Guide to Queuing
|
A queuing client application can have a combination of sources and receivers.
To write queuing client applications, use standard Ultra Messaging programming practices. A UMQ queuing context must be able to establish broker connections. If the client application contains non-brokered sources or receivers, these sources or receivers must use a separate, non-brokered context.
Writing UMQ source and receiver applications includes creating brokered contexts, creating sources, creating receivers, and setting attributes by configuration files or other methods.
Coding examples are in C language.
Before starting to develop client applications, decide on a language, verify that the Ultra Messaging libraries work with your development environment, and determine a general approach for setting configuration options.
A client application that sends or receives messages must have one or more context objects.
When you create a brokered context, set the IP address and port of the broker, and configure the attributes in a context attribute object. After you create the context, you can delete the context attribute object. The following code fragments show context coding concepts.
Create a context attribute object with the current default configuration.
Set the configuration options that must be unique or permanent for the context. The following example sets configuration option broker to 10.29.3.190:5672.
Create the context object using the context attribute object.
Delete the context attribute object, which is no longer needed.
A client application that sends messages must have at least one source object.
When you create a source, configure the attributes in a topic attribute object. After you create the source, you can delete the topic attribute object. The following code fragments show source coding concepts.
Create a topic attribute object with the current default configuration. The topic name supplied should be the same as is passed to lbm_src_topic_alloc() below.
Set configuration options that must be unique or permanent for the source. The following example sets configuration option transport to BROKER.
Create a source topic object using the context and topic attribute object. The topic string becomes the queue name.
Delete the topic attribute object, or retain it for subsequent source topic allocation.
Create the source object using context and source topic object. An example of the function "app_src_callback" is shown below.
If needed, set the message properties for the message. In this example we set message property Price to a value of 170 and message property Quan to 49.
Send the message and delete the message properties object.
Verify that the source has registered with the broker. Verify that the sent message is stable at the broker.
A client application that receives messages must have at least one receiver object.
When you create a receiver, configure the attributes in a topic attribute object. The following code fragments show receiver coding concepts.
Create a receiver topic object using the context object with the current default configuration. The topic string is the queue name.
Create the receiver object using the context and topic object.
Ultra Messaging receives a message and then delivers the message to the application. The message might have message properties. After the callback delivers the message and returns, Ultra Messaging automatically tells the broker that the message is consumed.
Ultra Messaging has multiple ways to set configuration options. Determine which methods are most appropriate for your application.
You can set configuration options programmatically or with configuration files. You can set configuration options in the following ways:
For detailed information about setting configuration options, see Configuration Overview.
The UMQ package includes sample applications for testing and educational purposes.
For descriptions and argument information on example applications, as well as source code for all languages, see the C Examples source code, Java Examples source code, or .NET Examples source code documentation.
You can write messaging applications with the Java Message Service (JMS) API and programming model.
Use the Oracle JMS API to develop or port Java messaging applications written according to the JMS specification. The Oracle JMS Specification 1.1 contains requirements and guidelines for developing JMS- based Java messaging applications.
You can write Ultra Messaging and JMS applications that interoperate through the broker by setting and getting message properties.
The JMS message consists of a header and body. You can set a JMS body type in the application and optionally identify the body type in a header field.
The following table shows JMS message types and their Ultra Messaging message property JMS_UM_MessageType numeric values:
JMS Message Type | JMS_UM_MessageType Value |
---|---|
TextMessage | 0 |
BytesMessage | 1 |
MapMessage | 2* |
Message | 3 |
ObjectMessage | 4* |
StreamMessage | 5* |
When a broker delivers a message to an Ultra Messaging receiver, Ultra Messaging maps JMS message properties and header fields to Ultra Messaging message properties. When an Ultra Messaging source application sends a message to a broker, Ultra Messaging maps message properties to JMS message properties and header fields.
JMS header fields, JMS-defined properties, provider-specific properties, and user properties map to message properties in an Ultra Messaging message. JMS message data in the message body maps to data in an Ultra Messaging message.
The following figure shows how a JMS message maps to an Ultra Messaging message:
A JMS message header consists of the following header fields:
Ultra Messaging transports JMS message properties of the following categories:
The JMS Specification defines these properties and reserves the use of their names. JMS-defined properties use a "JMSX" prefix.
Ultra messaging defines and reserves the following provider-specific properties:
Properties that you define for applications. You can use User Properties as Message Selectors.