Deploying OSGi bundles in a JVM server

To deploy a Java™ application in a JVM server, you must install the OSGi bundles for the application in the OSGi framework of the target JVM server.

Before you begin

The CICS bundle that contains the OSGi bundles for the application must be deployed to zFS. The target JVM server must be enabled in the CICS region.

About this task

A CICS bundle can contain one or more OSGi bundles. Because the CICS bundle is the unit of deployment, all the OSGi bundles are managed together as part of the BUNDLE resource. The OSGi framework also manages the lifecycle of the OSGi bundles, including the management of dependencies and versioning.

Ensure that all OSGi bundles that comprise a Java application component are deployed in the same CICS bundle. If there are dependencies between OSGi bundles, deploy them in the same CICS bundle. When you install the CICS BUNDLE resource, CICS ensures that all the dependencies between the OSGi bundles are resolved.

If you have dependencies on an OSGi bundle that contains a library of common code, create a separate CICS bundle for the library. In this case, it is important to install the CICS BUNDLE resource that contains the library first. If you install the Java application before the CICS bundles that it depends on, the OSGi framework is unable to resolve the dependencies of the Java application.

Do not attempt to install a CICS bundle that contains an OSGi bundle into a Liberty JVM server, as this configuration is not supported. Instead, you can either package the OSGi bundle together with your web application in an enterprise bundle archive (EBA), or you can use the WebSphere® Liberty bundle repository to make the OSGi bundle available to all web applications in the Liberty JVM server.

If you're using CICS Explorer: You can use the IBM® CICS® SDK for Enterprise Java (Liberty) in CICS Explorer to deploy bundles by following instructions in this topic.
If you're using Gradle or Maven: You can package and deploy applications in CICS bundles by using the CICS-provided Gradle or Maven plug-in, provided the CMCI JVM server is configured to use the How it works: CICS bundle deployment API CICS bundle deployment API.

This tutorial provides step-by-step instructions on how to build a CICS bundle from an existing Java application that is already built by Gradle or Maven.

Procedure

  1. Create a BUNDLE resource that specifies the directory of the bundle in zFS:
    1. In the CICS SM perspective, click Definitions > Bundle Definitions in the CICS Explorer menu bar to open the Bundles Definitions view.
    2. Right-click anywhere in the view and click New to open the New Bundle Definition wizard.
      Enter the details for the BUNDLE resource in the wizard fields.
    3. Install the BUNDLE resource.
      You can either install the resource in an enabled or disabled state:
      • If you install the resource in a DISABLED state, CICS installs the OSGi bundles in the framework and resolves the dependencies, but does not attempt to start the bundles.
      • If you install the resource in an ENABLED state, CICS installs the OSGi bundles, resolves the dependencies, and starts the OSGi bundles. If the OSGi bundle contains a lazy bundle activator, the OSGi framework does not attempt to start the bundle until it is first called by another OSGi bundle.
  2. Optional: Enable the BUNDLE resource to start the OSGi bundles in the framework if the resource is not already in an ENABLED state.
  3. Click Operations > Bundles in the CICS Explorer menu bar to open the Bundles view. Check the state of the BUNDLE resource.
    • If the BUNDLE resource is in an ENABLED state, CICS was able to install all the resources in the bundle successfully.
    • If the BUNDLE resource is in a DISABLED state, CICS was unable to install one or more resources in the bundle.
    If the BUNDLE resource failed to install in the enabled state, check the bundle parts for the BUNDLE resource. If any of the bundle parts are in the UNUSABLE state, CICS was unable to create the OSGi bundles. Typically, this state indicates that there is a problem with the CICS bundle in zFS. You must discard the BUNDLE resource, fix the problem, and then install the BUNDLE resource again.
  4. Click Operations > Java > OSGi Bundles in the CICS Explorer menu bar to open the OSGi Bundles view. Check the state of the installed OSGi bundles and services in the OSGi framework.
    • If the OSGi bundle is in the STARTING state, the bundle activator has been called but not yet returned. If the OSGi bundle has a lazy activation policy, the bundle remains in this state until it is called in the OSGi framework.
    • If the OSGi bundles and OSGi services are active, the Java application is ready.
    • If the OSGi service is inactive it is possible that CICS detected an OSGi service with that name already exists in the OSGi framework.
    • If you disable the BUNDLE resource, the OSGi bundle moves to the RESOLVED state.
    • If the OSGi bundle is in the INSTALLED state, either it has not started or it failed to start because the dependencies in the OSGi bundle could not be resolved.
  5. Invoke a Java application in a JVM server.

Results

The BUNDLE is enabled, the OSGi bundles are successfully installed in the OSGi framework, and any OSGi services are active. The OSGi bundles are available to other bundles in the framework.

What to do next

You can make the Java application available to other CICS applications outside the OSGi framework, as described in Invoking a Java application in a JVM server.