This guide provides information to help you get started with installing, configuring and using the IBM® Client for the Java™ Message Service (JMS) on the Java 2 Platform, Standard Edition (J2SE) with IBM WebSphere® Application Server. The guide consists of the following sections:
The IBM Client for JMS on J2SE with IBM WebSphere Application Server is an embeddable technology that provides JMS v1.1 connections to a WebSphere Application Server Version 6.0.2 or above default messaging provider messaging engine. The connection to the messaging engine can be either TCP or SSL. HTTP connectivity is not supported.
The client supports the following Java Runtime Environments (JREs):
Two versions of the IBM Client for JMS on J2SE with IBM WebSphere Application Server are available. The runtime code is identical in both versions; the versions differ only in the license under which the code is made available.
To use the IBM Client for JMS on J2SE with IBM WebSphere Application Server only within your enterprise select the “JMS Client” download file sibc_install-<build>.jar which is available under an IBM International Program License Agreement (IPLA). This version of the Client for JMS on J2SE with IBM WebSphere Application Server is warranted and supported by IBM.
To redistribute the IBM Client for JMS on J2SE with IBM WebSphere Application Server outside your enterprise select the “JMS Client (OEM)” download file sibc_oeminst-<build>.jar which is available under an IBM International License Agreement for Non-Warranted Programs (ILAN). This version of the IBM Client for JMS on J2SE with IBM WebSphere Application Server is not supported by IBM.
Before redistributing the IBM Client for JMS on J2SE with IBM WebSphere Application Server outside of your enterprise you must obtain a Distribution License from IBM. To receive a Distribution License from IBM you should:
The download installation file supports multiple install options. To perform an install of the client enter:
java –jar <installation file>.jar [flags]
[positional arguments]
flags
-text install using a command-line interface
-silent install using silent license acceptance
-xpd install Lotus Expeditor v6.1 Device Runtime Environment J2SE 5.0 ready executables
positional arguments
install option one of: jms, jms_jndi_ibm, jms_jndi_sun, nls (see below)
install directory directory to install into
The following install options are available:
jms - JMS
only
Choose this option if you require JMS v1.1 function only. All connection factories must be programmatically created, since no Java Naming and Directory Interface (JNDI) function is available. This option has the smallest installed footprint.
jms_jndi_ibm - JMS + JNDI for IBM JREs
Choose this option if you require JMS v1.1 with basic JNDI function to run under an IBM JRE.
jms_jndi_sun - JMS + JNDI for Sun JREs
Choose this option if you require JMS v1.1 with basic JNDI function to run under a Sun JRE.
nls - optional
National Language Support (NLS) files
Choose this option if you require support for languages other than English.
For example, to install JMS + JNDI for IBM JREs into c:\jms use:
java –jar sibc_install-<build>.jar jms_jndi_ibm
c:\jms
The installed directories and their contents are:
|
../bin |
Run scripts including the custom.bat and custom.sh files that you use to configure the client on either Windows or Unix platforms. |
|
../docs |
The documentation for the client. |
|
../etc |
The default WebSphere Application Server client key and trust files required for SSL. |
|
../lib |
The client JAR files. |
|
../license |
License files |
|
../properties |
The trace settings properties file. |
UNIX users may need to set execute permission on the ../bin shell scripts.
With the exception
of support for WebSphere Application Server v5.1 the following conditions
apply:
The client is supported in WebSphere Application Server v5.1 provided:
Optional national language support files are provided. Any combination of these language files can be copied into the …/lib directory. The following national language support files are available:
|
Language |
Country or region |
File |
|
German |
|
sibc.nls_de.jar |
|
Spanish |
|
sibc.nls_es.jar |
|
French |
|
sibc.nls_fr.jar |
|
Italian |
|
sibc.nls_it.jar |
|
Japanese |
|
sibc.nls_ja.jar |
|
Korean |
|
sibc.nls_ko.jar |
|
Brazilian Portuguese |
|
sibc.nls_pt_BR.jar |
|
Simplified Chinese |
|
sibc.nls_zh.jar |
|
Traditional Chinese |
|
sibc.nls_zh_TW.jar |
To configure the client to work with a simple JMS application:
JRE_HOME=<location of JRE>
JMS_PCLIENT=<location of JMS Client>
CLASSPATH=<required application
CLASSPATH>
For example, if the downloaded zip file was unzipped into c:\JmsClient then set
JMS_PCLIENT=c:\JmsClient
The JAR files for the client contained in the ../lib directory may be embedded into a larger Java application provided system properties required by the client are configured to the Java Virtual Machine. The batch and shell script files in the ../bin directory show what system properties are required.
Suitable JMS connection factories may be obtained programmatically without using JNDI, for example:
import com.ibm.websphere.sib.api.jms.*;
...
JmsConnectionFactory jmsCF = JmsFactoryFactory.getInstance().createQueueConnectionFactory();
jmsCF.setBusName("myBus");
jmsCF.setProviderEndpoints("1.2.3.4");
A suitable reference to a JMS queue or topic may be obtained programmatically, for example:
JmsQueue jmsQ = JmsFactoryFactory.getInstance().createQueue("myQueue");
For further information see the JmsFactoryFactory class Javadoc available with WebSphere Application Server.
To compile JMS code, include the following jar files in the CLASSPATH setting for the javac command:
<JMS_PCLIENT>/lib/sibc.jms.jar
To run JMS code, use your customized custom.bat or custom.sh file, for example:
custom HelloJMSWorld
When using the JMS code in an OSGi environment the application bundle should import the package:
javax.jms
if using programmatically created connection factories then the following package should also be imported by the application bundle:
com.ibm.websphere.sib.api.jms
Alternatively, if using JNDI lookups then the following package should also be imported by the application bundle:
com.ibm.websphere.naming
When performing JNDI lookups in an OSGi environment using an IBM JRE in which no boot delegation to the boot classpath class loader is performed eg Dosgi.compatibility.bootdelegation=false, it is necessary that the following JVM system property be specified:
-Dorg.osgi.framework.system.packages=com.ibm.CORBA.iiop,<all packages exported by system.bundle>
A list of all packages exported by system.bundle can be obtained from the Execution Environment Profile being used. If the Execution Environment is J2SE-1.4 then the list of all packages exported by system.bundle can be obtained from the property org.osgi.framework.system.packages in the Execution Environment Profile file named J2SE-1.4.profile contained in the bundle org.eclipse.osgi_<version>.jar
A JNDI provider is supplied with the client. The JNDI provider is capable of discovering and performing unauthenticated and insecure lookups of service integration bus resources in a WebSphere Application Server using “jndi” name syntax. There is no SSL support for JNDI operations.
The client provides two JNDI enabled options that allow you to use JNDI to look up service integration bus resources in a WebSphere Application Server instead of creating connection factories programmatically. You must install one of these two options, as described in Installing the client, if you want to perform JNDI lookups.
To create a suitable Initial Context, create the following code, substituting the server IP address and port as appropriate:
import javax.naming.*;
...
Hashtable env = new Hashtable();
env.put(Context.PROVIDER_URL,"iiop://<server
IP address>:<server bootstrap
address port>");
env.put(Context.INITIAL_CONTEXT_FACTORY,"com.ibm.websphere.naming.WsnInitialContextFactory");
env.put("java.naming.corba.orb",org.omg.CORBA.ORB.init((String[])null,null));
InitialContext ctx = new InitialContext(env);
The property “java.naming.corba.orb” specifies the Object Request Broker (ORB) instance that the WebSphere Application Server JNDI provider should use to contact the server. This property is not required by JREs which include the IBM ORB because the WebSphere Application Server JNDI provider will locate an IBM ORB instance automatically. This property is required by all JREs which do not include the IBM ORB.
If it is not possible to programmatically create an ORB instance as required by the “java.naming.corba.orb” property then an alternative is to specify the property:
env.put("com.ibm.CORBA.ORBInit","com.ibm.ws.sib.client.ORB");
The client uses the standard Java Secure Socket Extension (JSSE) provided by all supported JREs to make SSL connections. JSSE documentation can be found at: http://java.sun.com/products/jsse/reference/docs/index.html A JRE configured to use SSL connections to connect to WebSphere Application Server would typically require System Properties to be configured for the client JRE as shown in the following example:
-Djavax.net.ssl.keyStore=%JMS_PCLIENT%\etc\DummyClientKeyFile.jks
-Djavax.net.ssl.keyStorePassword=WebAS
-Djavax.net.ssl.trustStore=%JMS_PCLIENT%\etc\DummyClientTrustFile.jks
-Djavax.net.ssl.trustStorePassword=WebAS
The client is supplied with the WebSphere Application Server default client key file and default client trust file in the .../etc directory. The supplied custom.bat and custom.sh files have been pre-configured to use the default client key and trust files. Before you deploy the client in a production environment, you must:
1. Replace the supplied default client key and trust files with your own key files.
2. Change the SSL_CONFIG settings in the custom.bat and custom.sh files to specify your own key files and passwords.
Trace may be enabled in two ways:
To enable trace using a system property and a trace properties file, set the variable WAS_TRACE in custom.bat or custom.sh to the name of a trace properties file, which should be located in the CLASSPATH, for example:
WAS_TRACE=-DtraceSettingsFile=TraceSettings.properties
This is an example trace properties file:
########################################################################
# A property to
specify where the output messages and trace (if enabled)
# should be routed. Valid values include stdout or a fully qualified
# file name. If a file is specified but
cannot be opened, stdout is used.
#
# Sample invocations
# To specify stdout - traceFileName=stdout
# To specify a file
on NT - traceFileName=c:\\MyTraceFile.log or
# traceFileName=c:/MyTraceFile.log
# To specify a file
on Unix - traceFileName=/usr/MyTraceFile.log
########################################################################
traceFileName=trace.log
########################################################################
# Specify trace
strings here. Trace strings take the form of:
# logger={level}={type}
where:
# level = entryexit || debug ||
event || all
# type = enabled ||
disabled
# examples:
# com.ibm.ejs.ras.SharedLogBase=all=enabled
enables all tracing for the
#
single logger created in class com.ibm.ejs.ras.SharedLogBase.
# com.ibm.ejs.*=debug=enabled
enables debug tracing for all loggers with
#
names starting with com.ibm.ejs.
#
# Multiple trace strings can be specified,
one per line.
########################################################################
*=all=enabled
To enable trace using system properties only configure the system properties:
-Dcom.ibm.ws.sib.client.traceSetting (trace specification) for example
-Dcom.ibm.ws.sib.client.traceSetting=SIBTrm=all:SIBCommunications=all
-Dcom.ibm.ws.sib.client.traceFile (name of trace file) for example -Dcom.ibm.ws.sib.client.traceFile=c:\trace.log
To enable First Failure Data Capture (FFDC) logging, set the variable WAS_FFDC in custom.bat or custom.sh with the name of the FFDC log file, for example:
WAS_FFDC=-DffdcLogFile=ffdc.log
New messages in the client are:
CWSJX0001E: An inconsistency in installed component build levels was
detected. The installed build level of component {0} which is {1} is different
to the build level of component {2} which is {3}.
Explanation: The installed
build level of all client components must be the same.
User response: Install a new
version of the client which contains the required components.
CWSJX0002E: The client component {0} has been installed but this is not
compatible with a Java Runtime Environment from {1}.
Explanation: Not all client
components are compatible with all vendor Java Runtime Environments, some
vendors provide additional function in the Java Runtime Environment which is
not compatible with some client components.
User Response: Install a
different version of the client which does not contain the component causing
the problem or use a different vendor Java Runtime Environment.
CWSJX0003E: The client found other WebSphere resources which are not
compatible with the client.
Explanation: The client
must not be run inside a WebSphere Application Server or WebSphere Application
Client environment.
User Response: Run the client
outside of a WebSphere Application Server and WebSphere Application Client
environment.
CWSJX0004E: The installed client component {0} requires that the client
component {1} be installed when used with a Java Runtime Environment from {2}.
Explanation: Some client
components require that other client components also be installed when run with
some vendor Java Runtime Environments.
User Response: Install a new
version of the client which contains the required components.
CWSJX0005E: The current Java Runtime Environment is version {0}, the
required Java Runtime Environment is {1} or higher.
Explanation:
The Java Runtime Environment is not a supported version.
User response:
Install a supported Java Runtime Environment.
For all other messages see the WebSphere
Application Server Information Center.
This
message will appear during installation when a Sun JRE which does not have the
“Additional languages” feature installed is used. The message does not prevent
correct operation of the client.
IBM, WebSphere and Lotus are trademarks of IBM Corporation.
Microsoft, Windows, Windows
NT, and the Windows logo are trademarks of Microsoft Corporation in the
Linux is a trademark of Linus Torvalds in the
Java and all Java-based
trademarks are trademarks of Sun Microsystems, Inc. in the
UNIX is a registered
trademark of The Open Group in the
Other company, product and service names may be trademarks or service marks of others.
© Copyright IBM Corporation 2006, 2008. All Rights Reserved.
US Government Users Restricted
Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.