URI File System Interface

The VersaLex application currently has three predefined URI schemes:

• JMS: Used to read and write messages to Java Message Service queues. VersaLex implements the client side of JMS. See JMS URI scheme.
• MSMQ: Used to read and write messages to Microsoft Message Queuing queues. VersaLex implements the client side of MSMQ. See MSMQ URI scheme.
• VLPipe: Used to pipe payload coming into one mailbox out through another VersaLex mailbox. See VLPipe URI scheme.

In addition, you can develop custom URI schemes in Java and add them to the VersaLex application. See custom URI schemes

These URI schemes can be used in the host-level Inbox and Outbox fields or as the source/destination in actions. If the URI scheme mimics a file system, then that scheme can be used for local user folders.

Sample URIs:

• jms:jndi:InboxQueue?jndiConnectionFactoryName=ConnFact&filenameProp=filename
• msmq:DIRECT=OS:.\private$\Inbox?createQueue=true
• vlpipe:FTPPipeDevTest\myMailbox
• mydb:\MyDBInbox
• hdfs:\hdfsnamenode:50070\Inbox

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 tojavax.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 propertycleo.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 theconnectionID 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.

The VersaLex MSMQ URI is for using Microsoft Message Queuing (MSMQ) queues instead of local file system files for payload sent to and received from trading partners.

The basic format of the MSMQ URI is:

msmq:DIRECT=OS:msmqQueue?param1=value1&param2=value2& param3=…

Example:

msmq:DIRECT=OS:.\private$\Inbox?createQueue=true

VersaLex only supports the DIRECT=OS queues.

In the case of unsolicited incoming files, the files will automatically be added as messages to the end of DIRECT=OS:.\private$\Inbox.

The VersaLex VLPipe URI is for piping input payload from one host’s Inbox out through another mailbox. The host and mailbox are specified in the URI. The <send> action will be used to send incoming payload out through the host\mailbox.  VLPipe can only be used for inboxes – it is nonsensical for outboxes.

The basic format of the MailboxPipe URI is:

vlpipe:host\mailbox

Example:

vlpipe:FTPPipeDevTest\myMailbox

If the host-level Inbox is specified as a mailbox pipe:

vlpipe:FTPPipeDevTest\myMailbox

Then all incoming payload (whether solicited or unsolicited) will be redirected through <send>myMailbox@FTPPipeDevTest

Custom scheme(s) can be created to access payload not normally accessible to VersaLex. A URI scheme must start with a letter and be followed by one or more alpha-numeric characters.

The custom URI scheme implementation must provide three basic classes:

1. File class – A class that provides that similar functionality as the java.io.File class. The custom Scheme File class must extend com.cleo.lexicom.beans.LexURIFile.
2. InputStream class – A class that provides similar functionality as the java.io.InputStream class. The custom Scheme InputStream class must extend java.io.InputStream.
3. OutputStream class – A class that provides similar functionality as the java.io.OutputStream class. The custom SchemeOutputStream class must extend java.io.OutputStream.

These three custom-written classes are configured in system properties. System properties are used to configure the class names for single URI scheme:

cleo.uri. scheme .file                   (required)

cleo.uri. scheme .inputstream      (required)

cleo.uri. scheme .outputstream    (required)

In addition, an optional classpath variable is provided to specify the path to the implementation jar and any support jar files necessary:

cleo.uri. scheme .classpath         (optional)

If any additional jars need to be in the base VersaLex class loader, then the cleo.additional.classpath system property must be used.

The Cleo versions of JMS, MSMQ, and VLPipe can be replaced with custom versions by specifying these system properties for JMS, MSMQ, or VLPipe and naming the custom classes.

Further documentation for custom URI schemes is provided in the API documentation (see LexURIFile in the JavaDocs).