Use the addCompUnit command to add an
enterprise bundle application (EBA) composition unit that consists
of a previously-imported EBA asset plus configuration information. Configuration information includes the context roots, virtual hosts, security role mappings, and web module or Blueprint resource bindings for your OSGi application.
Before you begin
You can add an EBA asset to a business-level application
by using the addCompUnit command as described in
this topic, or by using the administrative console as described in Adding an EBA asset to a business-level application using the administrative console.
An EBA asset can be added to only one business-level application. A business-level application is scoped to cell scope, so this means that only one instance of a given OSGi application can be deployed in a cell.
This
task makes the following assumptions:
About this task
An EBA composition unit consists of a previously-imported EBA asset, plus 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 application's context roots or virtual
hosts.
- Bindings to any associated web modules or blueprint resource references.
- Mappings from security roles to particular users or groups.
This topic includes a brief description of the main elements that you need to configure when adding an EBA asset. For
a more complete description of the addCompUnit command
and its parameters, see Managing composition units using wsadmin
scripting and BLAManagement command group for the AdminTask
object using wsadmin scripting.
For clarity, each of
the following steps describes the syntax for adding a single element
to the EBA composition unit. However, to create the composition unit
you run the addCompUnit command only once. Therefore, when you run the command, you must combine these elements together. An example of the combined syntax is given after the separate steps.
You specify the configuration information for the EBA asset during the following procedure and you cannot change it later. For example, if you subsequently update a bundle in an EBA asset, you cannot introduce anything that requires additional configuration, for example new resource references.
Procedure
- Add the previously-imported asset (the .eba file) as a deployed asset.
The parameters for this aspect of the
addCompUnit wsadmin
command are as follows:
- -blaID
- Specifies the configuration ID of the business-level application.
- -cuSourceID
- Specifies the ID of the EBA asset that is being added to the business-level
application.
- -CUOptions
- Specifies the 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.
The jython syntax for this aspect of the command is as follows:
If the target is one cluster:
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.eba "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:
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.eba "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.
The bundles listed under the ContextRootStep need to be all the WAB modules 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 containing 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 module or 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 that is used to access artifacts such as servlets and JavaServer Page (JSP) files in a web module. For example, the alias myhost:8080 is the host_name:port_number portion of the URL http://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 you want to isolate your WAB from other WABs or resources on the same node (physical machine), default_host is a suitable virtual host. In addition to default_host, WebSphere® Application Server 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:
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 WebSphere Application Server user names, separated
by the "|" character.
- groups is a list of WebSphere Application Server groups, separated
by the "|" character.
Note: 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 you want 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.
- Add authentication aliases to Blueprint resource references.
Blueprint components can access WebSphere Application Server resource references. Each reference is declared in a Blueprint XML file, and can be secured using a Java Platform, Enterprise Edition (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 that the OSGi application is deployed to. 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.
You must declare the resource references in the Blueprint
XML file. For example:
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:rr="http://www.ibm.com/appserver/schemas/8.0/blueprint/resourcereference">
<!-- Other Blueprint declarations ... -->
<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
Application), 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>
<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:
AdminTask.addCompUnit('[
...
-BlueprintResourceRefBindingStep [
[
bundle_symbolic_name
bundle_version
blueprint_resource_reference_id
interface_name
jndi_name
authentication_type
sharing_setting
authentication_alias_name
]]
...
]')
Note: 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 Version 1.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 resource references.
Binding a resource reference maps a resource dependency of the web module 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 that you specified in the web.xml file during development of the web application bundle (WAB).
The jython syntax for this aspect of the command is as follows:
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"]]
...
]')
Note: If you use multiple extended properties, the jython syntax is "extprop1=extval1,extprop2=extval2".
Example
In the following example, the jython syntax from the previous
individual steps is combined so that, by running the
addCompUnit command
once only, an EBA composition unit is created and added to a business-level
application:
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 "" ""]]
-BlueprintResourceRefBindingStep[
[com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
javax.sql.DataSource jdbc/Account
Container Shareable alias1]]
-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"]]
]')
What to do next
After using the command, save your changes to the
master configuration by using the following command:
AdminConfig.save()
You are
now ready to start your business-level application.