Creating an OSGi bundle fragment for vendor classes

If your application uses IBM or vendor classes that are supplied with the JRE, you must create an OSGi bundle fragment to make the classes available in the OSGi framework

About this task

Starting with CICS® TS 5.1, the OSGi framework has stricter rules that control which classes can be loaded from the JRE.

Any package that is prefixed with java is loaded by the OSGi framework as required by the application. If an application uses an IBM or vendor package that is supplied with the JRE, such as com.ibm.misc, you must create a middleware OSGi bundle to make these classes available to the OSGi framework. If you do not, transactions abend with an AJ05 code and java.lang.ClassNotFoundException errors are written to the JVM server error log and CICS system log.

You do not need to complete these steps for the CICS Java classes, because the JCICS classes are automatically made available in the OSGi framework.

Procedure

  1. For each IBM or vendor package that the application requires, create an OSGi bundle fragment to export the package. The following example shows what the manifest of the OSGi bundle fragment can contain:
    Manifest-Version: 1.0
    Bundle-ManifestVersion: 2
    Bundle-Name: Extension
    Bundle-SymbolicName: com.ibm.example.extension
    Bundle-Version: 1.0.0
    Bundle-Vendor: IBM
    Fragment-Host: system.bundle; extension:=framework
    Export-Package: com.ibm.misc
    Bundle-RequiredExecutionEnvironment: JavaSE-1.6

    The Fragment-Host defines that the OSGi bundle fragment extends the system bundle in the OSGi framework. The Export-Package lists the packages that are exported; in this example, the package beginning com.ibm.misc is exported. If you use Eclipse, ignore the error that is flagged.

  2. Change the application to add an import for the exported package in the appropriate OSGi bundle manifest. Each OSGi bundle that requires a class from an IBM or vendor package must declare the package in the manifest.
  3. Create a CICS Bundle project for the OSGi bundle fragments. You can include one or many OSGi bundle fragments in the project depending on whether you want to manage the lifecycle of the fragments together. It is best practice to keep the middleware bundle separate from the application so that administrators can manage the lifecycle separately in CICS.

Results

You have created a CICS bundle project that contains one or more OSGi bundle fragments that export packages from the JRE. When deployed, this middleware bundle ensures your application can run in a CICS TS 5.1 JVM server.

What to do next

Deploy the application and middleware bundle. You must ensure that the JVM profile for the target JVM server specifies the middleware bundle on the OSGI_BUNDLES option.