        |  |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
JMS Connect User's Guide
CHAPTER 3
This chapter outlines the process of creating a JMS Component for use in an exteNd web service. At the same time, the semantics and usage of message header fields and properties are discussed in the context of JMS messaging; and tips are given for making the most effective use of JMS-based exteNd web services. You should familiarize yourself with this chapter before creating and deploying web services that rely on components created with the JMS Connect.
Creating a JMS component requires that you know the answers to the following questions:
Which XML template documents (and/or COBOL copybooks) will you to need in order to map data into or out of messages? (For more information on XML Template resources, see Creating a New XML Template in the Composer User's Guide.)
Which JMS Connection resource will your component(s) use? As part of the process of creating a JMS component, you can select an existing JMS connection, or you can create a new one. (If you create the connection beforehand, then it is available to all new JMS components.) See the previous chapter for step-by-step information on how to set up a JMS Connection resource.
Will you be creating a Browse Messages action? (See "The Browse Messages Action".) If so, you will need to choose a queue connection as your connection resource. Browsing is not defined on topic connections.
Will your service be triggered by messages arriving at a queue/topic? If so, you will need to deploy your service as a JMS Service. (See The JMS Service.)
Will your message session be transacted? If you intend to issue Commit or Rollback commands, you must enable transactions in the particular JMS Connection Resource you intend to use (by checking the "Transacted" checkbox in the Connection Resource setup wizard). For more information, see the discussion of the "Transacted" checkbox on page 29.
Will you be sending messages, or receiving them? You can send as well as receive messages inside of a single JMS Component—but only if the same queue (or connection resource) is used. If you will be sending or receiving to/from two or more different queues or topics, you must create separate components: one for each connection resource.
To create a new JMS Component:
Select File>New>xObject then open the Component tab and select JMS. The "Create a New JMS Component" Wizard appears.
Click Next. The XML Templates Info panel of the "Create a New JMS Component" Wizard appears.
Specify the Input and Output templates as follows.
Type in a name for the template under Part if you wish the name to appear in the DOM as something other than "Input".
Select a Template Category if it is different than the default category.
Select a Template Name from the list of XML templates in the selected Template Category.
To add additional input XML templates, click Add and choose a Template Category and Template Name for each.
To remove an input XML template, select an entry and click Delete.
Select an XML template for use as an Output Part using the same steps outlined above.
NOTE: You can specify an input or output XML template that contains no structure by selecting {System}{ANY} as the Input or Output template. For more information, see "Creating an Output Part without Using a Template" in the User's Guide.
Click Next. The XML Temp/Fault Template Info panel of the New HP3000 Terminal Component Wizard appears.
If desired, specify a template to be used as a scratchpad under the "Temp Message" pane of the dialog window. This can be useful if you need a place to hold values that will only be used temporarily during the execution of your component or are for reference only. Specify the templates as indicated in Step 6 above.
Under the "Fault Message" pane, select an XML template to be used to pass back to clients when an error condition occurs.
As above, to add additional temp or fault XML templates, click Add and choose a Template Category and Template Name for each. Repeat as many times as desired. To remove an XML template, select an entry and click Delete.
Click Next. The Connection Info panel of the "Create a New JMS Component" Wizard appears.
Select a Connection type from the pulldown list. (The pulldown list choices reflect the available JMS Connection Resources that were created earlier. For more information on creating JMS Connection Resources, see "Creating a JMS Connection Resource" on page 23).
Click Finish. The component is created and the JMS Component Editor appears.
The JMS Component Editor is similar in appearance to the XML Map Component Editor window (and in fact includes all the functionality of the XML Map Component Editor, plus additional Action types specific to messaging). Like all other Component Editors, the JMS Component Editor window includes an Action Model pane (which is typically in the lower right corner, although it doesn't have to be), a Native Environment pane (upper right), and mapping panes for input, output, and/or temporary DOMs.
The Native Environment page appears as a grey pane until you create or highlight a Message Action, at which time it displays a message status pane containing either two or three tabs, depending on whether the current Message Action involves browsing, sending, or receiving.
If you activate the Action menu (or do a right-mouse-click inside the Action Model pane) and select New Action, you will see that all of the same actions that are available in the XML Map Component are also available in the JMS Component, but with four new action types:
The four JMS-specific actions are the subject of the next chapter.
The JMS Component Editor's Native Environment pane (which is initially grey) will display various types of information associated with a message whenever a JMS Message Action is highlighted in the Action Model pane. The available categories of information (indicated by tabs at the top of the pane) include Message Body, Message Header, and Message Filter. The first two categories are common to all message actions (Send, Receive, and Browse). The Message Filter category, however, is visible only for Receive and Browse.
In the above illustration, the Message Header tab has been selected (with a Receive Message action highlighted in the Action Model pane). The Native Environment pane has been enlarged to show all available message headers and properties. For information on message header and property field usage, see "Message Headers and Properties" on page 127.
When the Message Body tab is selected, the Native Environment Pane will display content in a manner appropriate to the body type. For example, if the message contains an XML document, the Native Environment Pane will display a DOM tree; whereas if the message contains a COBOL copybook, it will display the contents of the copybook. See "Actions Unique to the JMS Component Editor"(starting on page 48) for additional information.
When the Message Filter tab is selected, the Native Environment Pane will display a selector-edit area. See "Working with Message Filters (Selectors)" on page 94 for more information.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
