Java code base

The WebSphere MQ Everyplace Java code base can be deployed onto a large variety of Java runtimes. These include:

The way that WebSphere MQ Everyplace, the application and other classes are packaged and deployed is dependant on the type of Java runtime, the operating system and processor type of the device that is being deployed to. This section provides information to assist in packaging and deploying Java based WebSphere MQ Everyplace applications to different environments.

Supplied jar files

WebSphere MQ Everyplace is supplied with a set of class libraries in the form of jar files that can be used when deploying applications that utilize WebSphere MQ Everyplace. There are two types of jar file; base jar files and extension jar files. The base jar files allow a usable queue manager to be created, administered and run. The extension jar files can be used in addition to the base jar files to provide additional capability.

Base jar files

MQeBase.jar
Contains classes that provide for a basic queue manager running in client and server mode on a J2ME CDC/Foundation or J2SE or better Java runtime.

MQeMidp.jar
Similar to MQeBase.jar but for use on a J2ME CLDC/MIDP Java runtime. Allows a queue manager to run in client mode. All MIDP compliant classes are included in this jar. No extension jars can be used with this one, as they are not MIDP compliant.

MQeGateway.jar
Contains classes that provide for a basic queue manager running in client, server and bridge mode on a J2SE or better Java runtime.

Extension jar files

MQeJMS.jar
Contains the classes that extend an WebSphere MQ Everyplace queue manager to provide a JMS programming interface.

MQeRetail.jar
Contains extra classes for use in retail environments. In particular, these classes are useful on a 4690 retail system.

MQeSecurity.jar
A set of classes that are used to provide both queue and message based security. It contains a set of cryptors, compressors and authenticators.

MQeBindings.jar
This file contains all C bindings specific information. It is required if access to a Java queue manager from a C application is needed (only on Win32 platforms).

MQeMigration.jar
Contains classes that assist in migrating from an earlier version of WebSphere MQ Everyplace.

MQeDeprecated.jar
This contains all of the deprecated class files that are no longer needed by a WebSphere MQ Everyplace application. These deprecated class files help you run applications written using a previous version of WebSphere MQ Everyplace, without making any changes.

MQeDiagnostics.jar
This file helps to diagnose problems with WebSphere MQ Everyplace classes. It contains tooling to search the class path to find out the level of each class found.

Other jar files

MQeExamples.jar
A packaging of all the WebSphere MQ Everyplace examples into one jar file. This includes all of the examples supplied with WebSphere MQ Everyplace, but excludes the deprecated classes.

MQeCore.jar
This contains a minimal set of classes. On its own it is not usable but it can be used as a base for building a small footprint WebSphere MQ Everyplace system. More details on reducing footprint can be found in the "Optimizing footprint" section.

Optimizing footprint

In many cases the supplied jar files can be used without change, however there are instances where this is not the case. In particular, on some environments where footprint is limited, the set of classes that are deployed must be reduced to the smallest possible size. The supplied jar files are general purpose and contain more than is necessary for an optimized environment. This section covers how to optimize the set of classes down to only those that are required for a particular application.

The table below separates the classes into groups associated with a particular function or configuration and will help determine which classes will be required to optimize an applications footprint. Using this table the minimum required set of classes can be deduced by taking the mandatory classes for the required categories and then adding in required optional classes for that category.

Due to the wide ranging set of Java runtimes that are now available, not all classes can run on all runtimes. The table lists all classes, unless otherwise stated, each class will run on a J2SE runtime. Due to the differences between a J2SE and a J2ME runtime, some of the classes are not appropriate for a J2ME runtime. There are two columns that show which classes can be used on J2ME MIDP and J2ME CDC/Foundation runtimes.

Table 40.

Category Detail Classes required (com.ibm.mqe. ) Midp compliant CDC / Foundation compliant
Mandatory classes For all queue managers MQe MQeAdapter
MQeAttribute
MQeAttributeDefaultRule
MQeAttributeRule
MQeAuthenticator MQeCompressor
MQeCryptor MQeEnumeration
MQeException MQeExceptionCodes
MQeField MQeFields MQeKey
MQeLoaderMQeProperties
MQePropertyProvider
MQeQueueControlBlock
MQeQueueProxy MQeQueueManager
MQeQueueManagerRule
MQeResourceControlBlock
MQeRule MQeRunnable
MQeRunnableInstance MQeThread
MQeThreadPool$1
MQeThreadPool$PooledThread
MQeThreadPool$Target
MQeThreadPool MQeTrace
MQeTraceHandler
MQeTraceInterface
registry.MQeRegistry
X X
Registry type One option in this category must be selected


File registry Add required: Storage adapter registry.MQeFileSession registry.MQeRegistrySession X X
Private registry w/o credentials Add: File registry registry.MQePrivateRegistry registry.MQePrivateSession
X
Private registry with credentials Add: Private registry w/o credentials attributes.MQeMiniCertRequest attributes.MQeSharedKey attributes.MQeWTLSCertificate
X
Mini-certificate management functions attributes.MQeListCertificates registry.MQePrivateRegistryConfigure
X
Public registry Applicable to types of message-level security Add: Private registry with credentials registry.MQePublicRegistry
X
Queue manager type For all types add required: Administration Storage adapters Message store Authenticators Cryptors Compressors Rules Security


Standalone qMgr.
No additional classes

Client qMgr. Add required: Communications MQeTransporter
adapters.MQeCommunicationsAdapter
communications.MQeChannel
communications.MQeChannelCommandInterface
communications.MQeChannelControlBlock
communications.MQeCommunicationsException
communications.MQeCommunicationsManager
communications.MQeConnectionDefinition
communications.MQeListener
communications.MQeListenerSlave
X X
Server qMgr. Add: Client qMgr. Add required: Communications Note: whilst MQeListener is not used in the Client, they need to be included when preverifying a J2ME application
X
Gateway qMgr. Add: Server qMgr. Add required Communications Transformers MQeBridgeLoadable MQeBridgeManager mqbridge.*

Communications



TCP/IP w/o history & persistence
adapters.MQeTcpipAdapter adapters.MQeTcpipLengthAdapter
X
TCP/IP with history & persistence Add: TCP/IP w/o history and persistence adapters.MQeTcpipHistoryAdapter
adapters.MQeTcpipHistoryAdapterElement

X
HTTP 1.0 Not to WES Proxy Authentication server
adapters.MQeTcpipAdapter adapters.MQeTcpipHttpAdapter
X
HTTP To WES Proxy Authentication server
adapters.MQeTcpipAdapter adapters.MQeWESAuthenticationAdapter
X
HTTP 1.1/1.0 J2ME MIDP only adapters.MQeMidpHttpAdapter X
UDP
adapters.MQeUdpipBasicAdapter$Initiator adapters.MQeUdpipBasicAdapter$InternalAdapter adapters.MQeUdpipBasicAdapter$Responder adapters.MQeUdpipBasicAdapter$Writer adapters.MQeUdpipBasicAdapter
X
Queue types For all queue types add required: Authenticators Cryptors Compressors Rules


Local Add: Storage adapter Message storage MQeAbstractQueueImplementation
MQeEventTrigger MQeMessageEvent MQeMessageListenerInterface
MQeQueue MQeQueueRule (or replacement)
X X
Remote Add: Local queue (storage adapter & msg. storage only if needed) MQeRemoteQueue X X
Home server Add: Remote queue (no storage adapter or msg. storage) MQeHomeServerQueue X X
Store and forward Add: Remote queue MQeStoreAndForwardQueue X X
Bridge queue Add: Remote queue mqbridge.MQeMQBridgeAdminMsg mqbridge.MQeBridgeServices mqbridge.MQeMQBridgeQueue mqbridge.MQeMQQMgrName mqbridge.MQeMQQName

Message storage



Base
MQeMessageStoreException MQeAbstractMessageStore messagestore.MqeIndexEntry X X
Standard Add: Base messagestore.MQeMessageStore X X
Short filename. Always use 8.3 file name for messages. Add: Standard messagestore.MQeShortFilenameMessageStore
X
4690 specific Add: Short filename messagestore.MQe4690ShortFilenameMessageStore

Message type



Basic
Support for MQeMsgObject is in Mandatory classes X X
MQSeries
mqemqmessage.*

Storage adapters



Assured disk Independence from OS lazy writes adapters.MQeDiskFieldsAdapter
X
Non-assured disk Dependence on OS lazy writes Add: Assured disk adapters.MQeReducedDiskFieldsAdapter
X
Case-Insensitive Add: Assured disk adapters.MQeCaseInsensitiveAdapter
X
Long to Short Filename Mapping
adapters.MQeMappingAdapter
X
Midp RMS Storage MIDP Only adapters.MQeMidpFieldsAdapter com.ibm.mqe.adapters.MQeMidpFieldsAdapter$RMSFile X
Memory Volatile storage adapters.MQeMemoryFieldsAdapter X X
Administration



Basic administration capability Add: Local queue MQeAdministrator MQeAdminMsg MQeAdminQueue MQeAdminQueue$1 MQeAdminQueue$Timer X X
Manage queue manager Add: Basic administration capability administration.MQeQueueManagerAdminMsg X X
Manage connection definitions Add: Basic administration capability administration.MQeConnectionAdminMsg X X
Manage communications listeners Add: Basic administration capability administration.MQeCommunicationsListenerAdminMsg X X
Manage local queue Add: Basic administration capability administration.MQeQueueAdminMsg X X
Manage administration queue Add: Manage local queue administration.MQeAdminQueueAdminMsg X X
Manage remote queue Add: Manage local queue administration.MQeRemoteQueueAdminMsg X X
Manage home server queue Add: Manage remote queue administration.MQeHomeServerQueueAdminMsg X X
Manage store and forward queue Add: Manage remote queue administration.MQeStoreAndForwardQueueAdminMsg X X
Manage bridge queue Add: Manage remote queue mqbridge.MQeMQBridgeQueueAdminMsg mqbridge.MQeCharacteristicLabels
X
Manage a bridge to MQSeries Add: Remote queues mqbridge.*AdminMsg mqbridge.MqeCharacteristicLabels mqbridge.MqeRunState mqbridge.MqeBridgeServices mqbridge.MQeBridgeExceptionCodes

Queue manager creation and deletion
MQeQueueManagerConfigure X X
Authenticators



mini-certificate
attributes.DHk (source may be generated) attributes.MQeSharedKey attributes.MQeRandom attributes.MQeWTLSCertificate attributes.MQeWTLSCertAuthenticator
X
Compressors



GZIP
attributes.MQeGZIPCompressor
X
LZW
attributes.MQeLZWCompressor attributes.MQeLZWDictionaryItem X X
RLE
attributes.MQeRleCompressor X X
Cryptors



triple DES
attributes.MQe3DESCryptor
X
DES
attributes.MQeDESCryptor
X
MARS
attributes.MQeMARSCryptor
X
RC4
attributes.MQeRC4Cryptor
X
RC6
attributes.MQeRC6Cryptor
X
XOR
attributes.MQeXorCryptor X X
Application security services



Local security Add required: Cryptors attributes.MQeLocalSecure X X
Message-level security Add required: Cryptors attributes.MQeMAttribute
X
Message-level security with digital signature & validation Add: Public registry. Add required: Cryptors attributes.MQeMTrustAttribute
X
Trace



Collect binary trace in J2SE/CDC
trace.MQeTraceToBinary trace.MQeTraceToBinaryFile
X
Collect binary trace to Midp RMS Store And or send to MIDP Trace servlet
trace.MQeTraceToBinary trace.MQeTraceToBinaryMidp X
Base trace renderer
trace.MQeTracePoint trace.MQeTracePointGroup trace.MQeTraceRenderer
X
Decode a binary file to readable form Add: Base trace renderer trace.MQeTraceToReadable trace.MQeTraceFromBinaryFile
X
Trace to a readable output stream Add: Base trace renderer trace.MqeTraceToReadable
X
Servlet collection of Midp binary trace Add Base trace renderer trace.MQeTraceToReadable examples.trace.MQeServlet

Miscellaneous



Cryptographic support Application or installation use only attributes.MQeCL (footnote?) attributes.MQeGenDH (generates a version of attributes.MQeDHk.java)
X
Mini-certificate server SupportPac ES03 MQe_MiniCertServer (or command line tool) See ES03 installation instructions


MQe_Explorer SupportPac ES02 MQe_Explorer See ES02 installation instructions


Bindings Access to Java classes from other languages


C language
bindings.*

JMS Support for the Java Message Service API jms.*
transaction.*

X X





User-defined MQe extensions





Authenticators Communications adapters Compressors Cryptors Logging classes Message classes Rule classes Security control Storage adapters Trace handler

JMS requirements

In order to use the WebSphere MQ Everyplace JMS programming interface, the JMS interface classes are required. These are contained typically in JMS.jar. WebSphere MQ Everyplace does not ship with jms.jar, and this must be downloaded before JMS can be used. At the time of writing, this can be freely downloaded from http://java.sun.com/products/jms/docs.html. The JMS Version 1.0.2b jar file is required.

In addition, if JMS administered objects are to be stored and retrieved using the Java Naming and Directory Interface (JNDI), the javax.naming.* classes must be available. If Java 1 is being used, for example, a 1.1.8 JRE, jndi.jar must be obtained and added to the classpath. If Java 2 is being used, a 1.2 or later JRE, the JRE might contain these classes. You can use WebSphere MQ Everyplace without JNDI, but at the cost of a small degree of provider dependence. WebSphere MQ Everyplace-specific classes must be used for the ConnectionFactory and Destination objects. You can download JNDI jar files from http://java.sun.com/products/jndi

WebSphere MQ Classes for Java requirements

To use the WebSphere MQ bridge the WebSphere MQ Classes for Java are required, version 5.1 or later. These are packaged with WebSphere MQ 5.3 and above. If using an earlier version of WebSphere MQ then they are available for free download from the Web as supportpac MA88. The Web address for the download is: http://www.ibm.com/software/mqseries/txppacs/ma88.html.

For an example of how to setup the classpath to include WebSphere MQ jar files, see batch files:

Occasionally, the jar files change between versions of the WebSphere MQ, if problems are encountered as a result of this, consult the documentation for WebSphere MQ classes in order to determine the correct jar files to use.

Using WebSphere studio device developer smart linker

The smart linker tool that ships with WebSphere Studio Device Developer is used in the process of building and packaging an application into a jar or jxe file. The smart linker can remove classes (and methods) that are deemed not to be required; this will happen to classes that are dynamically loaded. WebSphere MQ Everyplace makes use of dynamic loading so care should be taken to either avoid this feature or to explicitly name classes that must be present, even though not explicitly referenced in the code.

To prevent unused classes being removed use the - noRemoveUnused option. If the -removeUnused option is set then any class that is dynamically loaded must be specifically included. One option that can be use to achieve this is -includeWholeClass. For example -includeWholeClass "com.ibm.mqe.adapters.*" will include all classes in the adapters package and -includeWholeClass "com.ibm.mqe.adapters.MQeTcpipHttpAdapter" will only include the http adapter. Multiple include (or exclude) options can be specified in the smart linker options file.

The following guidelines can be used to determine which classes are dynamically loaded. The basic guideline is any class that is referenced though an WebSphere MQ Everyplace class alias or any class that is set as a parameter when administering WebSphere MQ Everyplace resources will be dynamically loaded. This includes:

An example of a set of includes needed for a simple MIDP application is:

-includeWholeClass "com.ibm.mqe.MQeQueue" 
-includeWholeClass "com.ibm.mqe.MQeRemoteQueue" 
-includeWholeClass "com.ibm.mqe.MQeHomeServerQueue" 
-includeWholeClass "com.ibm.mqe.MQeTransporter" 
-includeWholeClass "com.ibm.mqe.communications.MQeConnectionDefinition" 
-includeWholeClass "com.ibm.mqe.adapters.MQeMidpFieldsAdapter" 
-includeWholeClass "com.ibm.mqe.adapters.MQeMidpHttpAdapter" 
-includeWholeClass "com.ibm.mqe.messagestore.MQeMessageStore" 
-includeWholeClass "com.ibm.mqe.registry.MQeFileSession"

J2ME Midp specifics

When deploying the Java Application for the Midp environment a few additional comments are worth mentioning.

4690 specifics

Take the following requirements into account when configuring WebSphere MQ Everyplace for use with 4690.

It is recommended that you use the MQeCaseInsensitiveDiskAdapter on the 4690 OS. This class implements a disk adapter that is insensitive to the 'case' of the filename used during matching. Some JVM or OS combinations list files with different case to that in which they were created. This means that the simple filtering in the superclass ignores them. This class converts both the compator and the comperand to lowercase before performing the comparison. This ensures the best chance of finding a valid match. Note that the conversion to lower case may be innapropriate on platforms where the case is honoured, and where there are non-mqe files stored that could be confused by case. In summary, as this adapter is more suited for use with the 4690 due its filesystem.

Packaging

Following is a list of some of the techniques and tools that can be used to package applications ready for deployment to a device. The list is not a full list and does not go into any detail but is intended to provide an introduction to some of the ways a Java application can be packaged.

Single Jar file
Build a self-contained application with WebSphere MQ Everyplace embedded in it. This option minimizes the footprint and ensures that the classpath is kept to a minimum.

Multiple Jar files
Put application into one jar file and use either the supplied WebSphere MQ Everyplace jar files or construct a separate WebSphere MQ Everyplace jar file. Keeping WebSphere MQ Everyplace in one or more separate jars makes it easy to use WebSphere MQ Everyplace from multiple independent applications.

JNLP
JNLP or Java Network Launching Protocol and API, is an emerging standard, for use in packaging and deploying Java applications. It is designed to automate the deployment, via the web, for applications written to the J2SE platform.

Midlet
An WebSphere MQ Everyplace J2ME MIDP application must be packaged as a midlet or midlet suite (.jad and .jar).

Palm specific
In order to run on a Palm device a Java application must to be packaged in a prc file, which is a Palm specific format. The IBM WebSphere Studio Device Developer product ships with a tool that will package a Java application as a prc file.

JXE
IBM WebSphere Studio Device Developer has a SmartLinker tool that can produce an optimized packaging of an application that contains the minimum set of required classes and methods for the deployment platform. The output from the smartlinker is stored in a .JXE file which is understood by the IBM j9 Java runtime.

Installer
There are a number of tools that will package an application ready for installation on one or more platforms. A couple of examples of these are InstallShield and self extracting zip files.

Roll you own distribution mechanism
For instance using a Java class loader that can load classes over a network.

Deployment to devices

Following is a list of some of the techniques and tools that can be used to deploy applications to devices. The list is by no means complete and does not go into any detail but is intended to provide an introduction to some of the ways a Java application can be deployed.

Device specific tools
Most devices ship with tools that allow applications to be copied across and installed. For instance:

Development tools
Many development environments (IDEs) like WSDD (IBM WebSphere Studio Device Developer) provide tools that allow deployment of applications onto a device and debugging of the application from the development environment.

JNLP
JNLP or Java Network Launching Protocol and API, is an emerging standard, for use in packaging and deploying Java applications. It is designed to automate the deployment, via the web, for applications written to the J2SE platform.

Device management products
There are a number of products on the market that can be used for large-scale deployment of software. One example is Tivoli(R) Configuration Manager from IBM.


© IBM Corporation 2002. All Rights Reserved