Modifying the configuration of an OSGi composition unit

You can modify the configuration information for a composition unit that contains an enterprise OSGi application. 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 your OSGi application.

Before you begin

You can modify the configuration of an OSGi composition unit by using the administrative console as described in this topic, or by using wsadmin commands as described in Modifying the configuration of an OSGi composition unit by using wsadmin commands.

About this task

An OSGi composition unit consists of an EBA asset, (optionally) one or more composite bundle extensions, and some or all of the following configuration information:
  • Mappings from the composition unit to a target application server, web server, or cluster.
  • Configuration of the session manager, context roots or virtual hosts of the application.
  • Mappings from enterprise beans to JNDI names.
  • Bindings to any associated web applications or blueprint resource references.
  • Mappings from security roles to particular users or groups.

You first specify the configuration of an EBA asset or composite bundle extension when you add it to a composition unit. If bundles in the asset or composite bundle extension are later changed, or if you have to remap resources, you can update the configuration. 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.

This topic describes the specific task of modifying the configuration of an OSGi composition unit.

Procedure

  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.

  3. Under the Additional Properties section, click any of the following options then modify the settings as required.
    • Session management

      Configure HTTP session management for the web application bundles.

      The Session management option is only visible if the OSGi application uses web application bundles.

    • Context root for web modules

      Select a web application bundle (WAB) from the list, then enter the context root for the WAB. For example, /sample. For more information, see Context root for web modules [Settings].

      The Context root for web modules option is visible only if the application uses web application bundles.

    • Listeners for message-driven beans

      For each message-driven bean (MDB) that is defined in either an ejb-jar.xml file or in an @MessageDriven annotation in the composition unit, you can specify the settings necessary to bind an MDB listener to the MDB. By binding a listener to an MDB, you configure the association of the MDB with the JMS destination from which the MDB receives messages. For more information, see Listeners for message-driven beans [Settings].

      The Listeners for message-driven beans option is visible only if the OSGi application contains at least one EJB bundle that has at least one MDB.

    • EJB JNDI names

      For each Session enterprise bean in the composition unit, you can specify the JNDI name by which the enterprise bean is known in the runtime environment. For more information, see EJB JNDI names [Settings].

      The EJB JNDI names option is visible only if the OSGi application contains at least one EJB bundle that has at least one session enterprise bean.

    • EJB references

      For each EJB reference that is defined in either an ejb-jar.xml file, a web.xml file, or an @EJB annotation in the composition unit, you can specify the JNDI name by which the EJB reference is known in the runtime environment. For more information, see EJB references [Settings].

      The EJB references option is visible only if the OSGi application contains at least one EJB reference, defined either in an ejb-jar.xml file, a web.xml file, or in an @EJB annotation.

    • EJB resource references

      The list of available EJB resource references in this asset is displayed. That is, resources of type resource-ref (resource reference), as defined in the Java™ specification JSR-250: Common Annotations for the Java Platform. For each reference, specify the JNDI name under which the resource is known in the runtime environment. For more information, see EJB resource references [Settings].

      The EJB resource references option is visible only if the OSGi application contains at least one resource reference, defined either in an ejb-jar.xml file, or through an @Resource annotation on an enterprise bean.

    • EJB message destination references

      The list of available EJB message destination and resource environment references in this asset is displayed. That is, resources of type message-destination-ref (message destination reference) or resource-env-ref (resource environment reference), as defined in the Java specification JSR-250: Common Annotations for the Java Platform. For each reference, specify the JNDI name under which the resource is known in the runtime environment. For more information, see EJB message destination references [Settings].

      The EJB message destination references option is visible only if the OSGi application contains at least one JMS message destination reference or resource environment reference, defined either in an ejb-jar.xml file, or through an @Resource annotation on an enterprise bean.

    • EJB environment entries

      For each simple environment entry that is defined in either an env-entry element in an ejb-jar.xml file or in an @Resource annotation in the composition unit, you can specify the value of the environment entry. For more information, see EJB environment entries [Settings].

      The EJB environment entries option is visible only if the OSGi application contains at least one simple environment entry, defined either in an ejb-jar.xml file, or in an @Resource annotation.

    • Virtual hosts for web modules

      The list of available WABs in this asset is displayed. For each WAB, you can change the associated virtual host by selecting a different one from the list. If you specify an existing virtual host in the ibm-web-bnd.xml or .xmi file for a WAB, the specified virtual host is set by default. Otherwise, the default virtual host setting is default_host. For more information, see Virtual hosts for web modules [Settings].

      The Virtual hosts for web modules option is visible only if the application uses web application bundles.

    • Security role to user or group mapping

      Change the security mapping as needed. For more information, see Security role to user or group mapping [Settings].

      The Security role to user or group mapping option is visible only if the application uses security roles.

    • RunAs roles for users

      You can map a specified user identity and password to a RunAs role. This mapping enables you to specify application-specific privileges for individual users, so that they can run specific tasks using another user identity. For more information, see RunAs roles for users [Collection].

      The RunAs roles for users option is visible only if the application uses RunAs roles.

    • Blueprint resource references

      The list of available Blueprint resource references in this asset is displayed. For each reference, you can optionally select an authentication alias from the list. Default authentication aliases (from ibm-eba-bnd.xml files) are offered only if they exist on every target server or cluster. For more information, see Blueprint resource references [Settings].

      The Blueprint resource references option is visible only if the bundle includes Blueprint resource reference declarations.

    • Web module message destination references

      The list of available web application message destination and resource environment references in this asset is displayed. That is, resources of type message-destination-ref (message destination reference) or resource-env-ref (resource environment reference), as defined in the Java specification JSR-250: Common Annotations for the Java Platform. For each reference, specify the JNDI name under which the resource is known in the runtime environment. For more information, see Web module message destination references [Settings].

      The Bind web module message destination references to administered objects wizard step and the Web module message destination references property are visible only if the bundle includes a web application.

    • Web module resource references

      The list of available web application resource references in this asset is displayed. That is, resources of type resource-ref (resource reference), as defined in the Java specification JSR-250: Common Annotations for the Java Platform. For each reference, specify the JNDI name under which the resource is known in the runtime environment. Optionally, set authentication properties and extended data source custom properties, which affect how the resource is accessed at run time. To specify the JNDI name mapping, either type the JNDI name into the box, or click Browse... then select the resource reference from the list of available resources. To modify the authentication method, or to set extended data source custom properties that apply to the database connection, select a single reference then click Modify Resource Authentication Method... or Extended Properties.... For more information, see Web module resource references [Settings].

      The Web module resource references option is visible only if the bundle includes a web application.

  4. Save your changes to the configuration repository.

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 you update a bundle that provides only OSGi services to the rest of the application, then only that bundle is restarted. If you 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 your 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 you do not declare the enterprise bean by 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 that is 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 WebSphere Application Server SystemOut.log file.