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:
- Your application classes should not perform unresettable actions, that
is, actions that modify the state of a JVM in such a way that it cannot be
properly reset. The classes can perform these actions, but they cause resettable
JVMs to be marked as unresettable and to be destroyed rather than re-used,
and in continuous JVMs they might have an undesirable effect on subsequent
program invocations in the JVM. How JVMs are reused explains
how to avoid unresettable actions.
- If you want to add classes to different class paths, they need to be in
separate directories or JAR files. For example, if an application includes
some classes that you want to place in the shared class cache (which need
to go on the shareable application class path), and other classes that you
prefer to be placed in the individual JVMs (which need to go on the standard
class path), you should place each type of class in a separate directory.
- If the JVM for this application is to use
the shared class cache (see The shared class cache), then
classes that you add to most of the class paths must be placed in the class
paths in the JVM profile and JVM properties file for the master JVM that initializes
the shared class cache, rather than in the JVM profile and JVM properties
file for the JVM where the application will run. This applies to middleware
classes, shareable application classes, and any items that you add to the
library path. This is because the library path (defined by the LIBPATH option
in the JVM profile), the trusted middleware class path (built from the CICS_DIRECTORY,
TMPREFIX, and TMSUFFIX options in the JVM profile), and the shareable application
class path (defined by the ibm.jvm.shareable.application.class.path system
property in the JVM properties file), are all ignored for a worker JVM, and
are taken instead from the JVM profile and JVM properties file for the master
JVM. Only the standard class path (specified by the CLASSPATH option in the
JVM profile) is taken from the JVM profile for the JVM itself, rather than
from the JVM profile for the master JVM that initialises the shared class
cache.
- The name of the class itself (including the name of the package, if the
program has been built as a package) is not actually specified in the JVM
profile or JVM properties file. The options in the JVM profile or JVM properties
file specify the path to the class—that is, the full path of the HFS
directory in which a class loader will be able to find the class or the package
containing the class. The rule is to stop specifying the path, at the
point where you would start specifying the name of the class in the
JVMCLASS attribute in a PROGRAM resource definition (see Setting up a PROGRAM resource definition for a Java program to run in a JVM).
So if the program has been built as a package, and you would use the Java
class name qualified by the package name (the fully qualified class name)
in the PROGRAM resource definition, do not include the package name as part
of the path. If the program has not been built as a package, and you would
just use the class name in the PROGRAM resource definition, then the path
must specify all the subdirectories, including the subdirectory containing
the class. Where classes or packages have been placed in JAR files (with
the extension .jar), include the name of the JAR file on the class path as
if it were the name of a directory. “Options in JVM profiles”
in the CICS® System
Definition Guide shows some examples of paths.
- Use a colon as the separator between paths that you specify on a class
path. (This is defined by the path.separator system property
for the JVM, which you can change.) To include line breaks, use a backslash
and a blank (\ ). “Rules for coding JVM profiles and JVM properties files” in the CICS System
Definition Guide has a full explanation of how to code class paths
and other items in a JVM profile or JVM properties file.
As explained in
Classes in a JVM, you should add
classes to class paths as follows:
- 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.
- 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.
- 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.
- 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.