OSGi applications: Troubleshooting tips
Tips for troubleshooting OSGi applications support.
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 WebSphere Application Server 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.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 you use OSGi Applications support is provided in OSGi Applications: Known restrictions.
- An existing Version 7 application server augmented with the OSGi Applications feature cannot be federated into a Deployment Manager in Version 8.0 or later
- For Version 9 and later, the way WebSphere Application Server interprets the Require-Bundle header changes to be compliant with the OSGi specification 3.13.1.
- The behavior has changed for using wsadmin commands to update bundle versions
- A composite bundle that is already included as application content should not also be applied as an extension
- An application cannot rely on bundles always starting in the same order
- A web application must not rely on bundle fragments being attached in a particular order
- An installed application does not start
- An updated bundle is not automatically downloaded unless the version is changed
- An EBA asset cannot be added to a business-level application until all bundle downloads are completed
- An unsuccessful bundle download is not resolved automatically
- An empty string does not always mean "no users" when you use wsadmin to map security roles to users
- A Blueprint bundle might not have started even though the application seems to have started successfully
- Any class path ordering defined in web fragments must match the bundle class path
- For CDI to work for a directory or JAR file on a bundle class path, file META-INF/beans.xml is needed
An existing Version 7 application server augmented with the OSGi Applications feature cannot be federated into a Deployment Manager in Version 8.0 or later
If you have a WebSphere Application Server 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 WebSphere Application Server 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 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 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 your 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.
For Version 9 and later, the way WebSphere Application Server interprets
the Require-Bundle
header changes to be compliant with the OSGi specification
3.13.1.
Require-Bundle
header specifies a bundle symbolic name, and might contain
arbitrary attributes. Require-Bundle: com.example.mybundle;foo=bar
In Version
9 and later, the foo=bar
attribute must be matched by an attribute on the symbolic
name of the required bundle:
Bundle-SymbolicName: com.example.mybundle;foo=bar
Require-Bundle: com.example.mybundle;version=1.1.0
The
version=1.1.0
is treated as an attribute to be matched against the symbolic name,
and would probably cause the application to fail to resolve. The correct way to specify a version
range is to use:
Require-Bundle: com.example.mybundle;bundle-version=1.1.0
The behavior has changed for using wsadmin commands to update bundle versions
In the WebSphere Application Server 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 the CompUnitStatusStep parameter.
// *** 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 Updating 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 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 your 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
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 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 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.
- Increment the value of the Bundle-Version header in the bundle manifest file as appropriate.
- Import the updated bundle into the bundle repository. For details on importing bundles into the internal bundle repository, see Administering bundles in the internal bundle repository.
- If you are using the internal bundle repository, save your changes to the master configuration.
- Update the EBA asset to use the new bundle version; this operation updates the deployment manifest file. For details, see Updating bundle versions for an EBA asset.
- 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 Updating 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 your changes to the master configuration, any missing dependencies are downloaded from the configured bundle repositories. You must wait until all the bundles are downloaded before you 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 Adding an EBA asset to a composition unit by using wsadmin commands, you can specify that no users are bound to the role by setting the usernames parameter to the empty string "" - unless your application contains an ibm-application-bnd.xmi file.
The empty string "" means the default or existing value is used. 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 you want 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 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.