Infor Integration 6.2. System Administrator's Guide for Java Message Services

Transcription

1 Infor Integration 6.2 System Administrator's Guide for Java Message Services

2

3 Copyright 2007 Infor Global Technology Solutions GmbH and/or its affiliates and subsidiaries All rights reserved. The word and design marks set forth herein are trademarks and/or registered trademarks of Infor Global Solutions Technology GmbH and/or its affiliates and subsidiaries. All rights reserved. All other trademarks listed herein are the property of their respective owners. Important Notices The material contained in this publication (including any supplementary information) constitutes and contains confidential and proprietary information of Infor Global Solutions. By gaining access to the attached, you acknowledge and agree that the material (including any modification, translation or adaptation of the material) and all copyright, trade secrets and all other right, title and interest therein, are the sole property of Infor Global Solutions and that you shall not gain right, title or interest in the material (including any modification, translation or adaptation of the material) by virtue of your review thereof other than the non-exclusive right to use the material solely in connection with and the furtherance of your license and use of software made available to your company from Infor Global Solutions pursuant to a separate agreement ( Purpose ). In addition, by accessing the enclosed material, you acknowledge and agree that you are required to maintain such material in strict confidence and that your use of such material is limited to the Purpose described above. Although Infor Global Solutions has taken due care to ensure that the material included in this publication is accurate and complete, Infor Global Solutions cannot warrant that the information contained in this publication is complete, does not contain typographical or other errors, or will meet your specific requirements. As such, Infor Global Solutions does not assume and hereby disclaims all liability, consequential or otherwise, for any loss or damage to any person or entity which is caused by or relates to errors or omissions in this publication (including any supplementary information), whether such errors or omissions result from negligence, accident or any other cause. Trademark Acknowledgements All other company, product, trade or service names referenced may be registered trademarks or trademarks of their respective owners. Publication Information Document code: U9050B US Release: Infor Integration 6.2 Publication date: July 07

4

5 Table of Contents Chapter 1 Introduction Purpose and scope Intended audience Overview JMS Definitions, acronyms, and abbreviations Chapter 2 JMS Architecture Java Naming and Directory Interface Composition of a complete JMS application Point-to-Point Model Chapter 3 Configuration of messaging system Overview To configure WebSphere MQ To configure the JMSAdmin tool Environment variables To create default Administered JMS Objects To monitor Administered JMS Objects To create Administered JMS Objects manually Chapter 4 Adapter configuration for JMS Basic settings for JMS Bus Component configuration for JMS Message transport Queues Message queues...4-6

6 ii Table of Contents Deadletter queues Defaults Connection to the JMS provider Defaults Naming directory Default LDAP directory Default non-ldap directory Minimal configuration Chapter 5 Advanced configuration Directory and namespace references Provider URL and Initial Context Factory To configure a Bus Component for a namespace Anonymous clients Miscellaneous properties persistent timetolive JMS properties of a Bus Component s URI Properties Values and default values Lookup order for configuration data

7 About this Guide This document describes how you must configure Infor Integration for JMS to be able to use message-oriented middleware (MOM) as transport service for the request/reply communication in an Infor Integration connection. This document guide only considers WebSphere MQ as middleware, which is the enterprise-messaging product of IBM. Other messaging products are expected to work as well, but WebSphere MQ is the only product that is tested. Other JMS providers must also work, but please, contact Infor OnePoint Support before implementing another JMS provider. Java Message Service (JMS) is a Java API that enables users to access a variety of message-oriented middleware products, such as WebSphere MQ from IBM, SonicMQ from Progress Software, and WebLogic JMS from BEA. Through this API, applications based on the Java 2 Platform, Enterprise Edition (J2EE) can send messages to and receive messages from one of the queues of the messaging product. The messaging product manages the messages and the queues, and takes care of a reliable and secure message transport. This document contains the following chapters: Chapter 1, Introduction, introduces JMS and outlines how you can configure Bus Components, which represent the end points of an Infor Integration network, for messaging through JMS. Chapter 2, JMS architecture, describes the architecture of a JMS application and describes how Infor Integration uses JMS for message transport. Infor Integration employs the JMS Point-to-Point model for the request/reply communication between a client and a server. Chapter 3, Configuration of messaging software, explains in general terms how you must configure the enterprise messaging software as a JMS provider. The chapter cannot be specific, because the nature of the configuration depends on the used messaging software. However, the chapter presents some configuration examples for WebSphere MQ.

8 iv Table of Contents Chapter 4, Adapter configuration for JMS, describes how you must configure the Bus Components for clients and servers to access the enterprise messaging middleware through JMS. Chapter 5, Advanced configuration, describes the advanced features of the Bus Components configuration to fine-tune the message transport. Related documents Infor Integration 6.2 Installation Guide (U9018 US) Infor Integration 6.2 System Administrator's Guide for Generic Runtime Components (U9042 US) Online documentation of Infor Integration Send us your comments We continually review and improve our documentation. Any remarks/requests for information concerning this document or topic are appreciated. Please e- mail your comments to In your , refer to the document code and title. More specific information will enable us to process feedback efficiently.

9 Table of Contents v

10

11 Chapter 1 Introduction 1 Purpose and scope This guide describes how you must configure Infor Integration to be able to use JMS message-oriented middleware as message transport tier for the request/reply communication in an Infor Integration connection. JMS stands for Java Message Service and is a message API that enables a Java program to access a wide range of messaging products. WebSphere MQ supports JMS from version 5.2 onwards. Bus Components are the end nodes in an Infor Integration network, and consist of server and client computers. The general configuration of Infor Integration with the Central Configuration Console involves the set up of the Bus Components that employ JMS messages as transport device. You must specify for these components various message-related parameters, such as the name of the directory in which the administered JMS objects are kept, and the names of the administered JMS objects themselves. In the case of Infor Integration, the administered objects comprise the Queue Connection Factory and the various Queues used for the message transport. Note 1: Although all messaging products with a JMS provider are expected to work properly with Infor Integration, the JMS provider of WebSphere MQ is the only provider that is tested and supported. Note 2: If you use MQSeries 5.1, the predecessor of WebSphere MQ, you must use the legacy Java message interface of IBM. The IBM interface consists of the MQSeries Java package com.ibm.mq, which contains the com.ibm.mq.jar file

12 1-2 Introduction and the mqji<language code>.properties file. For the Infor Integration configuration for MQSeries 5.1 or earlier, contact Infor OnePoint Support from help at Note 3: This guide uses the terms Client Adapter and Server Adapter. The term Client Adapter refers to the client runtime component of Infor Integration that receives a request from the client application, forwards this request as a Bus Document to the involved Bus Component, and receives the reply. The term Server Adapter refers to the server runtime component of Infor Integration that receives the Bus Document with the client's request, handles the contained XML, invokes the server application and returns a Bus Document to the client with the server's reply. Intended audience This document is intended for application or system administrators who install, configure, and maintain Infor Integration software. Overview JMS Java Message Service (JMS) is a Java API that enables you to access a variety of Message Oriented Middleware products (MOM). The JMS provider implements JMS for a specific MOM and JMS providers are currently available for a wide range of message products, such as the following: WebSphere MQ (MQSeries) from IBM SonicMQ from Progress Software WebLogic JMS from BEA SmartSockets from Talarian FioranoMQ from Fiorano IBus MessageServer from SoftWired This document only considers WebSphere MQ.

13 Introduction 1-3 Through the JMS API, applications based on the Java 2 Platform, Enterprise Edition (J2EE) can send messages to and receive messages from one of the queues of a supported MOM. The MOM manages the messages and the queues, and takes care of a reliable and secure message transport. In the case of Infor Integration, the generic Infor Integration core represents the Java application that communicates with the MOM through the JMS interface. The configuration data of the message queues and the related components are kept in a naming directory, which the user can access through the Java Naming and Directory Interface (JNDI). The JNDI service provider can be a LDAP-compliant Directory Service, another type of naming or directory service, or just a flat data file. Which type of data store is used will partly be determined by the MOM and partly by the company s network configuration. A MOM-provider, for example, can supply a proprietary JNDI implementation, and a company can have an existing LDAP server that the company wants to leverage. Infor Integration accesses this naming directory to retrieve the required data and the message queues, such as the name of a queue and the name of the connection factory used to connect to a queue. Definitions, acronyms, and abbreviations Abreviation API BOI Bus Component Business Object Interface Client Adapter Description Application Programming Interface: A set of functions that can be called by other applications. Business Object Interface. A logical endpoint in a Infor Integration network, such as servers and named clients. Bus Components can be configured for certain connection points, pooling policies and activation services in the Central Configuration Console (CCC) of Infor Integration. Business Object Interface (BOI) is a standard methodology to connect Infor Integration objects with other applications. BOI makes data and functionality on a server available to a client. On the client side, the BOI consists of a BOI proxy, which forms a substitute for data and functionality of one or more business objects on the server (BOI implementation). The client runtime component of Infor Integration that receives a request from the client application, forwards this request as an XML message (Bus Document) to the involved Bus Component, and receives the reply from the back end.

14 1-4 Introduction Context (JNDI) Directory Service J2EE J2SE JMS JND JNDI LDAP LDAP Directory Service Message Message Queue MOM MQ name space (JNDI) A set of bindings with distinct atomic names, which is associated with a specific naming convention. A context provides a lookup operation that returns an object, and may provide operations such as for binding names. A network service that defines and manages resources (or other data) on a network and makes them accessible to users and applications. For Infor Integration, a Directory Service is used to centrally store the Bus Components and the associated configuration data for Infor Integration. Java 2 Platform, Enterprise Edition. Java 2 Platform, Standard Edition (successor to JDK), including the JVM for Java version and later. Java Message Service Java Naming Directory Java Naming and Directory Interface Lightweight Directory Access Protocol, a set of open industry protocols for accessing a Directory Service. A Directory Service that complies with the LDAP protocol. See also LDAP and Directory Service. Asynchronous requests, reports, or events that are consumed by client applications. These messages contain information required to coordinate these applications. A message has a header to which additional fields can be added and a body. The message header specifies standard fields and optional properties. The message body contains the data that is being transmitted. An intermediary holding place for messages created to facilitate the management of asynchronous exchange of messages across a (distributed) network. The various queues reflect the status of the message, such as Incoming, Outgoing, or Failed. Message Oriented Middleware Message Queue The set of all names in a naming system. naming system (JNDI) A connected set of name-object bindings of the same type that has the same naming convention and provides the same set of operations with identical semantics. Server Adapter The server runtime component of Infor Integration that

15 Introduction 1-5 Infor Integration Core receives a Bus Document with a request from a client, handles the contained XML, invokes the server application and returns a Bus Document to the client that contains the server's reply. The generic runtime core of the Infor Integration software that links enterprise applications that use Connectors and Adapters. The Infor Integration Core converts low-level syntax and complex data models into Business Objects. These Business Objects are exchanged between applications using Infor-specific XML messages called Bus Documents.

16

17 Chapter 2 JMS Architecture 2 Java Message Service (JMS) provides a common way for Java programs on the Java 2, Enterprise Edition (J2EE) platform to send and receive messages of an enterprise messaging system. JMS provides a set of interfaces (objects) and associated semantics that define how a Java program accesses the facilities of a messaging product. This type of Java program is called a JMS client. In the context of this document, the JMS clients are the Client and Server Adapters in the Infor Integration network that use JMS to transport messages with requests and replies. The JMS provider implements JMS for a particular enterprise messaging product. Each messaging system, therefore, has a unique JMS provider that is specific to that particular system. JMS clients use the message implementations of the JMS provider of the applied messaging system. Note: Enterprise messaging systems are often also referred to as Message Oriented Middleware (MOM). Java Naming and Directory Interface Java Naming and Directory Interface (JNDI) is an API that provides directory and naming functionality to Java applications, which is independent of any specific directory service implementation. As a result, you can access a variety of directories in a common way. JMS stores the configuration parameters of the administered objects in a repository that can be accessed trough the JNDI directory interface or the JNDI naming interface. The repository can be specific to the messaging product, or can be an external repository, such as a file system or an LDAP

18 2-2 JMS Architecture directory. Enterprise messaging systems and JMS clients access the directory through the Java Naming and Directory Interface (JNDI). Administered objects refer to objects of which the properties are defined, stored, and maintained (administered) in the JNDI namespace, using the messaging system. JMS administrators use provider-specific facilities to create and configure these objects. JMS clients use this namespace to look up the object properties. The administered properties involve various types of configuration parameters that are specific to the messaging system, such as queue locations, authorization data, encryption parameters, and the error handling settings. The messaging system and the JMS clients must know which type of naming system is used and where these clients can find this system. To indicate which naming system to use, you can specify system properties java.naming.factory.initial and java.naming.provider.url. The former provides the factory class that creates the initial context, which represents the starting point of the namespace, and the latter provides the name and address of the naming service. To connect to a naming service, you start with an InitialContext that points to the root of the namespace you use. You create an initial context object with the following constructor methods: public InitialContext() or public InitialContext(Hashtable environment) The latter constructor creates an initial context, using the environment supplied in the specified hash table. Environment property java.naming.provider.url provides the initial context with the name and address of the naming service, whereas the environment property java.naming.factory.initial specifies the class name of the initial context factory. If no arguments are passed to the constructor, the constructor uses the system property java.naming.factory.initial, which contains the class name of the initial context factory. The InitialContext constructor attempts to create the initial context specified therein. The environment of the initial context is then inherited by contexts that are derived from the context. All naming operations are relative to a context. The initial context implements the Context interface and provides the starting point for resolution of names. The Context interface is the principal interface of the JNDI API, which not

19 JMS Architecture 2-3 only specifies a naming context, but also defines basic operations such as adding a name-to-object binding, creating subcontexts, or looking up an object bound to a specified name. For more information on the InitialContext interface and the related environment properties, refer to the Java J2SE API Reference: Composition of a complete JMS application The previous sections in this chapter discussed JMS clients, JMS providers, and JMS administered objects. This section summarizes the building blocks of a full JMS application. A JMS application is composed of the following components: JMS Clients The Java programs that send and receive messages, using the JMS API. In the case of Infor Integration, the JMS clients are the Server Adapters and Client Adapters in the Infor Integration network that has been configured for JMS message transport. Non-JMS Clients The programs that use the native client API of the messaging system instead of the JMS API. Messages Messages defined by the application and used to communicate information between JMS clients. JMS Provider The messaging system that has been configured to support JMS. The system also possesses functionality to administer and manage messages and message queues.

20 2-4 JMS Architecture Administered Objects Message-related objects that are configured and maintained in the messaging system to be used by the JMS clients. The administered objects are stored in a JNDI namespace and accessed through the JNDI API. Point-to-Point Model To realize the request/reply communication between clients and servers, Infor Integration uses the JMS Point-to-Point model. This model is based on the concept of dedicated message queues. A JMS client sends messages to, and retrieves messages from, particular queues that are assigned to this client. Each client has therefore, essentially predefined queues to place or receive messages. The following JMS objects play a key role in the JMS Point-to-Point model: JMS Point-to-Point objects QueueConnectionFactory QueueConnection QueueSession QueueSender QueueReceiver Queue Description An administered object a client uses to create a connection. The object encapsulates a set of administratordefined connection configuration parameters. An active connection to a JMS Provider. A single-threaded context for sending and receiving messages. An object created by a QueueSession that is used to send messages to a destination (a queue). An object created by a QueueSession that is used to receive messages sent to a destination (a queue). An administered object that encapsulates the identity of a message destination.

21 JMS Architecture 2-5 The following figure depicts how you use the JMS Point-to-Point objects to realize the message transport between various JMS clients: The connection factories and queues are the administered objects of the Point-to-Point model. As a result, you must define, store, and maintain these objects in the JNDI directory, using the message system. How you must do this is specific to the messaging system you use. Chapter 3, Configuration of messaging system, outlines in general terms how you can accomplish this and also provides an example of how to define a connection factory and queues using IBM s WebSphere MQ. You must also inform the JMS clients, in our case the Server and Client Adapters, about the names of the administered objects. The Adapters require this information to be able to look up these objects in the directory and then use the objects properties. To provide the Adapters with the names of the administered objects, you must include the names in the URI of a Bus Component s connection. For more information on this subject, refer to Chapter 4, Adapter Configuration for JMS. The Adapters internally handle the use of the JMS Point-to-Point domain to realize the message transport between clients and servers. However, you will not encounter this issue, therefore, you can disregard this point.

22

23 Chapter 3 Configuration of messaging system 3 Overview The appropriate method to implement JMS support in an enterprisemessaging product includes the following steps: 1 Configure the messaging product as a JMS provider. The JMS provider implements JMS for a messaging product and handles the communication between the JMS API and the particular messaging product. 2 Define the connection factories and the queues in the Java Naming and Directory Interface (JNDI) namespace. The J2EE applications that send and receive messages through JMS (the JMS Clients, in our case the Client and Server Adapters) use these definitions. The following figure shows the implementation of a JMS provider that is specific to the messaging system and the configuration of a JNDI naming service that contains the JMS administered objects of that provider. The JNDI naming service you use can be a directory specific to the messaging system, or some other naming service, such as a file system or an LDAP directory.

24 3-2 Configuration of messaging system The following section provides an example of how you configure MQ JMS support in the WebSphere J2EE environment. Note: You can use essentially any messaging system for data transport between Adapters, as long as these messaging systems support JMS, which means that a JMS provider is available for these systems. However, the only messaging system tested by Infor Integration at the moment is WebSphere MQ of IBM. Contact Infor OnePoint Support before you use other JMS providers. To configure WebSphere MQ This section provides an example of how you must configure WebSphere MQ to implement JMS support, on a Windows platform. In the example, the administered JMS objects are defined and stored in Sun s LDAP-compliant naming directory (Sun ONE Directory Service). The configuration mainly consists of the set up of the JMSAdmin tool of WebSphere MQ and the application of this tool for administering JMS objects in the naming directory. For advanced configuration issues, refer to the WebSphere MQ documentation. First, you must have installed the following components of WebSphere MQ:

25 Configuration of messaging system 3-3 WebSphere MQ Server The software to create and run queue managers, and to handle the actual messaging. WebSphere MQ Client The software to run a WebSphere MQ Client. Java Messaging (including JMS support) The files required for messaging using Java, including IBM s MQ classes for Java and the JMS classes. Sun JRE Sun s Java Runtime Environment (JRE), which is required to run any of the WebSphere configuration tools. After you install these components, you must make various settings to run and configure WebSphere MQ successfully and deploy the JMS objects in LDAP. To configure the JMSAdmin tool The Java Message Service Administration (JMSAdmin) tool is a WebSphere tool to configure the JMS objects in a naming directory. To start the tool, you can run the Jmsadmin.bat file, which is present in the Java\bin subdirectory of the install directory of WebSphere MQ, which is usually C:\Program Files\IBM\WebSphere MQ. The following configuration example assumes that the JMS objects are kept in the LDAP-compliant Sun ONE directory. To connect to the directory service for administering objects, this executable file uses the settings defined in a configuration file called JMSAdmin.config. This file resides in the same directory and represents the default configuration file for the WebSphere MQ Classes for Java Message Service Administration Tool. You must first configure this file before you can run the JMSAdmin tool.

26 3-4 Configuration of messaging system The JMSAdmin.config file is extensively documented in the WebSphere MQ documentation. The following two properties are most relevant: INITIAL_CONTEXT_FACTORY=com.sun.jndi.ldap.LdapCtxFactory: Assuming you use Sun ONE Directory Server, you must set the Initial Context Factory property as shown here. Each JNDI service provider has a unique initial context factory, therefore, be sure to consult the respective service provider documentation to find what you must specify for this property. PROVIDER_URL=ldap://ldap.myorg.com/o=MyOrg The Provider URL contains the location of the JNDI provider, which consists of the name of the computer on which the LDAP server resides, and the root of the used namespace (initial naming context). In this example, ldap.myorg.com is the name of the computer and o=myorg is the namespace s root. You can change the other properties in this file for advanced configuration; however, for a basic configuration these properties can remain unchanged. Environment variables To run the JMSAdmin tool successfully, you must set the following environment variables: MQ_ROOT_DIR=C:\Program Files\IBM\WebSphere MQ MQ_JAVA_INSTALL_PATH=%MQ_ROOT_DIR%\java MQ_JAVA_LIB=%MQ_JAVA_INSTALL_PATH%\lib You must also add the following references to the classpath. Note that you must first remove all references to the old MQ Series based Jar files (version 5.1 or earlier) that were used for Adapter Suite 2.4 or earlier from the Classpath, if these files are still present. Classpath="%MQ_JAVA_LIB%\com.ibm.mq.jar;%MQ_JAVA_LIB%\connec tor.jar;%mq_java_lib%;%mq_java_lib%\jms.jar;%mq_java_lib%\co m.ibm.mqjms.jar;%mq_java_lib%\jndi.jar;%mq_java_lib%\ldap.ja r;%classpath%" To create default Administered JMS Objects After you make the settings described previously, you can add the administered JMS objects to the LDAP directory server in the following two ways:

27 Configuration of messaging system Create administered objects manually. To create the administered objects manually, you can use MQ Series commands interactively using the JMSAdmin tool. The following sections describe this option in detail. 2 Create administered objects using IVTSetup. Alternatively, you can use a file called IVTSetup.bat, which is located in the same directory as the JMSAdmin tool to create the administered objects automatically. You use the IVTSetup.bat file to create the following default objects: Queue Connection Factory Queue Topic Connection Factory Topic Afterwards, to query and modify these objects, you can use the JMS Admin tool, as described in the following sections. If you run the IVTSetup.bat, this results in the following output: In case of any errors, validate the settings of the environment variables, as discussed previously. If the Unable to bind object error occurs, this indicates that the objects being created are already present in the naming directory. In this case, proceed to the following section, To monitor JMS Administered Objects. Note: From the perspective of Infor Integration, you only need the Queue Connection Factory and the Queue objects, because Infor Integration currently does not support the JMS Publish-Subscribe model, in which the Topic Connection Factory and Topic objects are used.

28 3-6 Configuration of messaging system To monitor Administered JMS Objects You can start the JMSAdmin tool with the Jmsadmin.bat file. If everything is successful, the following prompt appears: If this prompt does not appear, an error probably occurred with the configuration of the JMSAdmin.config file or with the classpath settings. From this prompt, you can run WebSphere MQ commands to create and display the JMS objects. To view the objects created with IVTSetup, you use for example the display ctx command: The display ctx command shows all the objects that are administered in the naming context. In the previous command console, the last four entries are the objects that were created with IVTSetup, as indicated by the objects common name.

29 Configuration of messaging system 3-7 To create Administered JMS Objects manually You can create and manage the Administered JMS objects manually with the JMSAdmin tool, which enables you to give the objects logical names suited to the involved business process.

30 3-8 Configuration of messaging system To assign these names, you must issue the following WebSphere MQ commands from the InitCtx prompt: Command Short form Description alter alt Alter one or more properties of an administered object. Example: alter q(myq) expiry(1050) define def Create and store an administered object, or create a new sub-context. Example: define qcf(myqcf) define ctx(subcontext) display dis Display the properties of one or more administered objects, or the contents of the current context. Example: display q(*) Display ctx delete del Remove one or more administered objects from the namespace, or remove an empty sub-context. Example: delete q(myq) delete ctx(emptysubcontext) change chg Change the current naming context to enable the user to traverse the directory namespace anywhere below the initial context (root entry), pending security clearance. Example: change ctx(subcontext) copy cp Make a copy of an administered object and store the object under another name. Example: copy q(myq) q(mysecondq) move mv Rename an administered object. Example: move q(myq) q(yourq) end Close the JMS administration tool Example: end Note: For more detailed information about the commands, refer to the WebSphere MQ Using Java guide of the WebSphere MQ information center, which is installed along with the WebSphere software.

31 Configuration of messaging system 3-9 To define and display objects With the define command, you create of a Queue Connection Factory called ClientMQQCF, which means that a Queue Connection Factory reference is created and stored in the naming or directory service: define qcf(clientmqqcf) Next, you use also the define command to create a Queue object called ClientMQQueue: define q(clientmqqueue) Finally, you use the display command to check whether you created the objects successfully: display ctx The last two entries from the output, as shown in the following figure, display the manually created components. To retrieve information about an object, you once again use the display command and specify the particular object. To find out information about Queue Connection Factory ClientMQQCF, you must issue the following command from the InitCtx prompt: display qcf(clientmqqcf) The result of this command is shown in the following command console:

32 3-10 Configuration of messaging system The command lists for the specified object all properties and their values. To alter objects As you can see in the previous list, the QMANAGER property has no value, which implies the use of a default Queue Manager. You can, however, change the value for the QMANAGER or any other property with the Alter command in combination with the property name: alter qcf(clientmqqcf) QMANAGER(myQueueManager) After this modification, to view the result, you can use the display command again:

33 Configuration of messaging system 3-11 Similarly, you can modify the properties of a Queue object and subsequently view the result, for example: After you configure the required administered JMS objects, the JNDI setup is ready to be used for the JMS transport. The final step is to reference in the Bus Component s URIs to these JMS objects to configure the Adapters for JMS. The following chapter, Adapter configuration for JMS, describes the procedure that you must use to configure Infor Integration for JMS.

34

35 Chapter 4 Adapter configuration for JMS 4 Basic settings for JMS As described in Chapter 2, JMS Architecture, Infor Integration uses the Point-to-Point model of JMS to realize request/reply communication between Adapter clients and Adapter servers. To be able to use this model, you must provide the Adapter servers and clients with the following information: The JNDI namespace containing the administered JMS objects (the queues and the connection factory). To define the naming service and the namespace, you must specify: The name and address of the naming service, provided by JMS property java.naming.provider.url The class name of the initial context factory, provided by JMS property java.naming.factory.initial For more information about the JNDI namespace, refer to Java Naming and Directory Interface, in Chapter 2, JMS architecture. The QueueConnectionFactory object used to create a connection to a JMS provider. The object contains various connection configuration parameters defined by the JMS administrator. The Queue objects used for the message transport. A Queue object encapsulates a provider-specific queue name, and is the way in which a client specifies the identity of a queue to JMS API methods. Note: All examples of Infor Integration configuration for JMS assume an LDAPcompliant naming/directory service, which means that all references to JMS objects start with a cn= prefix, for example cn=myqueue. If, however, you

36 4-2 Adapter configuration for JMS apply another naming system, such as a file-based system, other naming rules prevail and you can probably leave out this prefix. The prefix may in fact even be illegal for some naming services. Bus Component configuration for JMS To pass the information about the naming directory, the connection factory, and the queues to the Infor Integration runtime components, you must include the information in the Uniform Resource Identifier (URI) of one of the Bus Component s Connection Points. The URI for JMS message transport has the following format: jms://v1.0/#get[<properties>] put[<properties>] The get section refers to the location where an Infor Integration component receives messages and, similarly, the put section refers to the location where an Infor Integration component puts messages. Both sections can include the following references: Queue The name of the queue to put or get messages, encapsulated by a Queue object. Connection The configuration of the connection to the JMS provider that owns that particular queue, encapsulated by a QueueConnectionFactory object. Directory The JNDI namespace used for looking up the Queue and ConnectionFactory objects. The namespace is specified by the initial context factory, property java.naming.factory.initial, and the naming provider URL, property java.naming.factory.initial. In addition, you can define a dead-letter queue, which is a queue to put messages that are not recognized by Infor Integration. After an explanation of how Infor Integration transfers messages using JMS, this chapter further discusses how you include references to the queues and connections in the URI of the Bus Component. How to configure various naming directories and anonymous clients in Infor Integration is discussed in the following chapter. This chapter also provides a complete overview of all JMS properties that you can use to configure a Bus Component.

37 Adapter configuration for JMS 4-3 Note: A Bus Component object represents an end node in an Infor Integration network, such as a named client or a server. The object encapsulates a set of configuration parameters required to connect to an Infor Integration client or Infor Integration server. For more information on the configuration of Bus Components, refer to the System Administrator's Guide for Generic Runtime Components and the Central Configuration Console online Help. Message transport After you configured Infor Integration for JMS support, you must specify the JNDI namespace and the JMS administered objects, so Infor Integration can use the Point-to-Point JMS provider to send a request and reply to messages between Infor Integration servers and Infor Integration clients.

38 4-4 Adapter configuration for JMS The following figure shows how an Adapter client sends a request message to an Adapter server at runtime: For each call from a client, the Bus Component of the server is known. When the Client Adapter dispatches a request message, the Adapter extracts the name of the destination queue from the URI of the server s Bus Component and sends this name along with the message to the JMS provider. The JMS provider forwards the message to specified queue of the messaging system (MOM). The MOM then handles the message and can transfer the message to some other queue, for example, because transformation or rerouting is required. After the MOM processes the request message, the message turns up in the queue where the Server Adapter expects the request. The server Adapter knows which queue this is, because the server s Bus Component s URI contains a reference to this queue. On arrival of a request, the JMS provider generates an event that triggers the Server Adapter to retrieve the message.

39 Adapter configuration for JMS 4-5 The following figure shows how a Server Adapter sends a reply message to a Client Adapter at runtime: The transfer of the reply message is similar to that of a request message, but now the direction is the other way around. The Server Adapter knows which client to address, because the client s Bus Component is sent along with the request. To find out to which queue the message must be sent, the Server Adapter retrieves the name of this queue from the URI of the client s Bus Component. Next, the MOM processes the message again and delivers the message on the queue the Client Adapter expects the replies. The URI of the client s Bus Components references this queue. Queues This section describes how to configure Adapter for the JMS Queues used for the message transport by including queue references in the Bus Component s URI. First, the queues are discussed that play a role in normal, successful message transport, and then the dead-letter queue is handled. Adapter uses

40 4-6 Adapter configuration for JMS the latter queue to store messages that Adapter does not understand, for example, because the format of the message is not supported. Message queues The request/reply communication between an Adapter client and an Adapter server involves four queues: The queue where the client puts a request (Q1) The queue where the server gets the client s request (Q2) The queue where the server puts a reply (Q3) The queue where the client gets the server s reply (Q4) The arrival of a message triggers an event upon which the client or server retrieves the message. The following figure depicts how these put and get queues are used for the transport of request and reply messages. The client sends a request to the queue Q1. The messaging system forwards the request to the queue from which the server gets all the requests (Q2). After processing the request, the server then sends a reply to the server s queue for replies (Q3). The server knows which client to reply to, because the client s Bus Component is sent along with the message. The messaging

41 Adapter configuration for JMS 4-7 system forwards the reply to the client s queue for replies (Q4). Finally, the client retrieves the reply from this latter queue. An obvious configuration of the messaging system is one in which the queue where the client puts a request coincides with the queue where the server gets this request, and in which the queue where the server puts a reply coincides the queue where the client gets this reply. In other words, a configuration that only uses two queues: one for the requests and one for the replies. The previous figure also illustrates how the Bus Components reference the involved queues: Q1 The name of the queue where the client puts a request is included in the put section of the URI of the server s Bus Component Q2 The name of the queue where the server gets the request of the client is included in the get section of the URI of the server s Bus Component Q3 The name of the queue where the server puts a reply is included in the put section of the URI of the client s Bus Component Q4 The name of the queue where the client gets the reply of the server is included in the get section of the URI of the client s Bus Component As a result, the URI of the client Bus Component will be as follows, if you reference all four queues and use the default connection factory and naming directory: jms://v1.0/#get[queue="cn=q4"] put[queue="cn=q3"] And for the server Bus Component: jms://v1.0/#get[queue="cn=q2"] put[queue="cn=q1"]

42 4-8 Adapter configuration for JMS This shorthand notation is for the queue references in the Bus Component s URI. The longhand notation for the client Bus Component is, for example: jms://v1.0/#get[queue={name= "cn=q2"}] put[queue={name="cn=q2"}] The longhand notation enables you to fill in additional queue properties, which specify the JNDI namespace used to look up the queues. For more information, refer to Naming directory, in this chapter. Deadletter queues The Deadletter queue is used to put messages that are received by an Adapter, but with which this Adapter does not know what to do. The reason why the Adapter might not know what to do with these messages can be because, for example, the messages do not conform to the syntax supported by Adapter, if the messages somehow got corrupted, or if the messages are unexpected at that address. In addition to the queues used for a successful request/reply communication between Adapters, you can specify in the get section of a Bus Component s URI which queue is used as a dead-letter queue for messages unrecognized by Adapter. In that case, the URI s syntax for dead-letter queue D is in shorthand notation: jms://v1.0/#get[queue="cn=myqueue", deadletterqueue = "cn=d"] Defaults The default queue name in the get section of a Bus Component s URI is temporary, without quotes, which is the reserved word for a temporary queue. A temporary queue is a queue that is created when a queue is required to get a message from. You can only specify a temporary queue in the get section of a Bus Component, because specifying a temporary queue in a put section would be pointless. You can put requests or replies in the temporary queue, but no application would know that it was expected to get the message from that temporary queue. The queue name in the put section of a Bus Component s URI defaults to the same queue as referenced in the get section. Note: A TemporaryQueue is a unique Queue object created for the duration of a QueueConnection. The TemporaryQueue is a system-defined queue that can only be deleted by the QueueConnection that created the queue.

43 Adapter configuration for JMS 4-9 Connection to the JMS provider When an Adapter sends a message through JMS, this message must be delivered at a specific pre-defined queue, which a JMS Queue object references. To reach this queue, the Adapter must first create a connection to the JMS provider that manages this queue. Usually, you only use one JMS provider. In this case, you do not have to be concerned about the connection, provided you previously created a QueueConnectionFactory object in the JNDI directory called cn = defaultqueueconnectionfactory, with no spaces. This object encapsulates all connection configuration properties required to connect to the JMS provider. And even if more JMS providers are used, Infor recommends that you create such an object for your default JMS provider, because it makes the configuration of an Adapter for JMS easier. If you use more JMS providers or if you do not have a QueueConnectionFactory called defaultqueueconnectionfactory, you must provide the Adapter with the information that is required to connect to the proper JMS provider. This connection configuration data is encapsulated by one of the QueueConnectionFactory objects stored in the JNDI namespace. You can pass on this data to an Adapter by including the name of a QueueConnectionFactory object in the URI of a Bus Component. For each message transport, Adapter must find out which connection to use. When you send a message, an Adapter consults for connection data the Bus Component at the other side of the transport, and when you receive a message an Adapter consults its own Bus Component. This implies that: When a Client Adapter sends a request, this Adapter looks in the put section of the Bus Component of the server When a Server Adapter sends a reply, this Adapter looks in the put section of the Bus Component of the client When a Client Adapter receives a reply, this Adapter looks in the get section of its own Bus Component When a Server Adapter receives a request, this Adapter looks in the get section of its own Bus Component This behavior of Adapter is similar to that with respect to queue references:

44 4-10 Adapter configuration for JMS Considering four different connections A, C, D, and F to queues Q1, Q2, Q3, and Q4, respectively, as shown in the previous figure, QueueConnectionFactory objects in the URI of the client Bus Component are referenced as follows: jms://v1.0/#get[queue="cn=q4", queueconnectionfactory = "cn=f"] put[queue="cn=q3", queueconnectionfactory = "cn=d"] The URI of the server Bus Component references to QueueConnectionFactory objects in the following way: jms://v1.0/#get[queue="cn=q2", queueconnectionfactory = "cn=c"] put[queue="cn=q1", queueconnectionfactory = "cn=a"] Defaults The default name of the QueueConnectionFactory object in the get section of a Bus Component s URI is defaultconnectionfactory. If this object does not exist in the used namespace and the name of the QueueConnectionFactory object is omitted in the URI, an error occurs. Adapter then does not know which connection to create to reach a particular queue. The default name of the QueueConnectionFactory object in the put section of a Bus Component s URI is the one specified in the get section of the same URI.

45 Adapter configuration for JMS 4-11 Naming directory Generally, for an Infor Integration connection, you use only one namespace of a particular naming directory to store, maintain, and retrieve administered objects, such as queues and connection factories. If that is the case, you are recommended to define this namespace as your default namespace, so you no longer must be concerned about specifying a namespace for each reference to an administered object in your Bus Component configuration. The following sections describe how you define a namespace in a naming directory as your default namespace. The section Directory and namespace references in Chapter 5, Advanced configuration, describes how to specify a directory and a namespace in the URI of a Bus Component. Default LDAP directory If you use an LDAP-compliant directory to store the administered objects, as default directory Adapter expects the Infor Integration LDAP directory, which is the Configuration Directory specified in owconfig.properties that is also applied to store Bus Components and other configuration data. You can view the URL of this directory with the graphical Support Information tool of Infor Integrations, or the Central Configuration Console, and you can change the directory s URL with the DirectoryURLEditor commandline tool. For more information, refer to the System Administrator's Guide for Generic Runtime Components and to the Central Configuration Console online Help. In addition, Adapter requires as default namespace a cn=jms node in the Infor Integration LDAP directory, which must be a sibling of the Central Configuration Console node (cn= configurations), both of which are children of the root node of Infor Integration s namespace, for example, o=mycompany.com, which is the root entry of the Directory URL you specified in owconfig.properties.

46 4-12 Adapter configuration for JMS The following figure shows where you must place the cn=jms node to make this node the default namespace for an Adapter when you use JMS. Note: If you use an LDAP Directory or namespace other than the Infor Integration default namespaces, you must refer to that directory or namespace in each Bus Component used for JMS message transport.