+

Search Tips   |   Advanced Search

OSGi applications: Troubleshooting tips

Tips for troubleshooting OSGi applications support.

WebSphere Application Server system messages are logged from a variety of sources, including application server components and applications. To help you identify and resolve problems concerning OSGi Applications support, use the WAS tracing and logging facilities. To enable trace for OSGi Applications, set the application server trace string to Aries*=all=enabled. If we encounter a problem that you think might be related to OSGi Applications support, we can check for system messages in the WAS administrative console, and in the application server SystemOut.log file. You can also enable the application server debug trace to provide a detailed exception dump.

Note: Beginning in WAS v8.0, we can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log, SystemErr.log, trace.log, and activity.log files. If we are using HPEL, we can access all of the log and trace information using the LogViewer command-line tool from the server profile bin directory. See Use HPEL to troubleshoot applications.

Note: Beginning in WAS v8.0, we can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log, SystemErr.log, trace.log, and activity.log files or native z/OS logging facilities. If we are using HPEL, we can access all of the log and trace information using the LogViewer command-line tool from the server profile bin directory. See Use HPEL to troubleshoot applications. For more information about using tracing and logging, see Add logging and tracing to the application.

To help solve any unexpected problems with the deployed applications, we can debug the bundles at run time using the command-line console.

A list of the main known restrictions that apply when using OSGi Applications support is provided in OSGi Applications: Known restrictions.

Here is a set of tips to help troubleshoot commonly-experienced problems:


An existing Version 7 application server augmented with the OSGi Applications feature cannot be federated into a dmgr in Version 8.0 or later

If we have a WAS Version 7 node that is augmented with either the OSGi applications feature or the JPA 2.0 feature of the Feature Pack for OSGi Applications and Java™ Persistence API 2.0 before Fix Pack 5, and you federate the node into a WAS cell in Version 8.0 or later, the addNode command does not succeed.

Running the addNode command from the /bin directory of the application server generates the following exception message:

com.ibm.websphere.management.exception.AdminException: addNode validation has failed. The OSGi Applications feature is installed on this node, but is not installed on the dmgr. The dmgr must also have the OSGi Applications feature installed. The node has not been added.

This problem occurs only when you try to federate a Version 7 node that has already been augmented with either the OSGi applications feature or the JPA 2.0 feature of the Feature Pack for OSGi Applications and Java Persistence API 2.0 before Fix Pack 5. To resolve the problem, augment the Version 7 node with Fix Pack 5, or later, of the Feature Pack for OSGi Applications and Java Persistence API 2.0. You can download the latest version of the feature pack from the Feature packs by version for WebSphere Application Server support page.


The behavior has changed for using wsadmin commands to update bundle versions

In the WAS Version 7 Feature Pack for OSGi Applications and Java Persistence API 2.0, bundle changes to the asset are applied by restarting the business-level application. In WebSphere Application Server Version 8.0 and later versions, these changes are applied by updating the composition unit. The current approach means that many bundle changes can be applied in place, without restarting the running business-level application.

To enable the current approach, the UpdateAppContentVersionsStep parameter has been replaced with the UpdateAppContentVersions parameter, and instead of restarting the business-level application you run the editCompUnit command with ompUnitStatusStep parameter.

If we have created a script for updating bundle versions and applying the updates, modify the script to use the editAsset command with the UpdateAppContentVersions parameter instead of the UpdateAppContentVersionsStep parameter. Remove any business-level application restarts that were inserted to trigger updates to be applied, and instead use the editCompUnit command with ompUnitStatusStep parameter to apply the updates. For example: 

// *** Version 7 with OSGi Feature Pack script ***
AdminTask.editAsset('
  -assetID WebSphere:assetname=test.eba
  -UpdateAppContentVersionsStep [
    [test.impl 1.0.0 1.1.0] 
    [test.use.bundle 1.0.0 1.0.1]
  ]
')
AdminConfig.save()
// wait for downloads to complete by polling the BundleCacheManager MBean
...
// restartBLA
AdminTask.stopBLA(['-blaID', 'WebSphere:blaname=test'])
AdminTask.startBLA(['-blaID', 'WebSphere:blaname=test'])

// *** Version 8 script ***
AdminTask.editAsset('
  -assetID WebSphere:assetname=test.eba
  -UpdateAppContentVersions [
    [test.impl 1.0.0 1.1.0] 
    [test.use.bundle 1.0.0 1.0.1]
  ]
')
AdminConfig.save()
// wait for downloads to complete by polling the BundleCacheManager MBean
...
AdminTask.editCompUnit('[
  -cuID WebSphere:cuname=test_0001.eba 
  -blaID WebSphere:blaname=test.app 
  -CompUnitStatusStep [[WebSphere:asssetname=test.eba]]
]')
// any number of AdminTask.editCompUnit items for new configuration AdminConfig.save()
// no BLA restart


A composite bundle that is already included as application content should not also be applied as an extension

OSGi applications have one or more bundles listed in their Application-Content stanza, each with a given version range. The specific version of each bundle in use at a given time can be varied by creating a new deployment as described in Update bundle versions for an EBA asset.

For WebSphere Application Server Version 8.0 and later versions, composite bundles can either be listed in the Application-Content stanza, or added to the deployed OSGi application as an extension. For a given application, you should not extend the application with a composite bundle that is already listed in the Application-Content stanza, and whose version is within the listed range for the composite bundle. If we do this, you might get unexpected results when you update the bundle versions.


An application cannot rely on bundles always starting in the same order

You cannot assume that one bundle within an OSGi application will start or stop before another. If the application expects bundles to be started or stopped in a given order, it is unlikely to work in all environments.

The Blueprint programming model provides a way of declaring and dealing with inter-bundle service dependencies. If we cannot use Blueprint, we can use the ServiceTracker class, perhaps with an associated ServiceTrackerCustomizer to track services and react to changes in their status.


A web application must not rely on bundle fragments being attached in a particular order

See Fragment attach order.


An installed application does not start

You have successfully installed the OSGi application. However, when you try and start the application it does not start.

Use the OSGi Applications command-line console to explore the framework for the application, and to debug specific bundles within the application. See Debugging bundles at run time.


An updated bundle is not automatically downloaded unless the version is changed

You have an enterprise bundle archive (EBA) asset that uses a bundle that is in a repository. You import the asset, so the bundle is downloaded. If we then modify the bundle in the repository, but we do not change the version, the updated bundle is not downloaded again when an asset that requires this bundle is updated.

To get the updated bundle to download...

  1. Increment the value of the Bundle-Version header in the bundle manifest file as appropriate.

  2. Import the updated bundle into the bundle repository. For details on importing bundles into the internal bundle repository, see Administer bundles in the internal bundle repository.

  3. For the internal bundle repository, save the changes to the master configuration.

  4. Update the EBA asset to use the new bundle version; this operation updates the deployment manifest file. For details, see Update bundle versions for an EBA asset.

  5. Update the OSGi composition unit, containing the EBA asset, to use the updated deployment configuration; this operation causes the updated bundle to be downloaded. For details, see Update an OSGi composition unit.


An EBA asset cannot be added to a business-level application until all bundle downloads are completed

When you import an EBA file as an asset and save the changes to the master configuration, any missing dependencies are downloaded from the configured bundle repositories. We must wait until all the bundles are downloaded before we add the EBA asset to a business-level application.

You can view the download status of the bundles from the administrative console, or by calling the areAllDownloadsComplete () method of the BundleCacheManager MBean. See Interacting with the OSGi bundle cache.


An unsuccessful bundle download is not resolved automatically

If a bundle does not download, fix the cause (for example an incorrect repository address, or a network failure), then reset and retry the bundle download. See Interacting with the OSGi bundle cache.


An empty string does not always mean "no users" when you use wsadmin to map security roles to users

When you map security roles to users or groups as described in Add an EBA asset to a composition unit by using wsadmin commands, we can specify that no users are bound to the role by setting the usernames parameter to the empty string "" - unless the application contains an ibm-application-bnd.xmi file.

The empty string "" means "use the default or existing value". If wer application does not contain an ibm-application-bnd.xmi file, the default value is that no users are bound to the role. However, when an application contains an ibm-application-bnd.xmi file, the default value for usernames is obtained from this file.

If we are deploying an application containing an ibm-application-bnd.xmi file, and to remove the bound users, specify just the "|" character (which is the separator for multiple user names). This setting explicitly specifies "no users", and therefore guarantees that no users are bound to the role.


A Blueprint bundle might not have started even though the application seems to have started successfully

When you start the OSGi application, any Blueprint bundles in the application try to satisfy their service dependencies. By default, the blueprint bundles continue to try to do this for five minutes before generating a timeout exception.

To check whether the Blueprint bundles have started, use the trace string org.apache.aries.blueprint.*=debug and check in the application server SystemOut.log file for GRACE_PERIOD messages. These messages tell you what, if anything, the Blueprint container is waiting for.


Any class path ordering defined in web fragments must match the bundle class path

See Class path ordering in web fragments.


For CDI to work for a directory or JAR file on a bundle class path, file META-INF/beans.xml is needed

See Web application bundles and CDI.


Subtopics


Related concepts

  • Considerations for using web applications and bundle fragments in web application bundles


    Related tasks

  • Interacting with the OSGi bundle cache
  • Debugging bundles at run time


    Build OSGi applications with the Blueprint Container specification
    Best practices for developing and working with OSGi applications
    Develop enterprise OSGi applications for WebSphere Application Server