Add an EBA asset to a composition unit using wsadmin

Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop OSGi applications > Develop and deploying an OSGi application > Deploy an OSGi application as a business-level application

Add an EBA asset to a composition unit using wsadmin

We can use the addCompUnit command and the AdminConfig commands to add a composition unit that consists of a previously-imported enterprise bundle archive (EBA) asset plus configuration information. The configuration information can include HTTP session management, context roots, virtual hosts, security roles, run-as roles, and web application or Blueprint resource reference bindings for your OSGi application.

Before you begin

We can add an EBA asset to a business-level application by using wsadmin as described in this topic, or by using the administrative console as described in Add an EBA asset to a composition unit .
An EBA asset can be added to only one business-level application. A business-level application is scoped to cell scope, therefore only one instance of a given OSGi application can be deployed in a cell.
This task makes the following assumptions:
You have already imported the EBA file as an asset (for example by using the importAsset command as described in step 2 of Set up business-level applications using wsadmin.sh), then saved your changes to the master configuration (which causes any bundle dependencies to be downloaded from configured bundle repositories).
You have already defined the target virtual hosts.
To check existing virtual hosts using wsadmin, issue the following jython command:
print AdminConfig.list('VirtualHost')
You have already created the JCA authentication alias to associate with each Blueprint resource reference.
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:

Maps from the composition unit to a target application server, web server or cluster.
Configuration of the application's session manager, context roots or virtual hosts.
Bindings to any associated web applications or blueprint resource references.
Maps from security roles to particular users or groups.

To create and configure all elements of the composition unit except the HTTP session manager, you use the addCompUnit command.
To configure the HTTP session manager, you use the AdminConfig commands to configure the deployed object represented by the appDeploy variable. The composition unit must be created before the session management options can be applied to it, so run the addCompUnit command before you configure the HTTP session manager.
As well as specifying the configuration information for the EBA asset through the following procedure, you can also change it later as described in Modify the configuration of an OSGi composition unit using wsadmin. 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.

Procedure
Create and configure all elements of the composition unit except the HTTP session manager.
Each of the following substeps describes the syntax for adding a single element to the composition unit. However, to create the composition unit you run the addCompUnit command only once. Therefore, when you run the command, combine these elements together. An example of the combined syntax is given after the separate substeps.
For several of the elements, the values you specify include bundle identifiers. If your EBA asset includes or references composite bundles, the command syntax is slightly different. For clarity, the differences for composite bundles are described, step by step, in a linked topic.
Add the previously-imported asset (the .eba file) as a deployed asset.

The parameters for this aspect of the command are as follows:

-blaID

Configuration ID of the business-level application.

-cuSourceID

ID of the EBA asset that is being added to the business-level application.

-CUOptions

Following additional properties for the composition unit.

parentBLA
backingID
name
description
startingWeight
startedOnDistributed
restartBehaviorOnUpdate

-MapTargets

Specifies additional properties for the composition unit target mapping. That is, it specifies the deployable unit URI (which, for an EBA asset, is ebaDeploymentUnit) and the target node and server, or the target cluster.
To add an additional target, you use the plus sign character ( + ) as a prefix.

-ActivationPlanOptions

Specifies additional properties for the composition unit activation plan. That is, it specifies the deployable unit URI and a list of runtime components. For an EBA asset, use default values as shown in the example below.

If the target is one cluster, the jython syntax for this aspect of the command is as follows:
AdminTask.addCompUnit('[
  -blaID WebSphere:blaname=bla_name
  -cuSourceID WebSphere:assetname=asset_name.eba
  -CUOptions [
    [WebSphere:blaname=bla_name.eba
    WebSphere:assetname=asset_name.eba
    cu_name "optional_cu_description" 1 false DEFAULT]]
  -MapTargets [[ebaDeploymentUnit WebSphere:cluster=cluster_name]]
  -ActivationPlanOptions [[default ""]]
  ...
]')
For example:
AdminTask.addCompUnit('[
  -blaID WebSphere:blaname=helloWorldService
  -cuSourceID WebSphere:assetname=com.ibm.ws.eba.helloWorldService.eba
  -CUOptions [
    [WebSphere:blaname=helloWorldService.eba
    WebSphere:assetname=com.ibm.ws.eba.helloWorldService.eba
    com.ibm.ws.eba.helloWorldService_0001.eba "" 1 false DEFAULT]]
  -MapTargets [[ebaDeploymentUnit WebSphere:cluster=cluster1]]
  -ActivationPlanOptions [[default ""]]
  ...
]')
If the target is two servers, the jython syntax for this aspect of the command is as follows::
AdminTask.addCompUnit('[
  -blaID WebSphere:blaname=bla_name
  -cuSourceID WebSphere:assetname=asset_name.eba
  -CUOptions [
    [WebSphere:blaname=bla_name.eba
    WebSphere:assetname=asset_name.eba
    cu_name "optional_cu_description" 1 false DEFAULT]]
  -MapTargets [
    [ebaDeploymentUnit WebSphere:node=node_name,server=server_name 
                       WebSphere:node=node2_name,server=server2_name]]
  -ActivationPlanOptions [[default ""]]
  ...
]')
For example:
AdminTask.addCompUnit('[
  -blaID WebSphere:blaname=helloWorldService
  -cuSourceID WebSphere:assetname=com.ibm.ws.eba.helloWorldService.eba
  -CUOptions [
    [WebSphere:blaname=helloWorldService.eba
    WebSphere:assetname=com.ibm.ws.eba.helloWorldService.eba
    com.ibm.ws.eba.helloWorldService_0001.eba "" 1 false DEFAULT]]
  -MapTargets [[ebaDeploymentUnit WebSphere:node=node01,server=server1+
                                  WebSphere:node=node01,server=web1]]
  -ActivationPlanOptions [[default ""]]
  ...
]')
Define WAB context roots.

Context roots determine where the web pages of a particular web application bundle (WAB) are found at run time. The context root that you specify here is combined with the defined server mapping to compose the full URL that you enter to access the pages of the WAB. For example, if the application server default host is www.example.com:8080 and the context root of the WAB is /sample, the web pages are available at www.example.com:8080/sample.
The jython syntax for this aspect of the command is as follows.
For composite bundles, the syntax is slightly different. See Step: Define context roots for web application bundles (WABs) in composite bundles. The bundles listed under the ContextRootStep need to be all the WABs contained in the OSGi application.
AdminTask.addCompUnit('[
  ...
  -ContextRootStep [
    [bundle_symbolic_name_1 bundle_version_1 context_root_1]
    [bundle_symbolic_name_2 bundle_version_2 context_root_2]]
  ...
]')
For example, for an EBA file that contains two WABs (com.ibm.ws.eba.helloWorldService.web at version 1.0.0, which is to be mapped to /hello/web, and com.ibm.ws.eba.helloWorldService.withContextRoot at version 0.9.0, which is to be mapped to /hello/service), this aspect of the command is as follows:
AdminTask.addCompUnit('[
  ...
  -ContextRootStep [
    [com.ibm.ws.eba.helloWorldService.web 1.0.0 "/hello/web"]
    [com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "/hello/service"]]
  ...
]')
Map WABs to virtual hosts.

You use a virtual host to associate a unique port with a web application. The aliases of a virtual host identify the port numbers defined for that virtual host. A port number specified in a virtual host alias is used in the URL used to access artifacts such as servlets and JavaServer Page (JSP) files in a web application. For example, the alias myhost:8080 is the host_name:port_number portion of the URL //publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/ ://myhost:8080/sample.
Each WAB that is contained in a deployed asset must be mapped to a virtual host. WABs can be installed on the same virtual host, or dispersed among several virtual hosts.
If you specify an existing virtual host in the ibm-web-bnd.xml or .xmi file for a given WAB, the specified virtual host is set by default. Otherwise, the default virtual host setting is default_host, which provides several port numbers through its aliases:

80

An internal, insecure port used when no port number is specified

9080

An internal port

9443

An external, secure port

Unless to isolate your WAB from other WABs or resources on the same node, default_host is a suitable virtual host. In addition to default_host, WAS provides admin_host, which is the virtual host for the administrative console system application. admin_host is on port 9060. Its secure port is 9043. Do not select admin_host unless the WAB relates to system administration.
The jython syntax for this aspect of the command is as follows.
For composite bundles, the syntax is slightly different. See Step: Map WABs in composite bundles to virtual hosts.
AdminTask.addCompUnit('[
  ...
  -VirtualHostMappingStep [
    [bundle_symbolic_name_1 bundle_version_1
    web_module_name_1 virtual_host_1]
    [bundle_symbolic_name_2 bundle_version_2
     web_module_name_2 virtual_host_2]]
  ...
]')
For example, for an EBA file containing two WABs (com.ibm.ws.eba.helloWorldService.web at version 1.0.0, which is to be mapped to default_host, and com.ibm.ws.eba.helloWorldService.withContextRoot at version 0.9.0, which is to be mapped to test_host), this aspect of the command is as follows:
AdminTask.addCompUnit('[
  ...
  -VirtualHostMappingStep [
    [com.ibm.ws.eba.helloWorldService.web 1.0.0
    "HelloWorld service" default_host]
    [com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0
    "HelloWorld second service" test_host]]
  ...
]')
Map security roles to users or groups.

The jython syntax for this aspect of the command is as follows:
AdminTask.addCompUnit('[
  ...
  -MapRolesToUsersStep [
    [role_name everyone?
    all_authenticated_in_realm?
    usernames groups]]
  ...
]')
Key:

role_name is a role name defined in the application.
everyone? is set to Yes or No, to specify whether or not everyone is in the role.
all_authenticated_in_realm? is set to Yes or No, to specify whether or not all authenticated users can access the application realm.
usernames is a list of WAS user names, separated by the "|" character.
groups is a list of WAS groups, separated by the "|" character.

For usernames, and groups, the empty string "" means "use the default or existing value". The default value is usually that no users or groups 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. For example:
AdminTask.addCompUnit('[
  ...
  -MapRolesToUsersStep [
    [ROLE1 No Yes "" ""]
    [ROLE2 No No WABTestUser1 ""]
    [ROLE3 No No "" WABTestGroup1]
    [ROLE4 Yes No "" ""]]
  ...
]')
For more information about the -MapRolesToUsersStep option, see the information for the $AdminApp install command "MapRolesToUsers" option. This is the equivalent option for Java EE applications. For more general information, see Security role to user or group mapping.
Map RunAs roles to users
We can map a specified user identity and password to a RunAs role. This enables you to specify application-specific privileges for individual users, so that they can run specific tasks using another user identity. The jython syntax for this aspect of the command is as follows:
AdminTask.addCompUnit('[
  ...
  -MapRunAsRolesToUsersStep [
    [role_name user_name password]]
]')
For example:
AdminTask.addCompUnit('[
  ...
  -MapRunAsRolesToUsersStep [
    [Role1 User1 password1]
    [AdminRole User3 password3]]
]')
For more information about the -MapRunAsRolesToUsers option, see the information for the $AdminApp install command "MapRunAsRolesToUsers" option. This is the equivalent option for Java EE applications. For more general information, see Map RunAs roles to users.
Add authentication aliases to Blueprint resource references.

Blueprint components can access WAS resource references. Each reference is declared in a Blueprint XML file, and can be secured using a Java EE Connector Architecture (JCA) authentication alias. Each bundle in an OSGi application can contain any number of resource reference declarations in its various Blueprint XML files.
When you secure resource references, those resource references can be bound only to JCA authentication aliases that exist on every server or cluster on which the application is deployed. An OSGi application can be deployed to multiple servers and clusters that are in the same security domain. Therefore, each JCA authentication alias must exist in either the security domain of the target servers and clusters, or the global security domain.
We must declare the resource references in the Blueprint XML file. For example:
<blueprint xmlns="//publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/  ://www.osgi.org/xmlns/blueprint/v1.0.0"
  xmlns:rr="//publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/  ://www.ibm.com/appserver/schemas/8.0/blueprint/resourcereference">


<rr:resource-reference id="resourceRef"
          interface="javax.sql.DataSource"
          filter="(osgi.jndi.service.name=jdbc/Account)">
<rr:res-auth>Container
</rr:res-auth>
<rr:res-sharing-scope>Shareable
</rr:res-sharing-scope>
</rr:resource-reference>
</blueprint> 
This declaration includes the resource reference ID (for example resourceRef), the service filter (for example jdbc/Account), the authentication type (for example Container), and the sharing setting (for example Shareable).
The Blueprint resource references to authentication alias bindings for each bundle are stored in a file ibm-eba-bnd.xml in the META-INF directory of that bundle. If an OSGi application contains any of these files when it is deployed as an asset, these files provide the default authentication alias values that are used when binding the resource references. For example:
<eba-bnd xmlns="//publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/  ://www.ibm.com/blueprintbinding.xsd">
<resource-ref>
<jndi-name>jdbc/Acount
</jndi-name>
<authentication-alias>Alias1
</authentication-alias>
<interface>javax.sql.DataSource
</interface>
<authentication>Container
</authentication>
<sharing-scope>Shareable
</sharing-scope>
<id>resourceRef
</id>
</resource-ref>
</eba-bnd> 
The jython syntax for this aspect of the command is as follows.
For composite bundles, the syntax is slightly different. See Step: Add authentication aliases to Blueprint resource references in composite bundles.
AdminTask.addCompUnit('[
  ...
  -BlueprintResourceRefBindingStep [
    [
    bundle_symbolic_name
    bundle_version
    blueprint_resource_reference_id
    interface_name
    jndi_name
    authentication_type
    sharing_setting
    authentication_alias_name
    ]]
  ...
]')
The value for jndi_name must match the jndi name that you declare in the filter attribute of the resource reference element in the Blueprint XML file. For example, for an EBA file that contains a bundle com.ibm.ws.eba.helloWorldService.properties.bundle.jar at v1.0.0, which is to be bound to authentication alias alias1, the command is as follows:
AdminTask.addCompUnit('[
  ...
  -BlueprintResourceRefBindingStep[
    [com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
    javax.sql.DataSource jdbc/Account Container Shareable alias1]]
  ...
]')
Bind web module message destination and resource environment references.

Binding a resource reference maps a resource dependency of the web application to an actual resource available in the server runtime environment. At a minimum, this can be achieved by using a mapping that specifies the JNDI name under which the resource is known in the runtime environment. By default, the JNDI name is the resource ID specified in the web.xml file during development of the web application bundle (WAB). Use this option to bind 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.
The jython syntax for this aspect of the command is as follows.
For composite bundles, the syntax is slightly different. See Step: Bind web module message destination and resource environment references in composite bundles.
AdminTask.addCompUnit('[
  ...
  -WebModuleMsgDestRefs [
    [
    bundle_symbolic_name
    bundle_version
    resource_reference_id
    resource_type
    target_jndi_name
    ]]
  ...
]')
For example:
AdminTask.addCompUnit('[
  ...
  -WebModuleMsgDestRefs [
    [com.ibm.ws.eba.helloWorldService.web 1.0.0
    jms/myQ javax.jms.Queue
    jms/workQ]
    [com.ibm.ws.eba.helloWorldService.web 1.0.0
    jms/myT javax.jms.Topic
    jms/notificationTopic]]
  ...
]')
Bind web module resource references.

Binding a resource reference maps a resource dependency of the web application to an actual resource available in the server runtime environment. At a minimum, this can be achieved by using a mapping that specifies the JNDI name under which the resource is known in the runtime environment. By default, the JNDI name is the resource ID specified in the web.xml file during development of the web application bundle (WAB). Use this option to bind resources of type resource-ref (resource reference), as defined in the Java specification JSR-250: Common Annotations for the Java Platform.
The jython syntax for this aspect of the command is as follows.
For composite bundles, the syntax is slightly different. See Step: Bind web module resource references in composite bundles.
AdminTask.addCompUnit('[
  ...
  -WebModuleResourceRefs [
    [
    bundle_symbolic_name
    bundle_version
    resource_reference_id
    resource_type
    target_jndi_name
    login_configuration
    login_properties
    extended_properties
    ]]
  ...
]')
For example:
AdminTask.addCompUnit('[
  ...
  -WebModuleResourceRefs [
    [com.ibm.ws.eba.helloWorldService.web 1.0.0
    jdbc/jtaDs javax.sql.DataSource
    jdbc/helloDs "" "" ""]
    [com.ibm.ws.eba.helloWorldService.web 1.0.0
    jdbc/nonJtaDs javax.sql.DataSource
    jdbc/helloDsNonJta "" "" "extprop1=extval1"]]
  ...
]')
If you use multiple extended properties, the jython syntax is "extprop1=extval1,extprop2=extval2".
In the following example, the jython syntax from the previous individual substeps is combined so that, by running the addCompUnit command once only, a composition unit is created and added to a business-level application.
If your EBA asset includes or references composite bundles, the command syntax is slightly different. For an equivalent example, see Example: Using the addCompUnit command to add an EBA asset that includes composite bundles.
AdminTask.addCompUnit('[
  -blaID WebSphere:blaname=helloWorldService
  -cuSourceID WebSphere:assetname=com.ibm.ws.eba.helloWorldService.eba
  -CUOptions [
    [WebSphere:blaname=helloWorldService.eba
    WebSphere:assetname=com.ibm.ws.eba.helloWorldService.eba
    com.ibm.ws.eba.helloWorldService_0001.eba "" 1 false DEFAULT]]
  -MapTargets [[ebaDeploymentUnit WebSphere:cluster=cluster1]]
  -ActivationPlanOptions [[default ""]]
  -ContextRootStep [
    [com.ibm.ws.eba.helloWorldService.web 1.0.0 "/hello/web"]
    [com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "/hello/service"]]
  -VirtualHostMappingStep [
    [com.ibm.ws.eba.helloWorldService.web 1.0.0
    "HelloWorld service" default_host]
    [com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0
    "HelloWorld second service" test_host]]
  -MapRolesToUsersStep [
    [ROLE1 No Yes "" ""]
    [ROLE2 No No WABTestUser1 ""]
    [ROLE3 No No "" WABTestGroup1]
    [ROLE4 Yes No "" ""]]
  -MapRunAsRolesToUsersStep [
    [Role1 User1 password1]
    [AdminRole User3 password3]]
  -BlueprintResourceRefBindingStep[
    [com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
    javax.sql.DataSource jdbc/Account
    Container Shareable alias1]]
  -WebModuleMsgDestRefs [
    [com.ibm.ws.eba.helloWorldService.web 1.0.0
    jms/myQ javax.jms.Queue
    jms/workQ]
    [com.ibm.ws.eba.helloWorldService.web 1.0.0
    jms/myT javax.jms.Topic
    jms/notificationTopic]]
  -WebModuleResourceRefs [
    [com.ibm.ws.eba.helloWorldService.web 1.0.0 jdbc/jtaDs javax.sql.DataSource
    jdbc/helloDs "" "" ""]
    [com.ibm.ws.eba.helloWorldService.web 1.0.0 jdbc/nonJtaDs javax.sql.DataSource
    jdbc/helloDsNonJta "" "" "extprop1=extval1"]]
]')
Configure the HTTP session manager.

To configure the HTTP session manager, you use the AdminConfig commands to configure the deployed object represented by the appDeploy variable. Session management for OSGi applications is configured in the same way as for enterprise applications, except for a minor difference in syntax when getting the deployed object.
Get the deployed object.

Use the instructions given in Configure applications for session management using scripting. Note that, for enterprise applications, you use the following two line script:
deployments = AdminConfig.getid('/Deployment:myApp/')
appDeploy = AdminConfig.showAttribute(deployments, 'deployedObject')
For OSGi applications, the equivalent script is the following single line:
appDeploy = AdminTask.getOSGiApplicationDeployedObject('-cuName cu_name')
where cu_name is the name of the composition unit. For example:
appDeploy = AdminTask.getOSGiApplicationDeployedObject('
  -cuName com.ibm.ws.eba.helloWorldService_0001.eba')
Create the session management options.
Use the instructions given in Configure applications for session management using scripting. The command usage for creating the session management options is exactly the same for enterprise applications and OSGi applications.
What to do next

After using these commands, save changes to the master configuration by using the following command:
AdminConfig.save()
After you import the enterprise bundle archive (EBA) file for your OSGi application as an asset, you can update versions of existing bundles but you cannot add extra bundles to the asset. However, after we have added the asset as a composition unit to a business-level application, you can extend the business-level application by adding one or more composite bundles to the composition unit. See Add or removing extensions for an OSGi composition unit using wsadmin.
You are now ready to start your business-level application.

Subtopics

Add an EBA asset that includes composite bundles using the addCompUnit command
We can use the addCompUnit command to add a composition unit that contains a previously-imported enterprise bundle archive (EBA) asset plus configuration information. If the EBA asset includes composite bundles, the command syntax is slightly different.

Parent topic: Deploy an OSGi application as a business-level application
Related concepts:

About OSGi Applications
JMS and OSGi Applications
Assets
Business-level applications
Composition units
Virtual hosts
Security domains
Related tasks:

Add an EBA asset to a composition unit
Secure OSGi Applications
Manage composition units using wsadmin.sh
Configure applications for session management using scripting
Update bundle versions for an EBA asset
Related reference:

OSGi Applications: Troubleshooting tips
BLAManagement command group using wsadmin.sh
Options for the AdminApp object install
Related information:

Blueprint resource reference bindings [Settings]
Context root for web application bundles [Settings]
Security role to user or group mapping [Settings]
Map RunAs roles to users [Collection]
Virtual hosts for web application bundles [Settings]
Web module message destination and resource environment reference bindings [Settings]
Web module resource reference bindings [Settings]
Web module resource references: Available resources [Collection]
Task topic Feedback
Copyright IBM Corporation 2009, 2011. All Rights Reserved.
This information center is powered by Eclipse technology.

+
Search Tips | Advanced Search