Network Deployment (Distributed operating systems), v8.0 > Reference > Troubleshoot tips


OSGi Applications: Troubleshooting tips

Tips for troubleshooting OSGi Applications support.

WAS 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 CWS??=all=enabled:Aries*=all=enabled. If you encounter a problem that you think might be related to OSGi Applications support, you can check for system messages in the WAS administrative console, and in the application server SystemOut.log file. We can also enable the application server debug trace to provide a detailed exception dump.

Beginning in WAS v8.0, you 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 you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your 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 your deployed applications, you 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 you troubleshoot commonly-experienced problems:


An existing v7 application server augmented with the OSGi Applications feature cannot be federated into a v8 Deployment Manager

If we have a WAS v7 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 prior to Fix Pack 5, and you federate the node into a WAS v8 cell, the addNode command does not succeed.

Run 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 Deployment Manager. The Deployment Manager must also have the OSGi Applications feature installed. The node has not been added.

This problem occurs only when you try to federate a v7 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 prior to Fix Pack 5.

To resolve the problem, augment your v7 node with Fix Pack 5, or later, of the Feature Pack for OSGi Applications and Java Persistence API 2.0. We can download the latest version of the feature pack from the Feature packs by version for WAS support page.

sep2011


The behavior has changed for using wsadmin to update bundle versions

In the WAS v7 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 v8, 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 the CompUnitStatusStep parameter.

If you have created a script for updating bundle versions and applying the updates, modify your 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 the CompUnitStatusStep parameter to apply the updates. For example: 

// *** v7 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'])

// *** v8 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 WAS v8.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 you 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 you cannot use Blueprint, you 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 your 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 Debug bundles at run time using the command-line console.


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 you then modify the bundle in the repository, but you 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. If you are using the internal bundle repository, save your 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, that contains 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.

jul2011


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 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 you add the EBA asset to a business-level application.

We 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 using wsadmin, you 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 your 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 you are deploying an application that contains 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 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 your 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 your 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:

About OSGi Applications
Considerations for using web applications and bundle fragments in web application bundles

Related tasks:

Secure OSGi Applications
Interacting with the OSGi bundle cache
Debug bundles at run time using the command-line console

Related reference:

Accept OSGi applications with the Blueprint Container specification

Best practices for developing and working with OSGi applications

Develop enterprise OSGi applications for WAS
Reference topic Feedback
Copyright IBM Corporation 2009, 2011. All Rights Reserved.
This information center is powered by Eclipse technology.

+

Search Tips   |   Advanced Search