Adding application classes to the class paths for a JVM

The class paths for a JVM are defined by options in the JVM profile, and in the JVM properties file that the JVM profile references. (Setting up JVM profiles and JVM properties files tells you how to select or create JVM profiles and their associated JVM properties files.) For each Java program, when you have specified the name of the JVM profile that CICS is to use for the JVM (on the JVMPROFILE attribute of the PROGRAM resource definition), you need to locate the JVM profile and its associated JVM properties file, and add the application classes for the program to the class paths. You can edit JVM profiles and JVM properties files in a standard text editor.

If you are setting up CORBA stateless objects and enterprise beans, and you just need to know how to specify the JAR file or any additional classes on the shareable application class path, you can skip straight to Including CORBA stateless objects and enterprise beans on the shareable application class path. If you are setting up a standard Java application, or if you want to know more about how the different class paths should be used, carry on reading.

Classes in a JVM explains the classes that are present in a JVM: system classes and standard extension classes, middleware classes, and application classes. That topic also explains the four class paths to which you can add the classes that your application needs. The class path you choose determines how the JVM treats the class.

When you add any class to a class path, remember that:
As explained in Classes in a JVM, you should add classes to class paths as follows:
  1. Choose the library path for any native C dynamic link library (DLL) files that are to be loaded into the JVM by trusted code. This might include the DLL files needed to use the DB2 JDBC drivers, or any native code associated with a class that you are using to redirect JVM output (named on the USEROUTPUTCLASS option in the JVM profile).

    To include items on the library path, use the LIBPATH option in the JVM profile that you have selected for the application (or for worker JVMs, in the profile for the master JVM that initialises the shared class cache). “Options in JVM profiles” in the CICS System Definition Guide has more information about this option.

  2. Choose the trusted middleware class path for middleware classes that can be trusted by the JVM to manage their own state across a JVM-reset. This class path is normally used for classes for middleware supplied by IBM or by another vendor, which are not included in the standard JVM setup for CICS. Trusted middleware classes are permitted to change the JVM environment even if the JVM is resettable, so for this reason you should not normally place your own application classes on the trusted middleware class path.

    To include classes on the trusted middleware class path, use the TMPREFIX or TMSUFFIX option in the JVM profile that you have selected for the application (or for worker JVMs, in the profile for the master JVM that initialises the shared class cache). Using TMPREFIX places the class at the beginning of the trusted middleware class path, and using TMSUFFIX places it at the end of the path. The trusted middleware class path also includes the path specified by the CICS_DIRECTORY option in the JVM profile, which points to the CICS-supplied JAR files. “Options in JVM profiles” in the CICS System Definition Guide has more details about all these options. For CICS, these options are used instead of the ibm.jvm.trusted.middleware.class.path JVM system property.

  3. Choose the shareable application class path for application classes that you want to be cached. For standalone JVMs, the classes will be cached in the JVM, kept across JVM reuses, and reinitialized if the JVM is reset. For worker JVMs, they will be obtained from the shared class cache. Adding application classes to this class path, rather than to the standard class path, produces the best performance in a resettable JVM, and it should be your normal choice for loading application classes in a production environment.

    To include classes on the shareable application class path, use the system property ibm.jvm.shareable.application.class.path, in the JVM properties file that is referenced by the JVM profile that you have selected for the application (or for worker JVMs, in the JVM properties file for the master JVM that initialises the shared class cache). “System properties for JVMs” in the CICS System Definition Guide has more details about this system property.

  4. Choose the standard class path for nonshareable application classes, that is, application classes that you do not want to be shared by other JVMs or across JVM resets. Classes on this class path are not placed in the shared class cache. They are loaded into the JVM. If the JVM is defined as resettable, classes on this class path are discarded when the JVM is reset, and reloaded from HFS files each time the JVM is reused. If the JVM is defined as a continuous JVM, however, nonshareable application classes are kept intact from one JVM reuse to the next.

    You should not normally place application classes on the standard class path without a good reason for doing so, because it causes a degradation in performance in a resettable JVM, and for worker JVMs (both resettable and continuous) it uses more storage than having a single copy of the classes in the master JVM. You might find it convenient to use this class path during application development in a non-production environment if your JVMs are resettable, because it means you do not have to phase out the JVM pool in order to update class definitions. (If your JVMs are continuous, you still need to phase out the JVM pool.) Occasionally, you might decide to use this class path for classes that are used infrequently, if you prefer to incur the performance cost in a resettable JVM of reloading the class each time it is required, rather than the storage cost of keeping the class in the JVM or in the shared class cache.

    To include classes on the standard class path, use the CLASSPATH option in the JVM profile that you have selected for the application. This class path is always taken from the profile for the JVM itself, not from the profile for the master JVM that initialises the shared class cache. “Options in JVM profiles” in the CICS System Definition Guide has more details about this option. For CICS, this option is used instead of the java.class.path JVM system property.