JMS URI scheme

The VersaLex JMS URI is for using Java Message Service (JMS) queues instead of local file system files for payload sent to and/or received from trading partners.

The basic format of the JMS URI is:

jms:jndi:jmsQueueName?param1=value1&param2=value2&param3=…

Example:

jms:jndi:OutboxQueue?msgFilename=test.edi&jndiConnectionFactoryName=ConnectionFactory&
jmsSelector=(SomeProperty=’abcd’)&filenameProp=filename

The JMS URI system interface has these important qualifications:

1. VersaLex JMS URI only supports Java Naming and Directory Interface (JNDI) connections to JMS providers.
2. JMS supports many different message types: BytesMessage, TextMessage, StreamMessage, MapMessage, ObjectMessage, and Message. VersaLex JMS URI only supports the BytesMessage message type. All other message types in the queue will be ignored and remain in the queue.
3. JMS supports Topics as well as Queues. VersaLex JMS URI only supports Queues.
4. If necessary, a custom JMS URI can be created which could support any of the items not supported above.

Optional parameters specified in the URI include the following:

jndiConnectionFactoryName=

This parameter is the connection factory name within JMS. Since there can be multiple connection factories within a single JMS, this parameter is typically required.

jndiInitialContextFactory=

This parameter is the initial context factory name. With some JMS implementations, such as GlassFish, this parameter does not need to be specified as it will be automatically determined during the call to javax.naming.InitialContext().

jndiURL=

This parameter is the JNDI URL. With some implementations, such as GlassFish, this parameter does not need to be specified as it will be automatically determined during the call to javax.naming.InitialContext().

ctxProps=

This parameter is used to specify additional properties that will be used during the call to javax.naming.InitialContext(environment). InitialContext is used when making a connection to the JMS provider.

connectionID=

This parameter is used to specify a connection ID to reference properties from the properties file specified in the system property cleo.uri.jms.connectionFile.

filenameProp=

JMS does not have a set place to store a filename for a message. This parameter specifies the name of a String Property to hold the filename for a message. If this property is not present, then no filename will be saved into sent messages. If this property is not present when reading from the queue, the filename will be based on the JMS message ID.

msgFilename=

This parameter is used to specify the filename for a PUT, GET, PUT+GET, or LCOPY command. It is used in conjunction with the filenameProp parameter. When used as the source for a command, the filename can be a wildcard or regular expression.

maxMessages=

This parameter is used to specify the maximum number of messages that will be read from the queue. Please note that if a JMS selector is used, the number of messages matching that selector will be returned. If a JMS selector is not used and a filename wildcard is used, it will read the first maxNumOfMessages messages and then apply the filename filter. This could result in fewer messages than expected.

jmsProps=

This parameter is used to specify JMS message string properties that will be added to the message. This parameter is only used in the Inbox or as the file destination.

jmsSelector=

This parameter is used to specify a JMS selector expression to select only certain items from the queue. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax. For example, the string (prop1=’val1’) and (prop2 LIKE ’val%%’) selects only those messages containing a string property, prop1, with a value of val1 and another string property, prop2, with a value starting with val. This parameter is used in the Outbox or as the file source. The typical % used in the JMS Selector expression must be specified as two percents (%%) since VersaLex uses % for macros.

msgID=

This parameter is used to specify a specific JMS message ID. This parameter cannot be a wildcard or regular expression. It is not typically specified in an action. It can be used to retrieve a specific message out of the JMS queue.

Parameters that could be added automatically by VersaLex include the following:

msgFilename=

This parameter is the filename for the message. If no filenameProp is specified, this will be the JMS message ID converted to a filename. Otherwise it contains the value from the String property specified by filenameProp.

msgID=

This is the JMS message ID. It is added to the URI so that a -DEL operation on a PUT can delete the specific message read.

length=

This is the length of the message.

time=

This is the timestamp of the JMS message. The format of the message time is YYYYMMDD-HHMMSS.

correlationId=

This is the correlation ID of the JMS message.

System properties can be defined for some of the JMS URI parameters. The parameters defined at the system property level would apply to all JMS URIs unless overridden in the URI itself or by a Connection ID property. The following system properties can be defined:

cleo.uri.jms.jndiConnectionFactoryName

Can be used in place of the jndiConnectionFactoryName URI parameter.

cleo.uri.jms.jndiInitialContextFactory

Can be used in place of the jndiInitialContextFactory URI parameter.

cleo.uri.jms.jndiURL

Can be used in place of the jndiURL URI parameter.

cleo.uri.jms.filenameProp

Can be used in place of the filenameProp URI parameter.

cleo.uri.jms.maxMessages

Can be used in place of the maxMessages URI parameter.

cleo.uri.jms.context.ContextKey

Can be used in place of or in addition to the ctxProps URI parameter and/or the Connection ID context properties. For example, if you wanted to set java.naming.security.authentication to simple as a default for all JMS connections, you would add the following line to the system.properties file: cleo.uri.jms.context.java.naming.security.authentication=simple

cleo.uri.jms.connectionFile

Used to define a properties file containing JMS connection properties. The properties in this file are used in conjunction with the connectionID URI parameter above.

Some parameters and properties can be specified at three different levels: in the URI string, in the Connection ID properties, and in the System properties. The parameters specified in the URI always override the values in the Connection ID properties and the System properties. The Connection ID properties override those in the System properties. If a value is in the System property that is not needed for a specific Connection ID property, the property can be added to the Connection ID properties file without a value.

There are many JMS servers available. Each of these servers provide their own custom .jar files that are used to send and receive JMS messages. These .jar files should be added to the VersaLex base class path using the cleo.additional.classpath system property. If more than one .jar file is necessary, the list of .jar files should be separated with a semicolon (;) on Windows systems and a colon (:) on Unix systems. Forward slashes (/) can be used for both Windows and Unix. If a backslash is used (\), then two backslashes (\\) must be used between each directory. For example, for GlassFish V3 the system property defined in the conf/system.properties file would look similar to cleo.additional.classpath=C:/glassfish3/glassfish/lib/gf-client.jar.

If the GlassFish server is not installed on the same workstation as VersaLex, then either:

• GlassFish would need to be loaded on the same workstation as VersaLex but not executed
• The necessary GlassFish files would need to be copied from the GlassFish installation to the VersaLex workstation
• The GlassFish files would need to be accessed through a network share.

In the case of unsolicited incoming files, the files will automatically be added as messages to the end of InboxQueue.

Then you can still use the JMS queue within the action commands.