You 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, JNDI mappings for Session enterprise beans, JNDI mappings for EJB references, and web application or Blueprint resource reference bindings for your OSGi application.
You can add an EBA asset to a business-level application by using wsadmin commands as described in this topic, or by using the administrative console as described in Adding an EBA asset to a composition unit by 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, therefore only one instance of an OSGi application can be deployed in a cell.
print AdminConfig.list('VirtualHost')
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 you must run the addCompUnit command before you configure the HTTP session manager.
In addition to specifying the configuration information for the EBA asset through the following procedure, you can also change it later as described in Modifying the configuration of an OSGi composition unit by using wsadmin commands. 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.
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, you must 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.
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 ""]]
...
]')
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 ""]]
...
]')
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.
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"]]
...
]')
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.
AdminTask.addCompUnit('[
...
-MDBBindingsStep [
[bundle_symbolic_name_1 bundle_version_1 uri_1
activation_spec_1 destination_jndi_name_1 authentication_alias_1]
[bundle_symbolic_name_2 bundle_version_2 uri_2
activation_spec_2 destination_jndi_name_2 authentication_alias_2]]
...
]')
In the following example, an EBA file contains two EJB bundles, com.ibm.ws.eba.currencyService at version 1.0.0, and com.ibm.ws.eba.accountService at version 0.9.0. The currencyService bundle contains a message-driven bean called ExchangeRateMDB, bound to an activation specification with a JNDI name of eis/ExchangeRate_Act_Spec; the destination JNDI name that is defined in the activation specification is overridden by a destination whose JNDI name is jms/ExchangeRateQueue, and the authentication alias that is defined in the activation specification is overridden by an authentication alias called ExchangeRate_Auth_Alias. The accountService bundle contains an MDB called CustomerDetailsMDB, bound to an activation specification with a JNDI name of eis/CustomerDetails_Act_Spec; the destination JNDI name that is defined in the activation specification is overridden by a destination whose JNDI name is jms/CustomerDetailsQueue, and the authentication alias that is defined in the activation specification is overridden by an authentication alias called CustomerDetails_Auth_Alias.AdminTask.addCompUnit('[
...
-MDBBindingsStep [
[com.ibm.ws.eba.currencyService 1.0.0 META-INF/ejb-jar.xml/ExchangeRateMDB
eis/ExchangeRate_Act_Spec jms/ExchangeRateQueue ExchangeRate_Auth_Alias]
[com.ibm.ws.eba.accountService 0.9.0 META-INF/ejb-jar.xml/CustomerDetailsMDB
eis/CustomerDetails_Act_Spec jms/CustomerDetailsQueue CustomerDetails_Auth_Alias]]
...
]')
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.
AdminTask.addCompUnit('[
...
-EJBMappingsStep [
[bundle_symbolic_name_1 bundle_version_1 ejb_name_1
ejb_interface_1 ejb_iterface_type_1 jndi_name_1]
[bundle_symbolic_name_2 bundle_version_2 ejb_name_2
ejb_interface_2 ejb_iterface_type_2 jndi_name_2]]
...
]')
In the following example, an EBA file contains two EJB bundles, com.ibm.ws.eba.currencyService at version 1.0.0, and com.ibm.ws.eba.accountService at version 0.9.0. The currencyService bundle contains an enterprise bean called ExchangeRate_ejb, with a Local interface called com.ibm.ws.eba.ejb.ExchangeRate, that is mapped to a JNDI name of ejb/ExchangeRate. The accountService bundle contains an enterprise bean called CustomerDetails_ejb, with a Remote interface called com.ibm.ws.eba.ejb.CustomerDetails, that is mapped to a JNDI name of ejb/CustomerDetails.AdminTask.addCompUnit('[
...
-EJBMappingsStep [
[com.ibm.ws.eba.currencyService 1.0.0 ExchangeRate_ejb
com.ibm.ws.eba.ejb.ExchangeRate Local ejb/ExchangeRate]
[com.ibm.ws.eba.accountService 0.9.0 CustomerDetails_ejb
com.ibm.ws.eba.ejb.CustomerDetails Remote ejb/CustomerDetails]]
...
]')
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.
AdminTask.addCompUnit('[
...
-EJBRefStep [
[bundle_symbolic_name_1 bundle_version_1 uri_1
ejb_reference_name_1 business_interface_1 jndi_name_1]
[bundle_symbolic_name_2 bundle_version_2 uri_2
ejb_reference_name_2 business_interface_2 jndi_name_2]]
...
]')
The uri parameter specifies the location where the EJB reference is defined.AdminTask.addCompUnit('[
...
-EJBRefStep [
[com.ibm.ws.eba.currencyService 1.0.0 META-INF/ejb-jar.xml/CurrencyExchange
ExchangeRate com.ibm.ws.eba.ejb.ExchangeRate ejb:ExchangeRate]
[com.ibm.ws.eba.accountService 0.9.0 WEB-INF/web.xml
CustomerDetails com.ibm.ws.eba.ejb.CustomerDetails ejb:CustomerDetails]]
...
]')
Binding a resource reference maps a resource dependency of an enterprise bean to an actual resource available in the server runtime environment. At a minimum, you can be achieve this mapping by specifying the JNDI name under which the resource reference is known in the runtime environment. By default, the JNDI name is retrieved from pre-existing bindings, or set to the value of the mapped-name specified in the resource reference definition. 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.
AdminTask.addCompUnit('[
...
-EJBResourceRefs [
[
bundle_symbolic_name
bundle_version
ejb_name
resource_reference_id
resource_type
target_jndi_name
resource_authentication_method
mapping_properties
extended_properties
]]
...
]')
WebSphere:name=property_name1,value=property_value1,description=property_description1
+WebSphere:name=property_name2,value=property_value2,description=property_description2
+ ...
property_name1=property_value1+property_name2=property_value2+ ...
AdminTask.addCompUnit('[
...
-EJBResourceRefs [
[com.ibm.ws.eba.currencyService 1.0.0 ExchangeRate
dataSource1 javax.sql.DataSource ref/ds1 ClientContainer
"WebSphere:name=mprop1,value=val1,description=desc1"
"exprop1=expropval1+exprop2=expropval2"]
[com.ibm.ws.eba.accountService 0.9.0 CustomerDetails
dataSource2 javax.sql.DataSource ref/ds2 WSLogin "" ""]]
...
]')
Binding a message destination reference or resource environment reference maps a resource dependency of an enterprise bean to an actual resource available in the server runtime environment. At a minimum, you can achieve this mapping by specifying the JNDI name under which the message destination reference or resource environment reference is known in the runtime environment. By default, the JNDI name is retrieved from pre-existing bindings, or set to the value of the mapped-name specified in the message destination reference definition. 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.
AdminTask.addCompUnit('[
...
-EJBMsgDestRefs [
[
bundle_symbolic_name
bundle_version
ejb_name
resource_reference_id
resource_type
target_jndi_name
]]
...
]')
For example:AdminTask.addCompUnit('[
...
-EJBMsgDestRefs [
[com.ibm.ws.eba.currencyService 1.0.0 ExchangeRate
jms/myQ javax.jms.Queue jms/workQ]
[com.ibm.ws.eba.accountService 0.9.0 CustomerDetails
jms/myT javax.jms.Topic jms/notificationTopic]]
...
]')
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.
AdminTask.addCompUnit('[
...
-EJBEnvEntryStep [
[
bundle_symbolic_name
bundle_version
ejb_name
env_entry_name
env_entry_type
env_entry_description
env_entry_value
]]
...
]')
For example:AdminTask.addCompUnit('[
...
-EJBEnvEntryStep [
[com.ibm.ws.eba.currencyService 1.0.0
ExchangeRate CommissionRate java.lang.Double
"Commission rate applied to currency exchange transactions." 5.75]]
...
]')
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 that is 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 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.
Unless you want 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, 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.
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]]
...
]')
AdminTask.addCompUnit('[
...
-MapRolesToUsersStep [
[role_name everyone?
all_authenticated_in_realm?
usernames groups]]
...
]')
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.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.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 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.
<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 Container), and the sharing setting
(for example Shareable).<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>
AdminTask.addCompUnit('[
...
-BlueprintResourceRefBindingStep [
[
bundle_symbolic_name
bundle_version
blueprint_resource_reference_id
interface_name
jndi_name
authentication_type
sharing_setting
authentication_alias_name
]]
...
]')
AdminTask.addCompUnit('[
...
-BlueprintResourceRefBindingStep[
[com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
javax.sql.DataSource jdbc/Account Container Shareable alias1]]
...
]')
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, you can achieve this mapping by specifying 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). 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.
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]]
...
]')
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, you can achieve this mapping by specifying 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). 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.
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"]]
...
]')
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"]]
-EJBMappingsStep [
[com.ibm.ws.eba.currencyService 1.0.0 ExchangeRate_ejb
com.ibm.ws.eba.ejb.ExchangeRate Local ejb/ExchangeRate]
[com.ibm.ws.eba.accountService 0.9.0 CustomerDetails_ejb
com.ibm.ws.eba.ejb.CustomerDetails Remote ejb/CustomerDetails]]
-EJBRefStep [
[com.ibm.ws.eba.currencyService 1.0.0 META-INF/ejb-jar.xml/CurrencyExchange
ExchangeRate com.ibm.ws.eba.ejb.ExchangeRate ejb:ExchangeRate]
[com.ibm.ws.eba.accountService 0.9.0 WEB-INF/web.xml
CustomerDetails com.ibm.ws.eba.ejb.CustomerDetails ejb:CustomerDetails]]
-EJBResourceRefs [
[com.ibm.ws.eba.currencyService 1.0.0 ExchangeRate
dataSource1 javax.sql.DataSource ref/ds1 ClientContainer
"WebSphere:name=mprop1,value=val1,description=desc1"
"exprop1=expropval1+exprop2=expropval2"]
[com.ibm.ws.eba.accountService 0.9.0 CustomerDetails
dataSource2 javax.sql.DataSource ref/ds2 WSLogin "" ""]]
-EJBMsgDestRefs [
[com.ibm.ws.eba.currencyService 1.0.0 ExchangeRate
jms/myQ javax.jms.Queue jms/workQ]
[com.ibm.ws.eba.accountService 0.9.0 CustomerDetails
jms/myT javax.jms.Topic jms/notificationTopic]]
-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"]]
]')
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.
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')
Use the instructions given in Configuring 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.
AdminConfig.save()
You are now ready to start your business-level application.