Initializing and Monitoring APIs

This section describes how to initialize the PubSub+ Messaging API and provides information for using PubSub+ Messaging API logging and session statistics.

Initializing APIs

To work with a PubSub+ Messaging API, it must first be initialized.

PubSub+ Messaging API for Java RTO, C, and .NET

Call a function or method listed in the table below to initialize the PubSub+ Java RTO API, PubSub+ C API, or PubSub+ .NET API. When these PubSub+ Messaging APIs are initialized, you can optionally set the initial log level filter for all log categories so that only logs at a specified level and more severe are emitted. (For more information on logging levels, see Configuring Logging.)

You can also set the global buffer sizes for the memory pools that are used to temporarily save messages in the application space (for the PubSub+ Java RTO API, see Modifying the Global Pool Buffer Sizes; for the PubSub+ C API, see PubSub+ C API Best Practices; for the PubSub+ .NET API, see Modifying the Global Pool Buffer Sizes).

PubSub+ Messaging API for JavaScript and Node.js

Call the function listed in the table below to initialize the PubSub+ JavaScript API and PubSub+ Node.js API. By default, when these APIs are initialized, they include the version 7 behavior profile for backwards compatibility. Behavior profiles allow old applications to remain compatible with old versions of the API, while allowing new applications to take advantage of updated recommended defaults. When writing a new application, Solace recommends using the newest available profile. For example, if version 10 is the newest profile, add the following to the entry point of your application to initialize the API with the version 10 profile and run it with the default property values that Solace recommends at the time of the version 10 release:

var factoryProps = new solace.SolclientFactoryProperties();
factoryProps.profile = solace.SolclientFactoryProfiles.version10;
solace.SolclientFactory.init(factoryProps);

When modifying an existing application to use a new behavior profile, the differences between behavior profiles should be considered.

To Initialize a PubSub+ Messaging API
PubSub+ Messaging API	Use
PubSub+ Java RTO API	`Solclient.init(...)`
PubSub+ C API	`solClient_initialize(...)`
PubSub+ .NET API	`ContextFactory.Instance.Init(...)`
PubSub+ JavaScript API and PubSub+ Node.js API	`solace.SolclientFactory.init(...)`

Related Samples

For an example of how to initialize the PubSub+ Java RTO API or PubSub+ C API, see the DirectPubSub sample for that API. For the PubSub+ .NET API, see SampleApp. For the PubSub+ JavaScript API and PubSub+ Node.js API, see the TopicSubscriber and TopicPublisher samples.

Cleanup

When the client application is finished using the PubSub+ C API or PubSub+ .NET API, it should perform a global clean-up, which automatically frees all allocated resources, including those allocated for contexts and sessions that have been previously created but are not destroyed.

To Cleanup When Finished With the PubSub+ Messaging API
PubSub+ Messaging API	Use
PubSub+ JCSMP API	Not applicable
PubSub+ Java RTO API	Not applicable
PubSub+ C API	`solClient_cleanup()`
PubSub+ .NET API	`ContextFactory.Instance.Cleanup()`
PubSub+ JavaScript API and PubSub+ Node.js API	Not applicable

Contexts and sessions should always be destroyed or disposed before a cleanup is performed. If solClient_cleanup() or ContextFactory.Cleanup() is called while sessions are connected, any messages buffered for transmission are discarded and not sent.
Note that invocations of “initialize” and “cleanup” are reference counted. For example, if “initialize” is called twice, “cleanup” must be called twice to properly free the resources.
In the .NET environment, the .NET garbage collector may attempt to release IMessage containers after the application has called ContextFactory.Cleanup(). This will cause warnings like “2012-08-07 19:11:50Z - Warn - Sdk:Bad msg_p pointer (0000000004000FE1) in solClient_msg_free”. These warnings may be disregarded because they indicate that the API has detected and avoided a double-free.
However, if the same application calls ContextFactory.Init() subsequent to ContextFactory.Cleanup(), the garbage collector may release messages that have been re-assigned to the newly initialized ContextFactory, and this will lead to an application crash. Therefore, it is recommended that you only call ContextFactory.Init()/ContextFactory.Cleanup() once.

Related Samples

For an example of how to perform a global cleanup for the PubSub+ C API, see the DirectPubSub sample. For the PubSub+ .NET API, see SampleUtils.cs included with the sample files.

Provide feedback