Creating and Destroying Broker Clients

Creating a Broker Client will establish a connection between your application and a Broker. This connection is identified by the following tuple:

Multiple Broker clients within a single application that connect to the same Broker will all share a single network connection, as described in Sharing Connections.

Your application may create a Broker client by calling the awNewBrokerClient function and specifying these parameters:

The name of the Broker to which you wish to connect. You may specify a NULL value if you want to connect to the default Broker. The default Broker for a particular host is determined by your webMethods Broker administrator.

A unique client ID for identifying your Broker client. You may specify NULL value if you wish the Broker to generate a unique client ID for you. The client ID generated by the Broker can be obtained after this call completes by calling the awGetClientID function.

The client group for your new Broker client. Client groups define the event types your new Broker client will be able to publish or retrieve, as well as the life cycle and queue storage type for your Broker client. Client groups are defined by your webMethods Broker administrator.

The name of the application that is creating the Broker client. This name is used primarily by webMethods Broker administration and analysis tools. The application name can be any meaningful string of characters you choose.

A connection descriptor to use for the new Broker. If you specify NULL, a new connection descriptor will be created for you. Connection descriptors are covered in detail in Broker Connection Descriptors.

The example below contains an excerpt from the publish1.c sample application that shows the use of the awNewBrokerClient function. In this example, a NULL Broker name is passed to indicate that the caller wishes to connect to the default Broker on the host "localhost."

A NULL client ID is specified, indicating that the Broker should generate a unique client ID. A client group named "default" is requested and the application name is set to "Publish Sample #1." A NULL connection descriptor is passed, indicating that the caller wishes a default connection to be established. The last parameter is used to return the BrokerClient reference, since the return value of the function represents the overall success or failure of the function call.

The following example illustrates how to create a Broker client:

#include "aweb.h"
. . .
char *Broker_host = "localhost";
char *Broker_name = NULL;
char *client_group = "default";
. . .
int main(int argc, char **argv)
{
BrokerClient c;BrokerError err;
. . .
/* Create a client */
err = awNewBrokerClient(broker_host, broker_name,
NULL, client_group, "Publish Sample #1",NULL, &c);
if (err != AW_NO_ERROR) {
printf("Error on create client\n%s\n", awErrorToString(err));
return 0;
}
. . .