Update an OSGi composition unit

If a new OSGi application deployment is available, we can update the OSGi composition unit so that the business-level application uses the newer configuration. If any of the updates contain configuration options, a wizard prompts you to update the configuration information.

This topic assumes that we have either updated the asset that the composition unit contains, or added a composite bundle as an extension to the composition unit. You do not have to update the composition unit every time you update the asset or add a composite bundle extension. You cannot update the composition unit until all bundle downloads are complete.

You can update an OSGi composition unit using the administrative console as described in this topic, or by using wsadmin commands as described in Update an OSGi composition unit using the editCompUnit command.

An OSGi composition unit consists of an EBA asset, (optionally) one or more composite bundle extensions, and configuration information for running the asset and composite bundle extensions in a business-level application. The configuration information can include HTTP session management, context roots, virtual hosts, security roles, run-as roles, JNDI mappings for Session enterprise beans, JNDI mappings for EJB references, and web application or Blueprint resource reference bindings for the OSGi application.

When all bundle downloads are complete, we can update the OSGi composition unit so that the business-level application uses the newer configuration. If any of the updates contain configuration options, a wizard prompts you to update the configuration information. You can also take the opportunity to make additional, non-essential configuration changes.

For users who are moving from a previous version: 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, rather than 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.

This topic describes the specific task of updating an OSGi composition unit. The more generalized task of updating the configuration of any composition unit is described in Update business-level applications.

1. Start the administrative console.

2. Navigate to Applications > Application Types > Business-level applications > application_name > composition_unit_name.

   The Composition unit settings panel is displayed. The deployment status is displayed under [General Properties] OSGi application deployment status, and shows one of the following values:

   • Use latest OSGi application deployment.

   • New OSGi application deployment not yet available because it requires bundles that are still downloading.

   • New OSGi application deployment available.

   • New OSGi application deployment cannot be applied because bundle downloads have failed.

   If the status is "New OSGi application deployment available", the Update to latest deployment ... button is available.

3. Update the composition unit to use the latest version of the EBA asset or composite bundle extension.

   If the status is "New OSGi application deployment available", click Update to latest deployment .... The Preview composition unit upgrade [Settings] panel is displayed.

   Because multiple updates might be available, and because updates do not have to be applied immediately, you might not be fully aware of the changes that you are about to make to the deployed application. So that we can see the cumulative effect of all the changes, this panel shows the complete list, bundle by bundle, of the updates that are about to be applied. If the result is not what we want, we can cancel the update. Otherwise, click OK.

4. Update the configuration information for running the asset or composite bundle extension in the business-level application.

   Bundle changes might also require configuration changes to the composition unit. For example, if you update a bundle in an EBA asset, or replace a composite bundle extension, you might introduce a resource that requires additional configuration, such as a new or changed Blueprint resource reference, or security role mapping.

   If any of the updates contain configuration options, a wizard prompts you to update the configuration information. This wizard is based on the Set options settings wizard that you use when creating an OSGi composition unit. See Add an EBA asset to a composition unit using the administrative console.

5. Save the changes to the master configuration.

Results

When you save the changes to the composition unit, the associated business-level application is updated to use the new configuration. If the business-level application is running, the bundle and configuration updates are applied immediately.

If possible (that is, depending on the nature of the updates) the system applies the updates without restarting the application. If we update a bundle that provides only OSGi services to the rest of the application, then only that bundle is restarted. If we update a bundle that provides one or more packages to other bundles, then those bundles and any bundles to which they provide packages are restarted. If, however, a new package or service dependency is added, or an existing package or service dependency is removed, then the application is restarted; a newly added package and service can come from a newly-provisioned bundle, or from a bundle that has already been provisioned.

If the application has a client bundle that references an enterprise bean in a service bundle, then to prevent the application being restarted if the service bundle is updated, configure the enterprise bean dependency in one of the following ways:

• Declare the enterprise bean in the Export-EJB header in the bundle manifest file of the service bundle, so that the enterprise bean is registered in the OSGi service registry, and use a reference element in the Blueprint XML file of the client bundle to inject and call the enterprise bean; for more information, see References and the Blueprint Container. This procedure is the preferred way to configure the EJB dependency.

• In the client bundle, declare an EJB reference to the target enterprise bean, in either an @EJB annotation or a binding XML file, and map the EJB reference to the EJB JNDI name when the application is deployed; for more information, see EJB references [Settings].

If we do not declare the enterprise bean using the Export-EJB header or by binding the EJB reference into JNDI, then a JNDI binding is generated automatically when you deploy the application, provided that there is exactly one match between the interface that the EJB class implements, and an interface specified in an EJB reference. However, the JNDI name that is generated contains the bundle version, which changes if you update the bundle; in this case, when you update the composition unit, the JNDI is regenerated to contain the updated version, and this configuration change results in the application being restarted.

Messages relating to any restart operations are written to the WAS SystemOut.log file.

Subtopics

• Update an OSGi composition unit using the editCompUnit command
  Use the editCompUnit command to select a composition unit containing an enterprise OSGi application, and update the composition unit so that the business-level application uses the newer configuration. If any of the updates contain configuration options, run the editCompUnit command a second time to update the configuration information. You can also take the opportunity to make additional, non-essential configuration changes.

Parent topic: Maintain an OSGi composition unit

Parent topic: Update bundle versions in a deployed OSGi application

Parent topic: Extending a deployed OSGi application

Related tasks

Add or removing extensions for an OSGi composition unit

Modify the configuration of an OSGi composition unit

Checking the bundle download status of an EBA asset

Update bundle versions for an EBA asset

Checking the update status of an OSGi composition unit

Develop a composite bundle

Writing extensible OSGi applications

Related information:

Preview composition unit upgrade [Settings]