skip to main content
OpenEdge Development: AppBuilder
Data-Communication Objects : SmartProducers and SmartConsumers
 
SmartProducers and SmartConsumers
Progress Software provides you with two message-handling objects—the SmartProducer and SmartConsumer. The SmartProducer sends messages and the SmartConsumer receives them. With them, your ADM-compliant application can use the reliable Progress SonicMQ message service for communication within and between businesses. Figure 45 illustrates the place of the SmartProducer and SmartConsumer objects in the message-handling process.
Figure 45: The Smart Message-interface objects
SonicMQ is Progress Software Corporation’s implementation of the industry-standard Java Message Service (JMS). The SmartProducer and SmartConsumer communicate with the SonicMQ broker through the ABL-JMS API.
Creating and placing a SmartProducer instance
The SmartProducer is supplied as a precompiled master. Creating and placing an instance is a straightforward process.
To create and place an instance in the SmartProducer:
1. Click SmartProducer in the Object Palette.
2. Position the mouse cursor over an empty spot in your workspace and click to place the object. If you have one or more SmartB2BObjects or SmartSenders in place, AppBuilder opens an Advisor dialog box and offers to create OUTMESSAGE SmartLinks. Examine the offers and accept those that are appropriate.
3. Right-click the instance and choose Properties from the context menu. The Property Sheet dialog box appears:
4. Change the Object identifier (instance handle) to one that more accurately describes the role of this SmartProducer in your application.
5. Configure the instance. Save your work.
Configuring a SmartProducer instance
There are only a limited number of instance properties you need to configure.
To configure instance properties in the SmartProducer:
1. Begin by clicking the instance’s menu button and choosing Instance Properties. The SmartProducer Properties dialog box appears:
2. Change the default values that do not meet your needs:
*Domain — Defaults to Publish-and-Subscribe. Setting this value to Point-to-Point creates a single copy of the message. Although a number of entities might have access to the message, the first entity to read it removes it from the queue. With the Publish-and-Subscribe mechanism, a single copy of the message can be read by all subscribing entities. This allows implementation of a form of multicasting.
You cannot modify the Domain value at run time.
*JMS Partition — Select a JMS Partition from the dropdown list. If there are no JMS Partitions listed, you can define as many as you like using the Service Parameter Maintenance Tool, available on the PRO*Tools toolbar. For information about how to use that tool, see the online help.
*JMS User — Set this field to identify the user of the JMS Broker connection.
*JMS Password — Set this field to be the password that corresponds to the JMS user identifier.
*JMS Client ID — Set this field to a value unique to this client. This field is used to resolve ambiguities in cases where multiple clients might be using the same subscription and user names.
Note: If you do not know the User, Password, and Client ID values at design time, you can check the Prompt-for-JMS-Login box and the values will be collected at run time.
*Ping Interval — Defaults to 0 (pinging off). Setting this field to some integer value (representing seconds) causes the connection to the SonicMQ broker to be tested at that rate for the duration of the JMS session. It is good practice not to ping frequently, since pinging decreases overall system performance.
*Prompt for JMS Login — Defaults to cleared. Setting this check box causes the messaging object to prompt the user for login.
*Priority — Defaults to 4. The value is read whenever a new message is sent. It establishes the priority for that message in the range 0 (lowest) to 9 (highest). You can modify the value at run time under program control.
*Time to Live — Defaults to 0 (no expiration). This field is evaluated for every new message. It establishes the length of time in milliseconds that the message can remain unread before being discarded as stale. You can modify the value at run time under program control.
*Persistency — Defaults to PERSISTENT (message retained in the broker’s database). Other values supported are:
*NON_PERSISTENT (message not retained)
*NON_PERSISTENT_ASYNC
*UNKNOWN
*Message Type — Defaults to TextMessage. Other types supported are:
*BytesMessage — A stream of raw (uninterpreted) bytes. This is the default type when connecting to a SmartB2BObject; most other types require extra code.
*HeaderMessage — Known simply as type Message within the SonicMQ system. Use for shutdown messages.
*XMLMessage — A string representing an XML tree that can be parsed as a document. Do not use this type when connected to a SmartB2BObject.
*MapMessage — A set of name/value pairs, where names are of type string and values are Java primitives. You can read the entries in sequence or randomly by reference to the name.
*StreamMessage — A stream of Java primitives, read sequentially.
Creating and placing a SmartConsumer instance
The SmartConsumer is supplied as a precompiled master. Creating and placing an instance is a straightforward process.
To create and place an instance with the SmartConsumer:
1. Click SmartConsumer in the Object Palette.
2. Position your mouse cursor over an empty spot in your workspace and click to place the object. If you have a SmartRouter in place, AppBuilder opens an Advisor dialog box and offers to create a ROUTER SmartLink. If, instead, you have a SmartB2BObject or SmartReceiver in place, the Adviser will offer to create an INMESSAGE link. In either case, accept the offer unless it seems inappropriate.
3. Right-click the instance and choose Properties from the context menu. The Property Sheet dialog box appears:
4. Change the instance handle to one that more accurately describes the role of this SmartConsumer in your application.
5. Configure the instance. Save your work.
Configuring a SmartConsumer instance
There are only a limited number of instance properties you need configure.
To configure the limited number of instance properties with SmartConsumer:
1. Begin by clicking the instance’s menu button and choosing Instance Properties. The SmartConsumer’s instance properties dialog box appears:
2. Change the following default values that do not meet your needs:
*Domain — Defaults to Publish and Subscribe. Setting this value to Point-to-Point creates a single copy of the message. Although a number of entities might have access to the message, the first one that reads the message deletes it from the pipeline. With the Publish-and-Subscribe mechanism, all subscribing entities can read the message. This allows implementation of a form of multicasting.
The Domain value is not modifiable at run time.
*JMS Partition — Select a Partition from those listed. If there are no JMS Partitions listed, you can define as many as you like using the Service Parameter Maintenance Tool available on the PRO*Tools toolbar. For information about how to use that tool, see the online help.
*Ping Interval — Defaults to 0 (pinging off). Setting this field to some integer value in seconds causes the connection to the SonicMQ broker to be tested at that rate for the duration of the JMS session. It is good practice not to ping frequently, since pinging decreases system performance.
*Log File — Defaults to empty. Set this field to the pathname of the error-log file that will be used when running in batch mode.
*Shutdown — Defaults to empty. Set this field to the identifier for the Topic (Publish-and-Subscribe) or Queue (Point-to-Point) to be used for shutting down this SmartConsumer instance when running in batch mode. Sending any message to this destination causes this SmartConsumer object to begin the shutdown process.
*JMS User — Set this field to identify the user of the JMS Broker connection.
*JMS Password — Set this field to be the password that corresponds to the JMS User identifier.
*JMS Client ID — Set this field to a value unique to this client. This field is used to resolve ambiguities in cases where multiple clients might be using the same subscription and user names.
Note: You can supply the User, Password, and Client ID values at design time if you know them. Otherwise, check the Prompt-for-JMS-Login box and the object will prompt the user for them at run time.
*Prompt for JMS Login — Defaults to cleared. Setting this check box causes the object to prompt the user for login.
*Destination — Set this field to create/update an identifier for the destination Topic/Queue.
*Message Selector — If you wish to filter incoming messages according to values in header fields or properties, enter the expression here. The SmartConsumer object will perform the test on incoming messages and discard from the inbound queue/topic any messages that fail the test. Example: company_name = "ABC" AND priority < 4. Any message received from company ABC with a priority of 3 or less will be discarded without notice. The syntax is a subset of the syntax defined in SQL-92.
*Durable Subscription — Defaults to cleared. Enabled only when Domain is Publish-and-Subscribe. Set this check box to preserve the current subscription across JMS sessions.
*Subscription Name — Enabled only for Durable Subscriptions. Set this field to create/update a subscription name.
*Unsubscribe on Session Close — Defaults to cleared. Enabled only for Durable Subscriptions. Setting this check box causes the selected subscription to be cancelled when the JMS session ends.
Batch mode: starting and stopping a SmartConsumer
Three properties are generally required before running SmartConsumer object in batch mode, if SonicMQ security checking is turned on. They are JMSUser, JMSPassword, and ClientID. Strictly speaking, ClientID is not required except when needed to distinguish between sessions using the same user identifier and password.
At present, you can set those properties in the instance properties dialog box or from the command line using the -param startup parameter, as shown:
 
prowin32 -b -p containerfilename -param “jmsuser,jmspassword,clientid” .
In the example shown, containerfilename would be the filename of a simple SmartContainer that contains a SmartConsumer object and a SmartRouter object. The values you pass in the parameter string override any values set at design time using the Instance Properties dialog box.
Stopping a SmartConsumer
The most orderly way to shut down a SmartConsumer object running in batch mode is to send a message to the designated shutdown topic or queue. You identify that topic or queue at design time in the Shutdown property.
The shutdown message needs no body; its receipt by the shutdown Queue or Topic is sufficient.
When the SmartConsumer detects reception of a message in that Queue/Topic, it sends a shutdown message to its container object. Shutting down the container object shuts down all objects in the container (including the SmartConsumer itself) as well as any containers that were started by the SmartRouter to which the SmartConsumer is connected.
To set up and test a shutdown mechanism:
1. Create a simple SmartContainer.
2. Create and place a SmartProducer in the SmartContainer. Set Message Type to HeaderMessage and configure other properties appropriately.
3. Create and place a SmartSender in the SmartContainer. If an Advisor offers to create an OUTMESSAGE link to the SmartProducer, accept the offer; otherwise, create the link using the SmartLinks editor. Set the Destination property to be the shutdown destination for the consumer, for example “Shutdown”. Any message this SmartProducer sends will then be a shutdown message.
4. Open a Section Editor window and create a local override procedure called initializeObject. Insert the following RUN statement as the procedure body:
 
RUN sendMessage IN THIS-PROCEDURE.
5. Save your work using a distinctive filename, for example stopconsumer. To test this shutdown mechanism, enter this statement on the command line:
 
prowin32 -b -p stopconsumer.w