Web Methods Integration Server JMS Client Developer's Guide 7.1

(1)

Integration Server

Version 7.1

webMethods Integration Server JMS

Client Developer’s Guide

(2)

Cerebra, Glue, Infravio X‐Broker, Infravio X‐Registry, Infravio, My webMethods Server, My webMethods, webMethods Access, webMethods Administrator, webMethods Broker, webMethods Central Configuration, webMethods Dashboard, webMethods Designer, webMethods Developer, webMethods Fabric, webMethods Glue, webMethods Infrastructure Data Collector, webMethods Infravio X‐Broker, webMethods Infravio X‐Registry, webMethods Installer, webMethods Integration Server, webMethods logo, webMethods Mainframe, webMethods Manager, webMethods Modeler, webMethods Monitor, webMethods Optimize for Infrastructure, webMethods Optimize for Process, webMethods Optimize, webMethods Portal, webMethods Process Engine, webMethods Servicenet, webMethods Task Engine, webMethods Trading Networks, webMethods Workflow, and webMethods are either registered trademarks or trademarks of webMethods, Inc. Acrobat, Acrobat, and Reader are registered trademarks of Adobe Systems Incorporated. Amdocs and ClarifyCRM are registered trademarks of Amdocs. Ariba is a registered trademark of Ariba, Inc. BEA, BEA WebLogic Server, Jolt, and Tuxedo are registered trademarks, and BEA WebLogic Platform is a trademark of BEA Systems, Inc. Action Request System, BMC Software, PATROL, and Remedy are registered trademarks of BMC Software, Inc. BroadVision is a registered trademark of BroadVision, Inc. Chem eStandards and CIDX are trademarks of CIDX, The Chemical Industry Data Exchange. SiteMinder and Unicenter are registered trademarks of CA, Inc. PopChart is a registered trademark of CORDA Technologies, Inc. Kenan and Arbor are registered trademarks of Alcatel‐Lucent. Data Connection and SNAP‐IX are registered trademarks of Data Connection Corporation. D&B and D‐U‐N‐S are registered trademarks of Dun & Bradstreet Corporation. Eclipse is a trademark of Eclipse Foundation, Inc. Entrust is a registered trademark of Entrust, Inc. papiNet is a registered trademark of the European Union and the United States. Financial Information eXchange, F.I.X, and F.I.X Protocol are trademarks of FIX Protocol Ltd. UCCnet and eBusinessReady are registered trademarks, and 1SYNC and Transora are trademarks of GS1 US. Hewlett‐Packard, HP, HP‐UX, OpenView, PA‐ RISC, and SNAplus2 are trademarks of Hewlett‐Packard Company. i2 is a registered trademark of i2 Technologies, Inc. AIX, AS/400, CICS, ClearCase, DB2, Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, OS/400, RACF, RS/6000, SQL/400, S/390, System/390, VTAM, and WebSphere, and z/OS are registered trademarks; and Communications System for Windows NT, DB2 Universal Database, IMS, MVS, and SQL/DS are trademarks of IBM Corporation. InnoDB is a trademark of Innobase Oy. Itanium is a registered trademark of Intel Corporation. Linux is a registered trademark of Linus Torvalds. W3C is a registered trademark, and X Window System is a trademark of the Massachusetts Institute of Technology. MetaSolv is a registered trademark of Metasolv Software, Inc. ActiveX, Microsoft, Outlook, Visual Basic, Visual SourceSafe, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation. Six Sigma is a registered trademark of Motorola, Inc. Firefox and Mozilla are registered trademarks of the Mozilla Foundation. MySQL is a registered trademark of MySQL AB. nCipher is a trademark of nCipher Corporation Ltd. Eclipse is a trademark of Eclipse Foundation, Inc. Entrust is a registered trademark of Entrust, Inc. papiNet is a registered trademark of the European Union and the United States. Financial Information eXchange, F.I.X, and F.I.X Protocol are trademarks of FIX Protocol Ltd. UCCnet and eBusinessReady are registered trademarks, and 1SYNC and Transora are trademarks of GS1 US. Hewlett‐Packard, HP, HP‐UX, OpenView, PA‐RISC, and SNAplus2 are trademarks of Hewlett‐Packard Company. i2 is a registered trademark of i2 Technologies, Inc. AIX, AS/400, CICS, ClearCase, DB2, Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, OS/400, RACF, RS/6000, SQL/400, S/390, System/390, VTAM, and WebSphere, and z/OS are registered trademarks; and Communications System for Windows NT, DB2 Universal Database, IMS, MVS, and SQL/DS are trademarks of IBM Corporation. InnoDB is a trademark of Innobase Oy. Itanium is a registered trademark of Intel Corporation. Teradata is a registered trademark of NCR Corporation. Netscape is a registered trademark of Netscape Communications Corporation. ServletExec is a registered trademark, and New Atlanta is a trademark of New Atlanta Communications, LLC. SUSE is a registered trademark of Novell, Inc. Appia is a registered trademark and Javelin Technologies is a trademark of NYFIX, Inc. CORBA is a registered trademark of Object Management Group, Inc. JD Edwards, OneWorld, Oracle, PeopleSoft, Siebel, and Vantive are registered trademarks; and Infranet, PeopleSoft Pure Internet Architecture, Portal, and WorldSoftware are trademarks of Oracle Corporation. Perforce is a trademark of Perforce Software. JBoss and Red Hat are registered trademarks of Red Hat, Inc. PIP and RosettaNet are trademarks of RosettaNet, a non‐profit organization. SAP and R/3 are registered trademarks of SAP AG. PVCS is a registered trademark of Serena Software, Inc. SWIFT and SWIFTNet are registered trademarks of Society for Worldwide Interbank Financial Telecommunication SCRL. SPARC and SPARCStation are registered trademarks of SPARC International, Inc. BAAN and SSA are registered trademarks; and SSA Global is a trademark of SSA Global Technologies, Inc. EJB, Enterprise JavaBeans, Java, JavaServer, JDBC, JSP, J2EE, Solaris, Sun, and Sun Microsystems are registered trademarks; and Java Naming and Directory Interface, JavaServer Pages, SOAP with Attachments API for Java, and SunSoft are trademarks of Sun Microsystems, Inc. Sybase is a registered trademark of Sybase, Inc. VERITAS is a registered trademark, and VERITAS Cluster Server is a trademark of Symantec Corporation. UNIX is a registered trademark of The Open Group. Unicode is a trademark of Unicode, Inc. VeriSign is a registered trademark of Verisign, Inc. Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG. Other product and company names mentioned herein may be the trademarks of their respective owners. Copyright © 2007 webMethods, Inc. All rights reserved.

(3)

About This Guide

The webMethods Integration Server JMS Client Developer’s Guide is designed for the developer who is responsible for developing solutions that use webMethods Integration Server to send and receive messages using Java Messaging Service (JMS). This guide does the following: Explains how to establish connections to one or more JMS providers. Describes how to build a JMS trigger to use for receiving JMS messages. Explains how to build services that send and receive JMS messages using built‐in services. This guide assumes that you are familiar with the following: Basic concepts of webMethods architecture and terminology. Usage of webMethods Developer to create elements and build services. General knowledge of programming, the Java programming language, and the JMS API. Note: An in‐depth treatment of messaging architecture is beyond the scope of this guide, but is available elsewhere. For information about the JMS API, please refer to the Java Message Service, Version 1.1 specification on the Sun Microsystems Java Message Service (JMS) Web site. Note: With webMethods Developer, you can create Broker/local triggers and JMS triggers. A Broker/local trigger is trigger that subscribes to and processes documents published/delivered locally or to the Broker. A JMS trigger is a trigger that receives messages from a destination (queue or topic) on a JMS provider and then processes those messages. This guide discusses development and use of JMS triggers only. Where the term triggers appears in this guide, it refers to JMS triggers. For information about creating Broker/local triggers, see the Publish‐Subscribe Developer’s Guide.

(8)

Document Conventions

Additional Information

The webMethods Advantage Web site at http://advantage.webmethods.com provides you with important sources of information about webMethods products:

Troubleshooting Information. The webMethods Knowledge Base provides troubleshooting information for many webMethods products.

Documentation Feedback. To provide feedback on webMethods documentation, go to the Documentation Feedback Form on the webMethods Bookshelf.

Additional Documentation. Starting with 7.0, you have the option of downloading the documentation during product installation to a single directory called “_documentation,” located by default under the webMethods installation directory. In addition, you can find documentation for all webMethods products on the webMethods Bookshelf. Convention Description Bold Identifies elements on a screen. Italic Identifies variable information that you must supply or change based on your specific situation or environment. Identifies terms the first time they are defined in text. Also identifies service input and output variables.

Narrow font Identifies storage locations for services on the webMethods Integration Server using the convention folder.subfolder:service. Typewriter font Identifies characters and values that you must type exactly or messages that the system displays on the console. UPPERCASE Identifies keyboard keys. Keys that you must press simultaneously are joined with the “+” symbol. \ Directory paths use the “\” directory delimiter unless the subject is UNIX‐specific. [ ] Optional keywords or values are enclosed in [ ]. Do not type the [ ] symbols in your own code.

(9)

Overview . . . 10

Working with JNDI Providers . . . 10

Working with JMS Connection Aliases . . . 13

Creating Administered Objects . . . . 20

(10)

Overview

To configure Integration Server for JMS messaging, you need to: Create one or more JNDI provider aliases to specify where Integration Server can look up administered objects when it needs create a connection to JMS provider or specify a destination for sending or receiving messages. Create one or more connection aliases that encapsulate the properties that Integration Server needs to create a connection with the JMS provider. Integration Server also includes various server configuration properties that you can use to change the default server behavior. For a list of server configuration parameters related to JMS, see Appendix A, “JMS Server Configuration Parameters”.

Working with JNDI Providers

Each JMS provider can store JMS administered objects in a standardize namespace called the Java Naming and Directory Interface (JNDI). JNDI is a Java API that provides naming and directory functionality to Java applications. As the JMS client, Integration Server uses a JNDI provider alias to encapsulate the information needed to look up an administered object. When you create a JMS connection alias, you can specify the JNDI provider alias that Integration Server should use to look up administered objects (i.e., Connection Factories and Destinations).

Creating a JNDI Provider Alias

Use the following procedure to create an alias to a JNDI provider.

1 Open Integration Server Administrator if it is not already open. 2 In the Settings menu of the Navigation panel, click Messaging. 3 Under JMS Configuration, click JNDI Settings.

4 Click Create JNDI Provider Alias.

5 Specify the following information for the JNDI provider alias:

Note: If you connect directly to the webMethods JMS Provider using native webMethods API, you do not need to use a JNDI provider. Instead, you can create Destinations directly on the webMethods Broker. You do not need to create Connection Factories if you use the native webMethods API.

(11)

In this field... Specify...

JNDI Alias Name The alias name that you want to assign to this JNDI provider. Description A description for this JNDI alias. Predefined JNDI Templates The JNDI template that you want to use. The JNDI templates provide information that you can use to complete alias configuration for a specific provider. Note: After you create a JNDI provider, Integration Server Administrator displays Current Settings as the value of the Predefined JNDI Templates field. This indicates that Integration Server uses the currently specified settings for the JNDI provider alias.

Initial Context

Factory The class name of the JNDI provider. The JNDI provider uses the initial context as the starting point for resolving names for naming and directory operations.

If you selected a pre‐defined JNDI template, Integration Server displays the initial context factory for the provider.

Provider URL The URL of the initial context for sessions with the JNDI provider. The URL specifies the JNDI directory in which the JNDI provider stores JMS administered objects.

If you selected a pre‐defined JNDI template, replace the placeholder information in brackets << >> with information specific to your configuration.

Security Principal The principal name, or user name supplied by Integration Server to the JNDI provider, if the provider requires one for accessing the JNDI directory

For information about whether or not the JNDI provider requires security principal information, consult the product documentation for the JNDI provider.

(12)

6 Click Save Changes.

Editing a JNDI Provider Alias

Use the following procedure to edit an existing JNDI provider alias. 1 Open Integration Server Administrator if it is not already open. 2 In the Settings menu of the Navigation panel, click Messaging. 3 Under JMS Configuration, click JNDI Settings. 4 In the JNDI Provider Alias Definitions list, select the JNDI provider alias that you want to edit. Integration Server Administrator displays details about the JNDI provider alias.

5 Click Edit JNDI Provider Alias.

6 Edit the properties of the JNDI provider alias.

For more information about the fields, see “To create a JNDI provider alias” on page 10.

7 Click Save Changes. Security

Credentials The credentials, or password, that Integration Server provides to the JNDI provider, if the provider requires security credentials to access the JNDI directory.

For information about whether or not the JNDI provider requires security credentials, consult the product documentation for the JNDI provider.

Other Properties Any additional properties the JNDI provider requires for configuration. For example, you might need to specify the classpath for any additional .jar or class files that the JNDI provider needs to connect to the JNDI. When you select a pre‐defined JNDI template, Integration Server populates this field with any additional properties and placeholder information required by the JNDI provider. For more information about additional properties or classes required by a JNDI provider and the location of those files, see the product documentation for the JNDI provider.

In this field... Specify...

(13)

Deleting a JNDI Provider Alias

Use the following procedure to delete a JNDI provider alias. 1 Open Integration Server Administrator if it is not already open. 2 In the Settings menu of the Navigation panel, click Messaging. 3 Under JMS Configuration, click JNDI Settings. 4 Locate the alias you want to delete and click the icon in the Delete field. Integration Server displays a dialog box that prompts you to verify your action. Click OK to verify that you want to delete the JNDI provider alias.

Performing a Test Lookup for a JNDI Provider

Using Integration Server Administrator, you can perform a test lookup for a JNDI provider alias. The test lookup lists all of the Objects in the JNDI namespace referenced by the alias. 1 Open Integration Server Administrator if it is not already open. 2 In the Settings menu of the Navigation panel, click Messaging. 3 Under JMS Configuration, click JNDI Settings.

4 Locate the alias you want to delete and click the icon in the Test Lookup field. Integration Server returns a list of the Objects located in the JNDI namespace.

Working with JMS Connection Aliases

A JMS connection alias specifies the information that Integration Server needs to establish an active connection between Integration Server and the JMS provider. Integration Server uses a JMS connection alias to send messages to and receive messages from the JMS provider. Important! When you delete a JNDI provider alias, any service or JMS trigger that uses a JMS connection alias that relies on the JNDI provider alias will fail.

To delete a JNDI provider alias

(14)

Creating a JMS Connection Alias

When you create a JMS connection alias, keep the following points in mind: You can use JNDI to retrieve administered objects (Connection Factories and Destinations) and then use the Connection Factory to create a connection. If you intend to use a JNDI provider, you need to configure one or more JNDI provider aliases before creating a JMS connection alias. – or – You can use the native webMethods API to create the connection directly on the webMethods JMS Provider. You can also create Destinations at the webMethods Broker. If you intend to use the native webMethods API, you do not need to configure a JNDI provider alias. Each connection alias has an associated transaction type. Within Integration Server, certain functionality must be completed within a non‐transacted session. For example, to use Integration Server to send or receive large message streams, you must specify a JMS connection alias whose transaction type is set to NO_TRANSACATION. For more information about transaction types, see “Transaction Types” on page 118. 1 Open Integration Server Administrator if it is not already open. 2 In the Settings menu of the Navigation panel, click Messaging. 3 Under JMS Configuration, click JMS Settings.

4 Click Create JMS Connection Alias.

5 Set the following General Settings for the JMS connection alias: To create a JMS connection alias

For this field... Specify... Connection Alias

Name Name of the connection alias. Each connection alias represents a connection factory to a specific JMS provider. Description A description of the JMS connection alias.

Transaction Type Whether sessions that use this JMS connection alias will be transacted.

Select... To...

NO_TRANSACTION Indicate that sessions that use this JMS connection alias are not transacted.

(15)

6 In Create Connection Using list, select one of the following to indicate how administered objects (connection factories and destinations) will be looked up:

If you intend to use a JNDI provider, select JNDI Lookup and proceed to step 7. If you intend to use the native webMethods API to create the connection directly on the webMethods JMS Provider, select Native webMethods API and proceed to step 8.

7 If you selected JNDI Lookup in step 6, do the following in the remaining fields under Connection Protocol Settings:

a In the JNDI Provider Alias Name field, select the alias to the JNDI provider that you want to this JMS connection alias to use to look up administered objects. For information about creating a JNDI provider alias, see “Creating a JNDI Provider Alias” on page 10.

b In the Connection Factory Lookup Name field, specify the lookup name for the connection factory that you want to use to create a connection to the JMS provider specified in this JMS connection alias.

8 If you selected Native webMethods API in step 6, do the following in the remaining fields under Connection Protocol Settings:

LOCAL_TRANSACTION Indicate that sessions that use this JMS connection alias are part of a local transaction. XA_TRANSACTION Indicate that sessions that use this JMS connection alias are part of an XA transaction. Connection Client ID The JMS client identifier associated with the connections established by this JMS connection alias. User (optional) User name needed to acquire a connection from the

connection factory.

For more information about whether or not the JMS provider requires a user name and password to obtain a connection, refer to the product documentation for the JMS provider. Password

(optional) Password needed to acquire a connection from the connection factory. For more information about whether or not the JMS provider requires a user name and password to obtain a connection, refer to the product documentation for the JMS provider. For this field... Specify...

(16)

a Configure the connection to the Broker Server that you want to use as the webMethods JMS Provider for this JMS connection alias. For information about configuring a connection to a Broker Server, see the webMethods Integration Server Administrator’s Guide. b In the Client Group field, specify the name of the client group to which you want Integration Server to belong when it acts as a JMS client. The client group that you specify must already exist on the Broker Server. The default is IS‐JMS. c In the Broker List field, specify a comma delimited list of Broker Servers on which the connection between the Integration Server (acting as the JMS client) and the webMethods JMS Provider can exist. This provides connection failover. If a connection failure occurs to the first Broker Server in the list, a connection attempt will be made to the next Broker Server listed. Use the following format for each Broker: {Broker Name]@<host>[:port] 9 Under Advanced Settings, specify the following information for the JMS connection alias: Note: If a connection to a Broker Server is already configured (via Settings > Messaging > Broker Settings), Integration Server populates the fields under Connection Protocol Settings with information about that Broker Server. If that Broker Server functions as the webMethods JMS Provider, you may not need to edit any information. However, make sure that the Client Group field specifies the client group to which you want Integration Server to belong when it functions as a JMS client.

For this field... Specify...

Class Loader The name of the class loader that you want to use with this JMS connection alias. Integration Server will use the specified class loader when performing certain activities with the JMS connection alias (send a message, receive a message, create a connection, create a destination, etc.) By default, Integration Server uses the server class loader. However, you can specify the class loader for a package instead. This may be helpful when working with third party JMS providers. For example, you might place the third party jars needed for each JMS provider in separate packages, specifically, in the IntegrationServer_directory/packageName/code/jars directory. This can help prevent conflicts between the jars required for different JMS providers.

(17)

10 Click Save Changes.

Specifying a Retry Interval for Failed Connections

When a connection between Integration Server and the JMS provider fails, Integration Server attempts to re‐establish the connection automatically after a 20 second delay. You Maximum CSQ Size (number of documents) The maximum number of messages that can exist in the client side queue for this JMS connection alias. Integration Server writes messages to the client side queue if the JMS provider is not available when messages are sent. Each JMS connection alias has its own client side queue. Specify ‐1 if you want the client side queue to be able to contain an unlimited number of messages. That is, specify ‐1 if you do not want to set a maximum limit. If you specify 0, Integration Serverwill not write messages to the client side queue for this JMS connection alias.

Drain CSQ in Order Whether Integration Server drains the client side queue by sending the messages to the JMS provider in the same order in which Integration Server placed the messages in the client side queue. Select the check box if you want Integration Server to send messages from the client side queue in the same order in which Integration Server originally placed the messages in the client side queue. When the Drain CSQ in Order check box is selected, after the connection to the JMS provider is re‐established, Integration Server continues to write new messages to the client side queue until the client side queue is completely drained. If the Drain CSQ in Order check box is not selected, after the connection to the JMS provider is re‐established, Integration Server sends new messages directly to the JMS provider while it drains the client side queue. Note: You can also specify the number of messages Integration Server retrieves from the client side queue for delivery to the JMS provider at one time. By default, Integration Server sends 25 messages at a time. For more information about the watt.server.jms.csq.batchProcessingSize property, see Appendix A, “JMS Server Configuration Parameters”. For this field... Specify...

(18)

connection by changing the value of the watt.server.jms.connection.retryPeriod property. For more information about this property, see Appendix A, “JMS Server Configuration Parameters”. For information about modifying extended settings using Integration Server Administrator, see the webMethods Integration Server Administrator’s

Guide.

Specifying a Keep Alive Interval

Integration Server periodically pings the JMS provider to keep the connection between the Integration Server and the JMS provider active. The ping acts as a keep‐alive request. By default, Integration Server pings the JMS provider every 300 seconds. You can configure how frequently Integration Server pings the JMS provider by changing the value of the

watt.server.jms.connection.pingPeriod property. For more information about this property, see Appendix A, “JMS Server Configuration Parameters”. For information about modifying extended settings using Integration Server Administrator, see the webMethods

Integration Server Administrator’s Guide.

Editing a JMS Connection Alias

After you create a JMS connection alias, you might need to modify properties of the alias. For example, you might want to reduce the amount of memory that the client side queue can occupy by decreasing the maximum number of messages that can be placed in the client side queue. You can edit any properties of a JMS connection alias with the exception of the alias name and the method used to look up administered objects (Create Connection Using field). You must disable a JMS connection alias before you can edit it. 1 Open Integration Server Administrator if it is not already open. 2 In the Settings menu of the Navigation panel, click Messaging. 3 Under JMS Configuration, click JMS Settings. 4 In the JMS Connection Alias Definitions list, select the JMS connection alias that you want to edit. Integration Server Administrator displays details about the connection alias.

5 Click Edit JMS Connection Alias.

6 Edit the properties of the connection alias. For more information about the fields, see

“To create a JNDI provider alias” on page 10. Note that the Connection Alias Name and Create Connection Using fields cannot be modified.

7 Click Save Changes. To edit a JMS connection alias

(19)

Enabling and Disabling a JMS Connection Alias

When a JMS connection alias is enabled, Integration Server can use the alias to obtain connections, send messages, and receive messages on behalf of services and JMS triggers. When a connection alias is disabled, Integration Server stops all JMS triggers that use the alias. Additionally, any services that use a disabled JMS connection alias to send or receive messages will end in error. 1 Open Integration Server Administrator if it is not already open. 2 In the Settings menu of the Navigation panel, click Messaging. 3 Under JMS Configuration, click JMS Settings. 4 In the JMS Connection Alias Definitions list, disable the alias if it is not already disabled. 5 In the JMS Connection Alias Definitions list, do one of the following in the Enabled column: Click No if the alias is disabled and you want to enable it. If Integration Server cannot enable the alias, it displays a message under the alias indicating why Integration Server cannot enable the alias. Click Yes if the alias is enabled and you want to disable it.

Deleting a JMS Connection Alias

Before you delete a JMS connection alias, make sure of the following: The JMS connection alias is disabled. No services or JMS triggers rely on the JMS connection alias. If a JMS trigger uses a JMS connection alias, Integration Server will prevent the JMS connection alias from being deleted 1 Open Integration Server Administrator if it is not already open. 2 In the Settings menu of the Navigation panel, click Messaging. 3 Under JMS Configuration, click JMS Settings. 4 In the JMS Connection Alias Definitions list, disable the alias if it is not already disabled.

To enable or disable a JMS connection alias

(20)

5 Locate the alias you want to delete and click the icon in the Delete field. Integration Server displays a dialog box that prompts you to verify your action. Click OK to verify that you want to delete the JMS connection alias.

Creating Administered Objects

The JMS provider that you select should provide you with the tools to create and

configure administered objects in a JNDI namespace. Integration Server cannot be used to create and configure administered objects. For more information about working with administered objects, refer to the product documentation for your chosen JMS provider.

Load Balancing Topics

With the webMethods JMS Provider you can allow multiple JMS clients, each using its own session, to process messages from a single topic in parallel, on a first‐come, first‐serve basis. To allow load balancing of topics across clusters, the following must be true: To be load balanced, each topic must be configured to share state. This allows multiple connections to share the same connection client ID. The wmjms.properties file must contain the following system property: com.webmethods.jms.clientIDsharing=true The wmjms.properties file must be placed in the Integration Server classpath. A durable subscriber must be used to receive messages from the topic. For information about creating a JMS topic at the Broker and configuring it to be a shared state client, see the webMethods Broker Administrator’s Guide. For more information abut creating a wmjms.properties file to contain JMS provider‐specific properties, see the webMethods Messaging Programmer’s Guide.

(21)

JMS Messaging . . . 22 Messaging Styles . . . 22 JMS API Programming Model . . . 24

(22)

JMS Messaging

The Java Message Service (JMS) is a Java API that allows applications to communicate with each other using a common set of interfaces. JMS is part of the Java 2 Platform, Enterprise Edition (J2EE) suite. The JMS API provides messaging interfaces, but not the implementations. A JMS provider, such as the webMethods JMS Provider, is a messaging system that implements the JMS message interfaces and provides administrative and control features. It supports routing and delivery of messages through the implementation of the JMS API on the client. A goal of JMS is to maximize the portability of JMS applications across different JMS providers. JMS clients are the programs or components, written in Java, that produce and consume messages.

Messaging Styles

A messaging style refers to how messages are produced and consumed. JMS supports the publish‐subscribe (pub‐sub) and point‐to‐point (PTP) messaging styles.

Point-to-point (PTP) Messaging

In point‐to‐point (PTP) messaging, message producers and consumers are known as senders and receivers. The central concept in PTP messaging is a destination called a queue. A queue represents a single receiver. Message senders submit messages to a specific queue and another client receives the messages from the queue. In the PTP model, a queue may receive messages from many different senders and may deliver messages to multiple receivers; however each message is delivered to only one receiver.

(23)

Publish-Subscribe Messaging

In publish‐subscribe messaging, message producers and consumers are known as publishers and subscribers. The central concept in the publish‐subscribe messaging is a destination called a topic. Message publishers send messages of specified topics. Clients that want to receive that type of message subscribe to the topic. The publishers and subscribers never communicate with each other directly. Instead, they communicate by exchanging messages through a JMS provider Sending Clients

JMS Provider Receiving Client

Integration Server (Sender)

Order Entry Program (Sender) Queue Integration Server JMS Trigger (Receiver) Publishing Clients JMS Provider Subscribing Clients Integration Server (Publisher) Integration Server (Publisher)

Order Entry Program (Publisher) Topic Integration Server JMS Trigger (Subscriber) Integration Server JMS Trigger (Subscriber) Integration Server JMS Trigger (Subscriber)

(24)

Publishers and subscribers have a timing dependency. Clients that subscribe to a topic can consume only messages published after the client has created a subscription. In addition, the subscriber must continue to be active to consume messages. The messaging APIs relax this dependency by making a distinction between durable subscriptions and non‐durable subscriptions.

Durable Subscriptions

Durable subscriptions allow subscribers to receive all the messages published on a topic, including those published while the subscriber is inactive. When the subscribing applications are not running, the messaging provider holds the messages in nonvolatile storage. It retains the messages until either: The subscribing application becomes active, identifies itself to the provider, and sends an acknowledgment of receipt of the message. The expiration time for the messages is reached.

Non-durable Subscriptions

Non‐durable subscriptions allow subscribers to receive messages on their chosen topic, only if the messages are published while the subscriber is active. You generally use this type of subscription for any kind of data that is time sensitive, such as financial information.

JMS API Programming Model

The following section summarizes the most important components of the JMS API. The building blocks of a JMS application consist of the following: Administered objects (connection factories and destinations) Connections Sessions Message producers Message consumers Messages

Administered Objects

Administered objects are pre‐configured objects that an administrator creates for use with JMS client programs. Administered objects serve as the bridge between the client code and the JMS provider.

(25)

By design, the messaging APIs separate the task of configuring administered objects from the client code. This architecture maximizes portability: the provider‐specific work is delegated to the administrator rather than to the client code. However, the implementation must supply its own set of administrative tools to configure the administered objects. JMS administered objects are stored in a standardized namespace called the Java Naming and Directory Interface (JNDI). JNDI is a Java API that provides naming and directory functionality to Java applications. JNDI provides a way to store and retrieve objects by a user supplied name.

Types of Administered Objects

There are two types of administered objects: connection factories and destinations. Connection Factories A connection factory is the object a client uses to create a connection with a JMS provider. It encapsulates the set of configuration parameters that a JMS administrator defines for a connection. The type of connection factory determines whether a connection is made to a topic (in a publish‐subscribe application), a queue (in a point‐to‐point application), or can be made to both (generic connection), and whether messages are managed like elements in a distributed transaction in the client application. You use XA‐based connection factories in JMS applications managed by a J2EE application server, in the context of a distributed transaction. Destinations Destinations are the objects that a client uses to specify the target of messages it produces and the source of messages it consumes. These objects specify the identity of a destination to a JMS API method. There are four types of destinations; only the first two (queues and topics) are administered objects: Queue. A queue object covers a provider‐specific queue name, and is how a client specifies the identity of a queue to JMS methods. Topic. A topic object covers a provider‐specific topic name, and is how a client specifies the identity of a topic to JMS methods. TemporaryQueue. A queue object created for the duration of a particular connection (or QueueConnection). It can only be consumed by the connection from which it was created. TemporaryTopic. A topic object that is created for the duration of a particular

connection (or TopicConnection). It can only be consumed by the connection from

(26)

Connections

A connection object is an active connection from a client to its JMS provider. In JMS, connections support concurrent use. A connection serves the following purposes: A connection encapsulates an open connection with a JMS provider. It typically represents an open TCP/IP socket between a client and the service provider software. The creation of a connection object is the point where client authentication takes place. A connection object can specify a unique client identifier.

A connection object supports a user‐supplied ExceptionListener object.

A connection should always be closed once its use is no longer required.

Sessions

A session object is a single‐threaded context for producing and consuming messages. If a client uses different threads for different paths of message execution, then a session must be created for each of the threads. A session is used to create message producers, message consumers, temporary topics, and temporary queues; it also supplies provider‐optimized message factories. In JMS, a session provides the context for grouping a set of send and receive messages into a transactional unit.

Message Producer

A message producer is an object that a session creates to send messages to a destination (a topic or a queue).

Message Consumer

A message consumer is an object that a session creates to receive messages sent to a destination. A message consumer allows a client to register interest in a destination, which manages the delivery of messages to the registered consumers of that destination.

Message Selector

A client may want to receive subsets of messages. A message selector allows a client to filter the messages it wants to receive by use of a SQL92 string expression in the message header. That expression is applied to properties in the message header (not to the message body content) containing the value to be filtered. If the SQL expression evaluates to true, the message is sent to the client; if the SQL expression evaluates to false, it does not send the message.

(27)

Messages

Messages are objects that communicate information between client applications. Following are descriptions of several key concepts related to JMS messages.

Message Structure

Messages are composed of the following parts: Header. All messages support the same set of header fields. Header fields contain predefined values that allow clients and providers to identify and route messages. Each of the fields supports its own set and get methods for managing data; some fields are set automatically by the send and publish methods, whereas others must be set by the client.

Examples of header fields include:

JMSDestination, which holds a destination object representing the destination to which the message is to be sent.

JMSMessageID, which holds a unique message identifier value and is set automatically.

JMSCorrelationID, which is used to link a reply message with its requesting message. This value is set by the client application.

JMSReplyTo, which is set by the client and takes as a value a Destination object representing where the reply is being sent. If no reply is being sent, this field is set to null.

See the description of the Message interface in the Java Message Service, Version 1.1 specification for information about the complete set of message header fields and the methods for setting and getting their data. Properties (optional). Properties are used to add optional fields to the message header. There are several types of message property fields. Application‐specific properties are typically used to hold message selector values. Message selectors are used to filter and route messages. Standard properties. The API provides some predefined property names that a

provider may support. Support for the JMSXGroupID and JMSXGroupSeq is required; however, support for all other standard properties is optional. Provider‐specific properties are unique to the messaging provider and typically refer to internal values. Body (optional). JMS defines various types of message body formats that are compatible with most messaging styles. Each form is defined by a message interface: StreamMessage. A message whose body contains a stream of Java primitive values. It is filled and read sequentially.

(28)

MapMessage. A message whose body contains a set of name‐value pairs where names are Strings and values are Java primitive types. The entries can be accessed sequentially by enumerator or randomly by name. The order of the entries is undefined.

TextMessage. A message whose body contains a java.lang.String. ObjectMessage. A message that contains a Serializable Java object.

BytesMessage. A message that contains a stream of uninterpreted bytes. This message type is for literally encoding a body to match an existing message format. In many cases, it will be possible to use one of the other, self‐defining, message types instead.

Both StreamMessage and MapMessage support the same set of primitive data types. Conversions from one data type to another are possible.

Message Acknowledgment

A message is not considered to be successfully consumed until it is acknowledged. Depending on the session acknowledgment mode, the messaging provider may send a message more than once to the same destination. There are several message acknowledgment constants: Value Description AUTO_ACKNOWLEDGE _{Automatically acknowledges the successful receipt of a} message. CLIENT_ACKNOWLEDGE _{Acknowledges the receipt of a message when the client}

calls the message’s acknowledge() method.

DUPS_OK_ACKNOWLEDGE _{Instructs the session to automatically, lazily}

acknowledge the receipt of messages, which reduces system overhead but may result in duplicate messages being sent.

(29)

The JMS Services . . . 30 Sending a JMS Message . . . . 30 Sending a JMS Message and Waiting for a Reply . . . 34 Replying to a JMS Message . . . . 38 Receiving a JMS Message Using Built-In Services . . . 39 Sending a JMS Message as Part of a Transaction . . . 44 Setting Properties in a JMS Message . . . 46

(30)

The JMS Services

Using the following JMS services, you can create services that send and/or receive JMS messages. The JMS services are located in the WmPublic package.

Sending a JMS Message

When you build a service that sends a JMS message, you specify how Integration Server connects to the JMS provider, the message destination, and whether or not a client side queue should be used.

How to Send a JMS Message

The following describes the general steps you take to send a JMS message to a JMS provider.

1 Create an empty flow service. 2 Create the message body.

How you build the message body depends on the format that you want to use for the message. For example, if you want to use a String as the message body, create a field of type String and then add content to the String field. If you want to use a Document (IData) as the message body, create a document and then add content to the document. Note that a Document (IData) should only be used when sending a JMS message from one Integration Server to another If you want more control over the actual javax.jms.Message that Integration Server sends to the JMS provider, you can create a Java service that calls the Service Description pub.jms:acknowledge Sends an acknowledgment for a message to the JMS provider. pub.jms:createConsumer Creates a message consumer to receive messages from destinations on the JMS provider. pub.jms:receive Synchronously receives a message from a queue or topic on the JMS provider. pub.jms:reply Sends a reply message to a requesting client. pub.jms:send Sends a JMS message to the JMS provider. pub.jms:sendAndWait Sends a request in the form of a JMS message to the JMS provider and optionally, waits for a reply. pub.jms:waitForReply Retrieves the reply message for an asynchronous request.

(31)

com.wm.app.b2b.server.jms.producer.ProducerFacade class, which will create a javax.jms.Message. See: com.wm.app.b2b.server.jms.producer.ProducerFacade.createBytesMessage(String) com.wm.app.b2b.server.jms.producer.ProducerFacade.createMapMessage(String) com.wm.app.b2b.server.jms.producer.ProducerFacade.createObjectMessage(String) com.wm.app.b2b.server.jms.producer.ProducerFacade.createStreamMessage(String) com.wm.app.b2b.server.jms.producer.ProducerFacade.createTextMessage(String) The Java service calling this API must return an Object of type javax.jms.Message, which can then be mapped to the JMSMessage/body/message input parameter of the pub.jms:send service. When creating the javax.jms.Message with the com.wm.app.b2b.server.jms.producer.ProducerFacade, you can use the javax.jms.Message setter methods to set the values of the message headers and properties directly. You can also set the value of message headers and properties using the input parameters of the pub.jms* service that you use to send the message. If you set the message headers and properties both ways, the values provided to the pub.jms* service take precedence. Software AG recommends that you use a pub.jms* service to create and send the JMS message. This may provide better performance on average. However, if you want to send a StreamMessage or a MapMessage, you need to use the appropriate com.wm.app.b2b.server.jms.producer.ProducerFacade API. 3 Invoke pub.jms:send. This service creates a JMS message (javax.jms.Message) based on input provided to the service or takes an existing JMS message and sends it to the JMS provider.

4 Specify the JMS connection alias. The JMS connection alias indicates how Integration Server connects to the JMS provider.

5 Specify the destination to which you want to send the message.

If the JMS connection alias you specified in step 4 uses the native webMethods API to create the connection directly on the webMethods JMS Provider, you need to specify the destinationName as well as the destinationType Name Description connectionAliasName Name of the JMS connection alias that you want to use to send the message.

(32)

6 Set values for the header fields in the JMS message. All of the header fields are optional. If you created a javax.jms.Message and you set the message header fields using the javax.jms.Message setter methods, you do not need to provide inputs to the fields in JMSMessage/header. If you do set message header fields using both approaches, Integration Server uses the values provided as input to the pub.jms:send service. Name Description destinationName Name or lookup name of the Destination to which you want to send the message. Specify the lookup name of the Destination object when the JMS connection alias uses JNDI to retrieve administered objects. Specify the provider‐specific name of the Destination when the JMS connection alias uses the native webMethods API to connect directly to the webMethods JMS Provider. destinationType Specifies whether the Destination is a queue or a topic. The default is queue. Name Description deliveryMode Specifies the message delivery mode for the message. Specify one of the following: PERSISTENT provides once‐and‐only‐once delivery for the message. The message will not be lost if a JMS provider failure occurs. NON_PERSISTENT provides at‐most‐once delivery for the message. The message has no guarantee of being saved if a JMS provider failure occurs. The default is PERSISTENT priority Specifies the message priority. JMS defines priority levels from 0 to 9, with 0 as the lowest priority and 9 as the highest. The default is 4. timeToLive Specifies the length of time, in milliseconds, that the JMS provider retains the message. The default is 0, meaning that the message does not expire. JMSType Message type identifier for the message.

(33)

7 Set values for the Integration Server-specific properties. The properties fields are optional fields added to the message header and are often used to hold message selector values. Integration Server adds the following properties to JMS messages it sends. You can set these values as follows. If you created a javax.jms.Message and you set the message property fields using the javax.jms.Message setter methods, you do not need to provide inputs to the fields in JMSMessage/properties. If you do set message property fields using both approaches, Integration Server uses the values provided as input to the pub.jms:send service. 8 Add any custom properties to the JMS message.

To add a new property to JMSMessage/properties, click on the Pipeline tab. Select a data type for the property and assign it a name. Make sure to place the new property in the JMSMessage/properties field.

Assign a value to any custom properties that you add.

9 Map data to the body of the JMSMessage document. Specifically, map the field that contains the data you want to included in the message body to the field in JMSMessage/body with the appropriate data type. Name Description activation Specifies the activation ID for the message. A JMS trigger uses the activation ID to join together messages it receives. For more information about setting the activation, see “Assigning an Activation to a JMS Message” on page 46. uuid Specifies a universally unique identifier for a message. For more information about setting a UUID, see “Setting the UUID” on page 47.

Map to this field... If you...

string Used a field of type String for the message body content bytes Used a one‐dimensional byte array for the message body content. object Used a Serializable Java object for the message body content. data Used a Document (IData) for the JMS message body content. Keep in mind that the IData message format can only be used when sending a JMS message from one Integration Server to another. message Used a Java service to create an object of type javax.jms.Message.

(34)

10 Specify client side queueing. When client side queueing is enabled, Integration Server places messages in the client side queue if the JMS provider is not available at the time the pub.jms:send service executes.

Sending a JMS Message and Waiting for a Reply

Integration Server provides the pub.jms:sendAndWait service, which you can use to send a message and wait for a reply. You can use the pub.jms:sendAndWait service to issue a request/reply in a synchronous or asynchronous manner. In a synchronous request/reply, the service that sends the request stops executing while it waits for a reply. When the service receives a reply message, the service resumes execution. If the timeout elapses before the service receives a reply, Integration Server ends the request, and the service returns a null message that indicates that the request timed out. Integration Server then executes the next step in the flow service. In an asynchronous request/reply, the service that sends the request continues executing the steps in the service after sending the message. To retrieve the reply, the requesting flow service must invoke the pub.jms:waitForReply service. If the timeout elapses before the pub.jms:waitForReply service receives a reply, the pub.jms:waitForReply service returns a null document indicating that the request timed out. A service that contains multiple asynchronous send and wait invocations allows the service to send all the requests before collecting the replies. This approach can be more efficient than sending a request, waiting for a reply, and then sending the next request. Name Description useCSQ Indicates whether Integration Server places the sent message in the client side queue if the JMS provider is not available at the time the message is sent True specifies that Integration Server writes messages to the client side queue if the JMS provider is not available at the time this service executes. When the JMS provider becomes available, Integration Server sends messages from the client side queue to the JMS provider. False indicates that Integration Server throws an ISRuntimeException if the JMS provider is not available at the time this service executes The default is True.

(35)

How to Send a Request Message and Wait for a Reply

The following describes the general steps you take to build a service that sends a request message and then waits for a reply.

1 Create an empty flow service.

2 Create the message body. For more information about creating content for the body of a JMS message, see step 2 in the section “How to Send a JMS Message” on page 30. 3 Invoke pub.jms:sendAndWait. This service creates a JMS message (javax.jms.Message)

based on input provided to the service or takes an existing JMS message and sends it to the JMS provider.

4 Specify the JMS connection alias. The JMS connection alias indicates how Integration Server connects to the JMS provider.

5 Specify the destination to which you want to send the message.

If the JMS connection alias you specified in step 4 uses the native webMethods API to create the connection directly on the webMethods JMS Provider, you need to specify the destinationName as well as the destinationType.

6 Specify the destination to which message recipients should send the reply message. (Optional) If you do not specify a destination for reply messages, Integration Server uses a temporaryQueue to receive the reply. A temporaryQueue is a queue object created for the duration of a particular connection. Name Description connectionAliasName Name of the JMS connection alias that you want to use to send the message. Name Description destinationName Name or lookup name of the Destination to which you want to send the message. Specify the lookup name of the Destination object when the JMS connection alias uses JNDI to retrieve administered objects. Specify the provider‐specific name of the Destination when the JMS connection alias uses the native webMethods API to connect directly to the webMethods JMS Provider. destinationType Specifies whether the Destination is a queue or a topic. The default is queue.

(36)

If the JMS connection alias you specified in step 4 uses the native webMethods API to create the connection directly on the webMethods JMS Provider, you need to specify the destinationNameReplyTo as well as the destinationTypeReplyTo.

7 Set the request timeout. The timeout indicates how long Integration Server waits for a reply message. The timeout parameter only applies to synchronous send and wait requests.

8 Populate the JMS message. To populate the JMS message header, properties, and body, follow steps 5–9 in the section “How to Send a JMS Message” on page 30.

9 Determine whether the request is synchronous or asynchronous. The pub.jms:sendAndWait provides a parameter that you can set to indicate whether the request is synchronous or asynchronous. By default, the request is synchronous. Name Description destinationNameReplyTo Name or lookup name of the Destination to which you want the reply message sent. Specify the lookup name of the Destination object when the JMS connection alias uses JNDI to retrieve administered objects. Specify the provider‐specific name of the Destination when the JMS connection alias uses the native webMethods API to connect directly to the webMethods JMS Provider. destinationTypeReplyTo Specifies whether the Destination is a queue or a topic. The default is queue. Name Description timeout Time to wait (in milliseconds) for the response to arrive. If no value is specified, the service does not wait at all.

Web Methods Integration Server JMS Client Developer's Guide 7.1

Integration Server

Version 7.1