You can use the Jython scripting language to configure
and administer business-level applications with the wsadmin tool.
Use the commands and parameters in the BLAManagement group to create,
edit, export, delete, and query business-level applications in your
configuration.
In order to configure and administer business-level applications
you must use the Configurator administrative role.
An asset
represents one or more application binary files that are stored in
an asset repository. Typical assets include application business logic
such as enterprise archives, library files, and other resource files.
Use the following commands to manage your asset configurations:
A business-level application is a configuration artifact
that consists of zero or more composition units or other business-level
applications. Business-level applications are administrative models
that define an application, and can contain enterprise archive (EAR)
files, shared libraries, PHP applications, and more. Use the following
commands to configure and administer business-level applications:
A composition unit represents an asset in a business-level
application. A composition unit enables the asset contents to interact
with other assets in the application. It also enables the product
run time to load and run asset contents. Use the following commands
to manage your composition unit configurations:
deleteAsset
The deleteAsset command
removes an asset from your business-level application configuration.
Before using this command, verify that no composition units are associated
with the asset of interest. The command fails if the asset is associated
with composition units.
Target object
None
Required parameters
- -assetID
- Specifies the configuration ID of the asset to delete. The command
accepts incomplete IDs for the assetID parameter, as long as the system
can match the string to a unique asset. (String, required)
Optional parameters
- -force
- Specifies whether to force the system to delete the asset, even
if other assets depend on this asset. (Boolean, optional)
Return value
The
command returns the configuration ID of the deleted asset, as the
following example displays:
WebSphere:assetname=asset2.zip
Batch mode example usage
- Using Jython string:
AdminTask.deleteAsset('-assetID asset2.zip -force true')
- Using Jython list:
AdminTask.deleteAsset(['-assetID', 'asset2.zip', '-force', 'true'])
Interactive mode example usage
- Using Jython:
AdminTask.deleteAsset('-interactive')
editAsset
The
editAsset command modifies additional asset configuration options.
You can use this command to modify the description, destination URL,
asset relationships, file permissions, and validation settings.
Target object
None
Required parameters
- -assetID
- Specifies the configuration ID of the asset to edit. This parameter
accepts an incomplete configuration ID, as long as the system can
match the string to a unique asset ID. (String, required)
Optional steps
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If you do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.- -AssetOptions
- Use the AssetOptions step and the following arguments to set additional
properties for the asset.
- inputAsset (read-only)
- Specifies the source package of the asset.
- name (read-only)
- Specifies the name of the asset. The default value for this argument
is the file name of the source package.
- defaultBindingProps (read-only)
- Specifies the default binding properties for the asset. This argument
only applies to enterprise assets. For assets which are not enterprise
assets, specify the asterisk character (*) for pattern matching. For
enterprise assets, specify the .* value to set the
argument as a non-empty value.
- description
- Specifies a description for the asset.
- destinationUrl
- Specifies the URL of the asset binaries to deploy.
- typeAspect
- Specifies the asset type aspect.
- relationship
- Specifies the asset relationship. Use the plus sign character
(+) to add additional assets to the existing relationship. Use the
number sign character (#) to delete an existing asset from the relationship.
To replace the existing relationships, specify the same syntax as
in the importAsset command. If the asset specified in the relationship
does not exist for add or update, the command returns an exception.
- filePermission
- Specifies the file permission configuration.
- validate
- Specifies whether to validate the asset. The default value is false.
The product does not save the value specified for validate. Thus,
if you select to validate the asset (true) now and
later edit the asset, when you edit the asset you must enable this
setting again for the product to validate the updated files.
- -UpdateAppContentVersions
- For an EBA asset, use this step and the following arguments to
select bundle versions for the asset.
For transitioning users: In
the WebSphere® Application
Server 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.
In Version 8.x, these changes are applied by updating the composition
unit. The new approach in Version 8.x means that many bundle changes
can be applied in place, without restarting the running business-level
application. To enable this new approach, the
UpdateAppContentVersionsStep parameter
has been replaced with the
UpdateAppContentVersions parameter,
and instead of restarting the business-level application you run the
editCompUnit command
with the
CompUnitStatusStep parameter.
trns
- bundle_name
- Specifies the name of the bundle.
- current_version
- Specifies either a bundle version number, for example 1.0.0,
or NOT_DEPLOYED for shared bundles
(that is, use bundles) that are declared in the application
manifest but not deployed by the runtime environment. This argument
describes the current configuration of the bundle, and is not used
to change the configuration.
- update_preference
- Specifies the new bundle version preference. This is either a
bundle version number, for example 1.0.0,
or NOT_DEPLOYED for shared bundles,
or NO_PREF if you want the system
to choose a bundle version for you. If you do not want to update the
version for a given bundle, set this attribute to the same value that
you are using for the current_version attribute.
- Include an entry (that is, the bundle_name current_version and update_preference)
for each bundle that is listed in the application manifest between
the application content header and the use bundle header. Include
every bundle, whether or not you are updating the bundle version.
- Specify the syntax as follows:
AdminTask.editAsset('[
-assetID asset_name
-UpdateAppContentVersions [
[bundle_1_name current_version update_preference]
[bundle_2_name current_version update_preference]
[bundle_3_name current_version update_preference]
[bundle_4_name current_version update_preference]
[bundle_5_name current_version update_preference]
]]')
Return value
The
command returns the configuration ID of the asset of interest.
Batch mode example usage
Use the following
examples to edit a non-enterprise asset:
- Using Jython string:
AdminTask.editAsset('-assetID asset3.zip –AssetOptions [[.* asset3.zip * "asset for testing"
c:/installedAssets/asset3.zip/BASE/asset3.zip "" assetname=a.jar "" false]]')
- Using Jython list:
AdminTask.editAsset(['-assetID', 'asset3.zip', '–AssetOptions', '[[.* asset3.zip * "asset for testing"
c:/installedAssets/asset3.zip/BASE/asset3.zip "" assetname=a.jar "" false]]'])
Use the following examples to edit an enterprise asset:
- Using Jython string:
AdminTask.editAsset('-assetID defaultapp.ear –AssetOptions
[[.* defaultapp.ear .* "asset for testing" "" "" "" "" false]]')
- Using Jython list:
AdminTask.editAsset(['-assetID', 'defaultapp.ear', '–AssetOptions',
'[[.* defaultapp.ear .* "asset for testing" "" "" "" "" false]]'])
Interactive mode example usage
- Using Jython:
AdminTask.editAsset('-interactive')
exportAsset
The
exportAsset command exports an asset configuration to a file.
Target object
None
Required parameters
- -assetID
- Specifies the configuration ID of the asset to export. This parameter
accepts an incomplete configuration ID as long as the ID matches a
unique asset. (String, required)
- -filename
- Specifies the file name to which the system exports the asset
configuration. (DownloadFile, required)
Return value
The
command does not return output.
Batch
mode example usage
- Using Jython string:
AdminTask.exportAsset('-assetID asset2.zip –filename c:/temp/a2.zip')
- Using Jython list:
AdminTask.exportAsset(['-assetID', 'asset2.zip', '–filename', 'c:/temp/a2.zip'])
Interactive mode example usage
- Using Jython:
AdminTask.exportAsset('-interactive')
importAsset
The
importAsset command imports an asset configuration to the asset repository.
After importing assets, you can add the assets to business-level applications
as composition units.
Target object
None
Required parameters
- -source
- Specifies the name of the source file to import. (UploadFile,
required)
Optional parameters
- -storageType
- Specifies the way the system saves the asset in the asset repository.
The default asset repository stores full binaries, metadata of binaries,
or no binaries. Specify FULL to store full binaries.
Specify METADATA to store the metadata portion of
the binaries. Specify NONE to store no binaries in
the asset repository. The default value is FULL.
(String, optional)
Optional steps
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If you do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.- -AssetOptions
- Use the AssetOptions step and the following arguments to set additional
properties for the asset.
- inputAsset (read-only)
- Specifies the source package of the asset.
- name
- Specifies the name of the asset. The extension file name of the
asset must match the extension file name of the source package. The
default value for this argument is the file name of the source package.
- defaultBindingProps (read-only)
- Specifies the default binding properties for the asset. This argument
only applies to enterprise assets. For assets which are not enterprise
assets, specify the asterisk character (*) for pattern matching. For
enterprise assets, specify the .* value to set the
argument as a non-empty value.
- description
- Specifies a description for the asset.
- destinationUrl
- Specifies the URL of the asset binaries to deploy.
- typeAspect
- Specifies the asset type aspect. Specify the typeAspect option
in object name format, as the following syntax demonstrates: spec=xxx
- relationship
- Specifies the asset relationship. Use the plus sign character
(+) to specify multiple asset relationships. The command returns an
exception if you specify assets in the relationship that do not exist.
- filePermission
- Specifies the file permission configuration.
OSGi applications
do not use a filePermission value.
- validate
- Specifies whether to validate the asset. The default value is false.
The product does not save the value specified for validate. Thus,
if you select to validate the asset (true) now and
later edit the asset, when you edit the asset you must enable this
setting again for the product to validate the updated files.
OSGi
applications do not use a validate value.
Return value
The
command returns the configuration ID of the asset that the system
creates, as the following example displays:
WebSphere:assetname=asset2.zip
Batch mode example usage
Use the following
examples to import a non-enterprise asset:
- Using Jython string:
AdminTask.importAsset('-source c:\ears\asset1.zip -storageType NONE')
- Using Jython list:
AdminTask.importAsset(['-source', 'c:\ears\asset1.zip', '-storageType', 'NONE'])
Use the following examples to import a non-enterprise
asset, set
asset2.zip as the asset name, save the
metadata binaries in the asset repository, and set the destination
directory of the binaries to deploy:
- Using Jython string:
AdminTask.importAsset('-source c:\ears\asset1.zip -storageType METADATA –AssetOptions
[[.* asset2.zip .* "asset for testing" c:/installedAssets/asset2.zip/BASE/asset2.zip "" "" "" "" false]]')
- Using Jython list:
AdminTask.importAsset(['-source', 'c:\ears\asset1.zip', '-storageType', 'METADATA', '–AssetOptions',
'[[.* asset2.zip .* "asset for testing" c:/installedAssets/asset2.zip/BASE/asset2.zip "" "" "" "" false]]')
Use the following examples to import a non-enterprise
asset, and specifies asset relationships with the
a.jar and
b.jar assets:
- Using Jython string:
AdminTask.importAsset('[-source c:\ears\asset3.zip -storageType FULL –AssetOptions
[[.* asset3.zip .* "asset for testing" "" spec=zip assetname=a.jar+assetname=b.jar "" false]]]')
- Using Jython list:
AdminTask.importAsset(['-source', 'c:\ears\asset3.zip', '-storageType', 'FULL', '–AssetOptions',
'[[.* asset3.zip .* "asset for testing" "" spec=zip assetname=a.jar+assetname=b.jar "" false]]'])
Use the following examples to import an enterprise asset:
- Using Jython string:
AdminTask.importAsset('-source c:\ears\defaultapplication.ear –storageType FULL –AssetOptions
[[.* defaultapp.ear .* "desc" "" "" "" false]]')
- Using Jython list:
AdminTask.importAsset(['-source', 'c:\ears\defaultapplication.ear', '–storageType',
'FULL', '–AssetOptions', '[[.* defaultapp.ear .* "desc" "" "" "" false]]'])
Interactive mode example usage
- Using Jython:
AdminTask.importAsset('-interactive')
listAssets
The
listAssets command displays the configuration ID of each asset within
the cell.
Target object
None
Optional parameters
- -assetID
- Specifies the configuration ID of the asset of interest. This
parameter accepts an incomplete configuration ID as long as the ID
matches a unique asset. (String, optional)
- -includeDescription
- Specifies whether to include the a description of each asset that
the command returns. Specify true to display the
asset descriptions. (String, optional)
- -includeDeplUnit
- Specifies whether to display the deployable units for each asset
that the command returns. Specify true to display
the deployable units. (String, optional)
Return value
The
command returns a list of configuration IDs for the assets of interest.
Depending on the parameter values specified, the command might display
the description and deployable composition units for each asset, as
the following example displays:
WebSphere:assetname=asset1.zip
"asset for testing"
WebSphere:assetname=asset2.zip
"second asset for testing"
a.jar
WebSphere:aasetname=asset3.zip
"third asset for testing"
a1.jar+a2.jar
WebSphere:assetname=a.jar0
"a.jar for sharedlib"
WebSphere:assetname=b.jar
"b.jar for sharedlib"
WebSphere:assetname=defaultapp.ear
"default app"
Batch
mode example usage
Use the following examples to list each asset
in the cell:
Use the following examples to list each asset in the cell:
- Using Jython string:
AdminTask.listAssets('-assetID asset1.zip')
- Using Jython list:
AdminTask.listAssets(['-assetID asset1.zip'])
Use the following examples to list each asset, asset description,
and deployable composition units in the cell:
- Using Jython string:
AdminTask.listAssets('-includeDescription true –includeDeplUnit true')
- Using Jython list:
AdminTask.listAssets(['-includeDescription', 'true', '–includeDeplUnit', 'true')
Interactive mode example usage
- Using Jython:
AdminTask.listAssets('-interactive')
updateAsset
The
updateAsset command modifies one or more files or module files of
an asset. The command updates the asset binary file, but does not
update the composition units that the system deploys with the asset
as a backing object.
Target object
None
Required parameters
- -assetID
- Specifies the configuration ID of the asset to update. This parameter
accepts an incomplete configuration ID as long as the ID matches a
unique asset. (String, required)
- -operation
- Specifies the operation to invoke on the asset of interest. (String,
required)
- The following table displays each operation that you can invoke
on an asset:
Table 1. updateAsset supported
operations. Specify one of the operations.Operation |
Description |
replace |
The replace operation replaces
the contents of the asset of interest. |
merge |
The merge operation updates
multiple files for the asset, but does not update all files. |
add |
The add operation adds a new
file or module file. |
addupdate |
The addupdate operation adds
or updates one file or module file. If the file does not exist, the
system adds the contents. If the file exists, the system updates the
file. |
update |
The update operation updates
one file or module file. |
delete |
The delete operation deletes
a file or module file. |
- -contents
- Specifies the file that contains the content to add or update.
This parameter is not required for the delete operation.
(UploadFile, optional)
Optional parameters
- -contenturi
- Specifies the Uniform Resource Identifier (URI) of the file to
add, update, or remove from the asset. This parameter is not required
for the merge or replace operations.
(String, optional)
Optional steps
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If you do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.- -AssetOptions
- Use the AssetOptions step and the following arguments to set additional
properties for the asset.
- name (read-only)
- Specifies the name of the asset. The default value for this argument
is the file name of the source package.
- defaultBindingProps (read-only)
- Specifies the default binding properties for the asset. This argument
only applies to enterprise assets. For assets which are not enterprise
assets, specify the asterisk character (*) for pattern matching. For
enterprise assets, specify the .* value to set the
argument as a non-empty value.
- description
- Specifies a description for the asset.
- destinationUrl
- Specifies the URL of the asset binaries to deploy.
- typeAspect
- Specifies the asset type aspect.
- relationship
- Specifies the asset relationship. Use the plus sign character
(+) to add additional assets to the existing relationship. Use the
number sign character (#) to delete an existing asset from the relationship.
To replace the existing relationships, specify the same syntax as
in the importAsset command. If the asset specified in the relationship
does not exist for add or update, the command returns an exception.
- filePermission
- Specifies the file permission configuration.
- validate
- Specifies whether to validate the asset. The default value is false.
The product does not save the value specified for validate. Thus,
if you select to validate the asset (true) now and
later edit the asset, when you edit the asset you must enable this
setting again for the product to validate the updated files.
- updateAssociatedCUs
- Specifies whether to update the composition units that are associated
with an enterprise (Java EE)
asset. This argument applies to enterprise assets only. The default
value is none. Specify all to update
all of the composition units that are associated with the enterprise
asset.
For the replace operation, specify values
for the AssetOptions name, defaultBindingProps, description, destinationUrl,
typeAspect, relationship, filePermission, validate, and updateAssociatedCUs
arguments. For operations other than replace, specify
values for the AssetOptions name and updateAssociatedCUs arguments.
Return value
The
command returns the configuration ID of the asset of interest.
Batch mode example usage
The following
example replaces the contents of a non-enterprise asset:
- Using Jython string:
AdminTask.updateAsset('-assetID asset1.zip -operation replace -contents c:/temp/a.zip')
- Using Jython list:
AdminTask.updateAsset(['-assetID', 'asset1.zip', '-operation', 'replace', '-contents', 'c:/temp/a.zip'])
The following example partially updates the files of a
non-enterprise asset:
- Using Jython string:
AdminTask.updateAsset('-assetID asset1.zip –operation merge –contents c:/temp/p.zip')
- Using Jython list:
AdminTask.updateAsset(['-assetID', 'asset1.zip', '–operation', 'merge', '–contents', 'c:/temp/p.zip'])
The following example updates an enterprise asset with
an Enterprise JavaBeans (EJB) module file:
- Using Jython string:
AdminTask.updateAsset('-assetID defaultapp.ear –operation add –contents
c:/temp/filename.jar –contenturi filename.jar')
- Using Jython list:
AdminTask.updateAsset(['-assetID', 'defaultapp.ear', '–operation', 'add', '–contents',
'c:/temp/filename.jar', '–contenturi', 'filename.jar'])
The following example replaces an enterprise asset and
its associated composition units using a replace operation:
- Using Jython string:
AdminTask.updateAsset('-assetID defaultapp.ear –operation replace –contents
c:/temp/newapp.ear –AssetOptions [[defaultapp.ear .* newdesc "" "" "" "" false all]]')
- Using Jython list:
AdminTask.updateAsset(['-assetID', 'defaultapp.ear', '–operation', 'replace', '–contents',
'c:/temp/newapp.ear', '–AssetOptions [[defaultapp.ear .* newdesc "" "" "" "" false all]]'])
The following example updates an enterprise asset and
its associated composition units using a merge operation:
- Using Jython string:
AdminTask.updateAsset('-assetID defaultapp.ear –operation merge –contents
c:/temp/newapp.ear –AssetOptions [[defaultapp.ear all]]')
- Using Jython list:
AdminTask.updateAsset(['-assetID', 'defaultapp.ear', '–operation', 'merge', '–contents',
'c:/temp/newapp.ear', '–AssetOptions [[defaultapp.ear all]]'])
Interactive mode example usage
- Using Jython:
AdminTask.updateAsset('-interactive')
viewAsset
The
viewAsset command displays additional asset configuration options
and configured values.
Target object
None
Required parameters
- -assetID
- Specifies the configuration ID of the asset of interest. This
parameter accepts an incomplete configuration ID as long as the ID
matches a unique asset. (String, required)
Optional parameters
None
Return value
The command returns configuration
data for the asset of interest, as the following example displays:
Specify Asset options (AssetOptions)
Specify options for Asset.
*Asset Name (name): [defaultapp.ear]
Default Binding Properties (defaultBindingProps):
[defaultbinding.ejbjndi.prefix#defaultbinding.datasource.jndi#defaultbinding.datasource.username
#defaultbinding.datasource.password#defaultbinding.cf.jndi
#defaultbinding.cf.resauth#defaultbinding.virtual.host#defaultbinding.force]
Asset Description (description): []
Asset Binaries Destination Url (destination): [${USER_INSTALL_ROOT}/installedAssets/defaultapp.ear/BASE/defaultapp.ear]
Asset Type Aspects (typeAspect): [WebSphere:spec=j2ee_ear]
Asset Relationships (relationship): []File Permission (filePermission): [.*\\.dll=755#.*\\.so=755#.*\\.a=755#.*\\.sl=755]
Validate asset (validate): [false]
Batch mode example usage
- Using Jython string:
AdminTask.viewAsset('-assetID asset3.zip')
- Using Jython list:
AdminTask.viewAsset(['-assetID', 'asset3.zip'])
Interactive mode example usage
- Using Jython:
AdminTask.viewAsset('-interactive')
addCompUnit
The
addCompUnit command adds a composition unit to a specific business-level
application. A composition unit represents an asset in a business-level
application, and enables the asset contents to interact with other
assets in the application. It also enables the product run time to
load and run asset contents.
Target
object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. (String, required)
- -cuSourceID
- Specifies the source configuration ID for the composition unit
to add. You can specify an asset ID or a business-level application
ID. (String, required)
Optional parameters
- -deplUnits
- Specifies the deployable units to deploy for the asset. You can
specify a subset of deployable units, all deployable units, or use
the default as a shared library. If you do not specify this parameter,
the system deploys each deployable unit. (String, optional)
- For Java EE assets, the
system ignores this -deplUnits parameter and, regardless of the value
specified, can add Java EE assets
as part of this command.
- -cuConfigStrategyFile
- Specifies the fully qualified file path for custom default binding
properties. This parameter only applies to enterprise assets. (String,
optional)
- -defaultBindingOptions
- Specifies optional Java Naming
and Directory Interface (JNDI) binding properties for an enterprise
asset. The binding properties available depend upon the type of enterprise
asset. Use the format property=value to specify a
default binding property. To specify more than one property, separate
each property=value statement by the delimiter #.
- You can specify binding properties now, when creating the asset,
or later, when adding the asset as a composition unit to a business-level
application. If you specify binding properties later, when adding
the asset to a business-level application, then you can use a strategy
file to specify the binding properties. (String, optional)
- Use the following options with the defaultBindingOptions parameter:
Table 2. addCompUnit -defaultBindingOptions supported
binding properties. Specify a binding property that is
supported for the asset type.enterprise asset type |
Supported binding properties |
Enterprise bean (EJB) |
defaultbinding.ejbjndi.prefix
defaultbinding.force
|
Data source |
defaultbinding.datasource.jndi
defaultbinding.datasource.username
defaultbinding.datasource.password
defaultbinding.force
|
Connection factory |
defaultbinding.cf.jndi
defaultbinding.cf.resauth
defaultbinding.force
|
Virtual host |
defaultbinding.virtual.host
defaultbinding.force
|
Optional steps
You
can also specify values for optional steps to set additional properties
for the new composition unit. These steps do not apply to enterprise
assets.
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If you do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.- -CUOptions
- Specifies additional properties for the composition unit. Specify
the following options with the CUOptions step:
- parentBLA (read-only)
- Specifies the parent business-level application for the new composition
unit.
- backingID (read-only)
- Specifies the composition unit source ID.
- name
- Specifies the name of the composition unit.
- description
- Specifies a description of the composition unit.
- startingWeight
- Specifies the starting weight of the composition unit. Supported
values are from 1 to 2147483647, the maximum Integer value.
- startedOnDistributed
- Specifies whether to start the composition unit after distributing
changes to the target nodes. The default value is false.
- restartBehaviorOnUpdate
- Specifies the nodes to restart after editing the composition unit.
Specify ALL to restart each target node. Specify DEFAULT to
restart the nodes controlled by the sync plug-ins. Specify NONE to
prevent the system from restarting nodes.
- For example, specify the syntax of this step as -CUOptions
[[.* .* cu4 "cu4 desc" 0 false DEFAULT]]
- -MapTargets
- Specifies additional properties for the composition unit target
mapping. Specify the following options with the MapTargets step:
- deplUnit (read-only)
- Specifies the deployable unit Uniform Resource Identifier (URI).
- For an enterprise
bundle archive (EBA) asset, this URI is ebaDeploymentUnit.
- server
- Specifies the target or targets to deploy the composition units.
The default value is the server1 server. Use the
plus sign character ( + ) to specify multiple targets. Use the plus
sign character ( + ) as a prefix to add an additional target. Specify
the complete object name format for each server that is not aWebSphere Application Server server.
- For example, specify the syntax of this step as -MapTargets
[[a1.jar cluster1+cluster2] [a2.jar +server2]]
- -ActivationPlanOptions
- Specifies additional properties for the composition unit activation
plan. Specify the following options with the ActivationPlanOptions
step:
- deplUnit (read-only)
- Specifies the deployable unit Uniform Resource Identifier (URI).
- activationPlan
- Specifies a list of runtime components as the activation plan.
Specify each activation plan in the format specName=xxx,specVersion=yyy,
where specName represents the name of the specification
and is required. Use the plus sign character ( + ) to specify multiple
activation plans.
- For example, specify the syntax of this step as -ActivationPlanOptions
[[a1.jar specname=actplan0+specname=actplan1] [a2.jar specname=actplan1+specname=actplan2]]
- For an EBA
asset, use the following default values: -ActivationPlanOptions
[[default ""]]
- -CreateAuxCUOptions
- Specifies additional properties for an auxiliary composition unit.
Use this step if the composition unit source is an asset that corresponds
to an asset that does not have a matching composition unit in the
business-level application. Specify the following options with the
CreateAuxCUOptions step:
- deplUnit (read-only)
- Specifies the deployable unit Uniform Resource Identifier (URI).
- inputAsset (read-only)
- Specifies composition unit source ID.
- cuID
- Specifies the composition unit ID that the system creates for
the asset. If you do not want to create a new composition unit, do
not specify this argument.
- matchTarget
- Specifies whether to match the targets of the dependency auxiliary
composition unit with the targets of the new composition unit. The
default value is true.
- The product does not save the value specified for matchTarget.
Thus if you select to not match the target (false)
now and later edit the composition unit, when you edit the composition
unit you must disable this setting again for the product to not match
the targets.
- For example, specify the syntax of this step as –CreateAuxCUOptions
[[a1.jar a.jar auxCU true] [a2.jar a.jar defaultCU false]]
- -RelationshipOptions
- Specifies additional properties for relationships between assets,
composition units, and business-level applications. Use this step
if the source ID of the composition unit is an asset that has a matching
composition unit in the business-level application. Specify the following
options with the RelationshipOptions step:
- deplUnit (read-only)
- Specifies the deployable unit Uniform Resource Identifier (URI).
- relationship
- Defines the composition unit relationships. Specify the composition
unit object name in the format: cuName=xxx. Use the
plus sign character (+) to specify multiple composition unit object
names in the relationship. If the composition unit specified in the
relationship does not exist under the same business-level application,
the system returns an error.
- matchTarget
- Specifies whether to match the targets of the composition unit
relationship with the targets of the new composition unit. The default
value is true.
- The product does not save the value specified for matchTarget.
Thus if you select to not match the target (false)
now and later edit the composition unit, when you edit the composition
unit you must disable this setting again for the product to not match
the targets.
- For example, specify the syntax of this step as –RelationshipOptions
[[a1.jar a.jar auxCU true] [a2.jar a.jar defaultCU false]]
- -ContextRootStep
- For an EBA asset, 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.
- You should list the context roots for all the WAB modules that
are contained in the OSGi application.
- Specify the syntax of this step as follows:
-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:
-ContextRootStep [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 "/hello/web"]
[com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "/hello/service"]]
- -VirtualHostMappingStep
- For an EBA asset, 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.
- Specify the syntax of this step as follows:
-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:
-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
- For an EBA asset, use this step to map security roles to users
or groups.
- Specify the syntax of this step as follows:
-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:
-MapRolesToUsersStep [
[ROLE1 No Yes "" ""]
[ROLE2 No No WABTestUser1 ""]
[ROLE3 No No "" WABTestGroup1]
[ROLE4 Yes No "" ""]]
- -BlueprintResourceRefBindingStep
- For an EBA asset, 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. For more information,
see Adding an EBA asset to a composition unit using the addCompUnit
command.
- Specify the syntax of this step as follows:
-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:
-BlueprintResourceRefBindingStep[
[com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
javax.sql.DataSource jdbc/Account Container Shareable alias1]]
- -WebModuleMsgDestRefs
- For an EBA asset, 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 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.
- Specify the syntax of this step as follows:
-WebModuleMsgDestRefs [
[
bundle_symbolic_name
bundle_version
resource_reference_id
resource_type
target_jndi_name
]]
- For example:
-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
- For an EBA asset, 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 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.
- Specify the syntax of this step as follows:
-WebModuleResourceRefs [
[
bundle_symbolic_name
bundle_version
resource_reference_id
resource_type
target_jndi_name
login_configuration
login_properties
extended_properties
]]
- For example:
-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".
Return
value
The command returns the configuration IDs of the composition
unit and the new composition unit created for the asset in the asset
relationship, as the following example displays:
WebSphere:cuname=cu4
WebSphere:cuname=cua
WebSphere:cuname=cud
Batch
mode example usage
Use the following examples to add a non-enterprise
asset:
- Using Jython string:
AdminTask.addCompUnit('-blaID myBLA –cuSourceID assetname=asset1.zip -CUOptions
[[.* .* cu1 "cu1 desc1" 0 false DEFAULT]] -MapTargets [[.* server1]] –ActivationPlanOptions
[.* specname=actplan0+specname=actplan1]')
- Using Jython list:
AdminTask.addCompUnit(['-blaID', 'myBLA', '–cuSourceID', 'assetname=asset1.zip', '-CUOptions',
'[[.* .* cu1 "cu1 desc1" 0 false DEFAULT]]', '-MapTargets', '[[.* server1]]', '–ActivationPlanOptions',
'[.* specname=actplan0+specname=actplan1]'])
Use the following examples to add a business-level application
composition unit:
- Using Jython string:
AdminTask.addCompUnit('-blaID myBLA -cuSourceID yourBLA -CUOptions [[.* .* cu3 "cu3 desc3" 0 false DEFAULT]]')
- Using Jython list:
AdminTask.addCompUnit(['-blaID', 'myBLA', '-cuSourceID', 'yourBLA', '-CUOptions',
'[[.* .* cu3 "cu3 desc3" 0 false DEFAULT]]'])
Use
the following example to create an EBA composition unit and add it
to a business-level application. For more information, see
Adding an EBA asset to a composition unit using the addCompUnit
command.
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]]
-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]]
-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"]]
]')
Use the following examples to add a composition
unit for a non-enterprise asset and deploy the composition unit to
multiple targets:
- Using Jython string:
AdminTask.addCompUnit('-blaID theirBLA –cuSourceID asset2.zip –CUOptions
[[.* .* cu2 "cu2 desc" 0 false DEFAULT]] -MapTargets [[.* server1+server2]]')
- Using Jython list:
AdminTask.addCompUnit(['-blaID', 'theirBLA', '–cuSourceID', 'asset2.zip', '–CUOptions',
'[[.* .* cu2 "cu2 desc" 0 false DEFAULT]]', '-MapTargets', '[[.* server1+server2]]'])
Use the following examples to add a composition unit that
is a non-enterprise asset with a deployable unit:
- Using Jython string:
AdminTask.addCompUnit('-blaID yourBLA –cuSourceID asset2.zip –deplUnits a.jar –CUOptions
[[.* .* cu3 "cu3 desc" 0 false DEFAULT]] –MapTargets [[a.jar server1]] –ActivationPlanOptions
[[a.jar specname=actplan1]]')
- Using Jython list:
AdminTask.addCompUnit(['-blaID', 'yourBLA', '–cuSourceID', 'asset2.zip', '–deplUnits', 'a.jar', '–CUOptions',
'[[.* .* cu3 "cu3 desc" 0 false DEFAULT]]', '–MapTargets', '[[a.jar server1]]', '–ActivationPlanOptions',
'[[a.jar specname=actplan1]]'])
Use the following examples to add a composition unit for
a non-enterprise asset as a shared library:
- Using Jython string:
AdminTask.addCompUnit('-blaID ourBLA –cuSourceID b.jar –deplUnits default –CUOptions
[[.* .* cub "cub desc" 0 false DEFAULT]] –MapTargets [[default server1]]')
- Using Jython list:
AdminTask.addCompUnit(['-blaID', 'ourBLA', '–cuSourceID', 'b.jar', '–deplUnits', 'default', '–CUOptions',
'[[.* .* cub "cub desc" 0 false DEFAULT]]', '–MapTargets', '[[default server1]]'])
Use the following examples to add a composition unit for
a non-enterprise asset with a dependency. For this example, the
cub composition
unit exists as a shared library of the
ourBLA business-level
application:
- Using Jython string:
AdminTask.addCompUnit('-blaID ourBLA –cuSourceID asset3.zip –deplUnits a1.jar –CUOptions
[[.* .* cu4 "cu4 desc" 0 false DEFAULT]] –MapTargets [[a1.jar cluster1+cluster2]] –CreateAuxCUOptions
[[a1.jar a.jar cua true]] –RelationshipOptions [[a1.jar cuname=cub true]]')
- Using Jython list:
AdminTask.addCompUnit(['-blaID', 'ourBLA', '–cuSourceID', 'asset3.zip', '–deplUnits', 'a1.jar', '–CUOptions',
'[[.* .* cu4 "cu4 desc" 0 false DEFAULT]]', '–MapTargets', '[[a1.jar cluster1+cluster2]]', '–CreateAuxCUOptions',
'[[a1.jar a.jar cua true]]', '–RelationshipOptions', '[[a1.jar cuname=cub true]]'])
Use the following examples to add an enterprise asset:
- Using Jython string:
AdminTask.addCompUnit('[-blaID yourBLA –cuSourceID defaultapp.ear –defaultBindingOptions
defaultbinding.ejbjndi.prefix=ejb# defaultbinding.virtual.host=default_host#
defaultbinding.force=yes –AppDeploymentOptions [-appname defaultapp -installed.ear.destination
application_root/myCell/defaultapp.ear] –MapModulesToServers
[[defaultapp.war .* WebSphere:cell=cellName,node=nodeName,server=server1]
[Increment.jar .* Websphere:cell=cellName,node=nodeName,server=server2]] -CtxRootForWebMod
[[defaultapp.war .* myctx/]]]')
- Using Jython list:
AdminTask.addCompUnit(['-blaID', 'yourBLA', '–cuSourceID', 'defaultapp.ear', '–defaultBindingOptions',
'defaultbinding.ejbjndi.prefix=ejb# defaultbinding.virtual.host=default_host# defaultbinding.force=yes',
'–AppDeploymentOptions', '[-appname defaultapp -installed.ear.destination application_root/myCell/defaultapp.ear]',
'–MapModulesToServers', '[[defaultapp.war .* WebSphere:cell=cellName,node=nodeName,server=server1]
[Increment.jar .* Websphere:cell=cellName,node=nodeName,server=server2]]', '-CtxRootForWebMod',
'[[defaultapp.war .* myctx/]]'])
Interactive mode example usage
- Using Jython:
AdminTask.addCompUnit('-interactive')
deleteCompUnit
The
deleteCompUnit command removes a composition unit. Both parameters
for this command accept incomplete configuration IDs, as long as the
system can match the string to a unique ID.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. (String, required)
- -cuID
- Specifies the configuration ID of the composition unit to delete.
(String, required)
Optional parameters
- -force
- Specifies whether to force the system to delete the composition
unit, even if other composition units depend on this composition unit.
(Boolean, optional)
Return value
The
command returns the configuration ID of the composition unit that
the system deleted, as the following example displays:
WebSphere:cuname=cu1
Batch mode example usage
- Using Jython string:
AdminTask.deleteCompUnit('-blaID myBLA –cuID cu1 -force true')
- Using Jython list:
AdminTask.deleteCompUnit(['-blaID', 'myBLA', '–cuID', 'cu1', '-force', 'true'])
Interactive mode example usage
- Using Jython:
AdminTask.deleteCompUnit('-interactive')
editCompUnit
The
editCompUnit command modifies additional composition unit options.
You can use this command to modify the starting weight of the composition
unit, deployment targets, activation plan options, and relationship
settings.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. (String, required)
- -cuID
- Specifies the configuration ID of the composition unit to edit.
(String, required)
Optional steps
You
can also specify values for optional steps to edit properties of the
composition unit. These steps do not apply to enterprise assets.
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If you do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.- -CUOptions
- Specifies additional properties for the composition unit. Specify
the following options with the CUOptions step:
- parentBLA (read-only)
- Specifies the parent business-level application for the composition
unit.
- backingID (read-only)
- Specifies the composition unit source ID.
- name (read-only)
- Specifies the name of the composition unit.
- description
- Specifies a description of the composition unit.
- startingWeight
- Specifies the starting weight of the composition unit. Supported
values are from 1 to 2147483647, the maximum Integer value.
- startedOnDistributed
- Specifies whether to start the composition unit after distributing
changes to the target nodes. The default value is false.
- restartBehaviorOnUpdate
- Specifies the nodes to restart after editing the composition unit.
Specify ALL to restart each target node. Specify DEFAULT to
restart the nodes controlled by the sync plug-ins. Specify NONE to
prevent the system from restarting nodes.
- For example, specify the syntax for this step as -CUOptions
[[.* .* cu4 "cu4 description" 0 false DEFAULT]]
- -MapTargets
- Specifies additional properties for the composition unit target
mapping. Specify the following options with the MapTargets step:
- deplUnit (read-only)
- Specifies the deployable unit Uniform Resource Identifier (URI).
- For an enterprise
bundle archive (EBA) asset, this URI is ebaDeploymentUnit.
- server
- Specifies the target or targets to deploy the composition units.
The default value is the server1 server. Use the
plus sign character ( + ) to specify multiple targets. Use the plus
sign character ( + ) as a prefix to add an additional target. Specify
the complete object name format for each server that is not a WebSphere Application Server server.
- For example, specify the syntax of this step as -MapTargets
[[a1.jar cluster1+cluster2] [a2.jar server1+server2]]
- -ActivationPlanOptions
- Specifies additional properties for the composition unit activation
plan. Specify the following options with the ActivationPlanOptions
step:
- deplUnit (read-only)
- Specifies the deployable unit Uniform Resource Identifier (URI).
- activationPlan
- Specifies a list of runtime components as the activation plan.
Specify each activation plan in the format specName=xxx,specVersion=yyy,
where specName represents the name of the specification
and is required. Use the plus sign character ( + ) to specify multiple
activation plans.
- For example, specify the syntax of this step as -ActivationPlanOptions
[[a1.jar specname=actplan0+actplan1] [a2.jar specname=actplan1+specname=actplan2]]
- For an EBA
asset, do not modify the activation plan. Keep the following default
values that were set when the composition unit was added: -ActivationPlanOptions
[[default ""]]
- -RelationshipOptions
- Specifies additional properties for relationships between assets,
composition units, and business-level applications. Use this step
if the source ID of the composition unit is an asset that has a matching
composition unit in the business-level application. Specify the following
options with the RelationshipOptions step:
- deplUnit (read-only)
- Specifies the deployable unit Uniform Resource Identifier (URI).
- relationship
- Defines the composition unit relationships. Specify the composition
unit object name in the format: cuName=xxx. Use the
plus sign character (+) to specify multiple composition unit object
names in the relationship. If the composition unit specified in the
relationship does not exist under the same business-level application,
the system returns an error.
- matchTarget
- Specifies whether to match the targets of the composition unit
relationship with the targets of the new composition unit. The default
value is true.
- The product does not save the value specified for matchTarget.
Thus if you select to not match the target (false)
now and later edit the composition unit, when you edit the composition
unit you must disable this setting again for the product to not match
the targets.
- For example, specify the syntax of this step as –RelationshipOptions
[[a1.jar a.jar auxCU true] [a2.jar a.jar defaultCU false]]
- -ContextRootStep
- For an EBA asset, 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.
- You should list the context roots for all the WAB modules that
are contained in the OSGi application.
- Specify the syntax of this step as follows:
-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:
-ContextRootStep [
[com.ibm.ws.eba.helloWorldService.web 1.0.0 "/hello/web"]
[com.ibm.ws.eba.helloWorldService.withContextRoot 0.9.0 "/hello/service"]]
- -VirtualHostMappingStep
- For an EBA asset, 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.
- Specify the syntax of this step as follows:
-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:
-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
- For an EBA asset, use this step to map security roles to users
or groups.
- Specify the syntax of this step as follows:
-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:
-MapRolesToUsersStep [
[ROLE1 No Yes "" ""]
[ROLE2 No No WABTestUser1 ""]
[ROLE3 No No "" WABTestGroup1]
[ROLE4 Yes No "" ""]]
- -BlueprintResourceRefPostDeployStep
- For an EBA asset, 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. For more information,
see Modifying the configuration of an EBA composition unit
using the editCompUnit command.
- Specify the syntax of this step as follows:
-BlueprintResourceRefPostDeployStep [
[
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:
-BlueprintResourceRefPostDeployStep[
[com.ibm.ws.eba.helloWorldService.properties.bundle 1.0.0 resourceRef
javax.sql.DataSource jdbc/Account Container Shareable alias1]]
- -WebModuleResourceRefs
- For an EBA asset, 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).
- Specify the syntax of this step as follows:
-WebModuleResourceRefs [
[
bundle_symbolic_name
bundle_version
resource_reference_id
resource_type
target_jndi_name
login_configuration
login_properties
extended_properties
]]
- For example:
-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".
Return value
The
command returns the configuration ID of the composition unit that
the system edits.
Batch mode example
usage
Use the following examples to edit a composition unit
of an asset and replace the target from existing targets:
- Using Jython string:
AdminTask.editCompUnit('-blaID myBLA –cuID cu1 –CUOptions [[.* .* cu1 cudesc 1 false DEFAULT]] -MapTargets
[[.* server2]] -ActivationPlanOptions [.* #specname=actplan0+specname=actplan2]')
- Using Jython list:
AdminTask.editCompUnit(['-blaID', 'myBLA', '–cuID', 'cu1', '–CUOptions',
'[[.* .* cu1 cudesc 1 false DEFAULT]]', '-MapTargets', '
[[.* server2]]', '-ActivationPlanOptions', '[.* #specname=actplan0+specname=actplan2]'])
Use the following examples to edit a composition unit
of an asset and its relationships:
- Using Jython string:
AdminTask.editCompUnit('-blaID ourBLA –cuID cu4 –CUOptions [[.* .* cu4 "new cu desc" 1 false DEFAULT]]
–MapTargets [[a1.jar server1+server2]] –RelationshipOptions [[a1.jar cuname=cub true]]')
- Using Jython list:
AdminTask.editCompUnit(['-blaID', 'ourBLA', '–cuID', 'cu4', '–CUOptions', '
[[.* .* cu4 "new cu desc" 1 false DEFAULT]]', '–MapTargets', '[[a1.jar server1+server2]]', '–RelationshipOptions',
'[[a1.jar cuname=cub true]]'])
Use the following examples to edit a composition unit
by adding a new relationship to the existing relationship:
- Using Jython string:
AdminTask.editCompUnit('[-blaID ourBLA –cuID cu4 –CUOptions [[.* .* cu4 "new cu desc" 1 false DEFAULT]]
–MapTargets [[a1.jar server1+server2]] –RelationshipOptions [[a1.jar +cuname=cuc true]] -ActivationPlanOptions
[a1.jar +specname=actplan2#specname=actplan1]]')
- Using Jython list:
AdminTask.editCompUnit(['-blaID', 'ourBLA', '–cuID', 'cu4', '–CUOptions', '
[[.* .* cu4 "new cu desc" 1 false DEFAULT]]', '–MapTargets', '[[a1.jar server1+server2]]', '–RelationshipOptions',
'[[a1.jar +cuname=cuc true]]', '-ActivationPlanOptions', '[a1.jar +specname=actplan2#specname=actplan1]'])
Use the following examples to edit an enterprise composition
unit configuration:
- Using Jython string:
AdminTask.editCompUnit('-blaID yourBLA –cuID defaultapp –MapModulesToServers
[[defaultapp.war .* WebSphere:cluster=cluster1][Increment.jar .* Websphere:cluster=cluster2]]
–CtxRootForWebMod [[defaultapp.war .* /]] –MapWebModToVH [[defaultapp.war .* vh1]]')
- Using Jython list:
AdminTask.editCompUnit(['-blaID', 'yourBLA', '–cuID', 'defaultapp', '–MapModulesToServers',
'[[defaultapp.war .* WebSphere:cluster=cluster1][Increment.jar .* Websphere:cluster=cluster2]]', '–CtxRootForWebMod',
'[[defaultapp.war .* /]]', '–MapWebModToVH', '[[defaultapp.war .* vh1]]'])
Interactive mode example usage
- Using Jython:
AdminTask.editCompUnit('-interactive')
listCompUnits
The
listCompUnits command displays each composition unit that is associated
with a specific business-level application.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. (String, required)
Optional parameters
- -includeDescription
- Specifies whether to include a description of each asset that
the command returns. (String, optional)
- -includeType
- Specifies whether to include the type for each asset that the
command returns. (String, optional)
Return value
The
command returns a list of configuration IDs and the type for each
composition unit, as the following example displays:
Websphere:cuname=cu1
asset
"description for cu1"
Websphere:cuname=cu4
bla
"description for cu4"
WebSphere:cuname=defaultapp
Java EE
"description for defaultapp"
Batch mode example usage
- Using Jython string:
AdminTask.listCompUnits('-blaID blaname=theirBLA')
- Using Jython list:
AdminTask.listCompUnits(['-blaID', 'blaname=theirBLA'])
Interactive mode example usage
- Using Jython:
AdminTask.listCompUnits('-interactive')
setCompUnitTargetAutoStart
The
setCompUnitTargetAutoStart command enables or disables automatic starting
of composition units. If you enable this option, the system automatically
starts the composition unit when the composition unit target starts.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. The command accepts an incomplete configuration ID if
the system matches it to a unique business-level application ID. (String,
required)
- -cuID
- Specifies the composition unit of interest. The command accepts
an incomplete configuration ID if the system matches it to a unique
composition unit ID. (String, required)
- -targetID
- Specifies the name of the target of interest. For example, specify
the server name to set the target to a specific server. (String, required)
- -enable
- Specifies whether to automatically start the composition unit
of interest when the specified target starts. Specify true to
start the composition unit automatically. If you do not specify true,
the system will not start the composition unit when the target starts.
The default value is true. (String, required)
Return value
The
command does not return output.
Batch
mode example usage
- Using Jython string:
AdminTask.setCompUnitTargetAutoStart('-blaID bla1 –cuID cu1 –targetID server1 –enable true')
- Using Jython list:
AdminTask.setCompUnitTargetAutoStart(['-blaID', 'bla1', '–cuID', 'cu1', '–targetID',
'server1', '–enable', 'true'])
Interactive mode example usage
- Using Jython string:
AdminTask.setCompUnitTargetAutoStart('-interactive')
viewCompUnit
The
viewCompUnit command displays configuration information for a composition
unit that belongs to a specific business-level application.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. This parameter accepts an incomplete configuration ID
if the system matches it to a unique business-level application ID.
(String, required)
- -cuID
- Specifies the configuration ID of the composition unit of interest.
This parameter accepts an incomplete configuration ID if the system
matches it to a unique composition unit ID. (String, required)
Optional parameters
None
Return value
The command returns configuration
information for the composition unit of interest, as the following
example displays:
Specify Composition Unit options (CUOptions)
Specify name, description options for Composition Unit.
Parent BLA (parentBLA): [WebSphere:blaname=myBLA]
Backing Id (backingId): [WebSphere:assetname=asset1.zip]
Name (name): [cu1]
Description (description): [cuDesc]
Starting Weight (startingWeight): [0]
Started on distributed (startedOnDistributed): [false]
Restart behavior on update (restartBehaviorOnUpdate): [DEFAULT]
Specify servers (MapTargets)
Specify targets such as application servers or clusters of application servers where you want
to deploy the cu contained in the application.
Deployable Unit (deplUnit): [default]
*Servers (server): [WebSphere:node=myNode,server=server1]
Specify Composition Unit activation plan options (ActivationPlanOptions)
Specify CU activation plan optionsDeployableUnit Name (deplUnit): [default]
Activation Plan (activationPlan): [WebSphere:specname=actplan0+WebSphere:specname=actplan1]
If
the composition unit contains an enterprise bundle archive (EBA) asset,
the composition unit status is also displayed. This status is one
of the following values:
- Using 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.
For more information, see
Checking the update status of an OSGi composition unit.
Batch mode example usage
The
following example displays configuration information for a non-enterprise
asset:
- Using Jython string:
AdminTask.viewCompUnit('-blaID myBLA -cuID myCompUnit')
- Using Jython list:
AdminTask.viewCompUnit(['-blaID', 'myBLA', '-cuID', 'myCompUnit'])
The following example displays configuration information
for an enterprise asset:
- Using Jython string:
AdminTask.viewCompUnit('-blaID myBLA -cuID defaultApplication')
- Using Jython list:
AdminTask.viewCompUnit(['-blaID', 'myBLA', '-cuID', 'defaultApplication'])
Interactive mode example usage
- Using Jython:
AdminTask.viewCompUnit('-interactive')
createEmptyBLA
The
createEmptyBLA command to create an empty business-level application.
After creating a business-level application, you can add assets or
other business-level applications as composition units to the application.
Target object
None
Required parameters
- -name
- Specifies a unique name for the new business-level application.
(String, required)
Optional parameters
- -description
- Specifies a description of the new business-level application.
(String, optional)
Return value
The
command returns the configuration ID of the new business-level application,
as the following example displays:
WebSphere:blaname=myBLA
Batch mode example usage
- Using Jython string:
AdminTask.createEmptyBLA('-name myBLA -description "my description for BLA"')
- Using Jython list:
AdminTask.createEmptyBLA(['-name', 'myBLA', '-description', '"my description for BLA"'])
Interactive mode example usage
- Using Jython:
AdminTask.createEmptyBLA('-interactive')
deleteBLA
The
deleteBLA command removes a business-level application from your configuration.
Before deleting a business-level application, use the deleteCompUnit
command to remove each composition unit that is associated with the
business-level application. Also, verify that no other business-level
applications reference the business-level application to delete.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. The command accepts an incomplete ID for the blaID parameter,
as long as the system can match the string to a unique identifier.
For example, you can specify the myBLA partial ID
to identify the WebSphere:blaname=myBLA configuration
ID. (String, required)
Optional parameters
None
Return value
The command returns the
configuration ID of the deleted business-level application, as the
following example displays:
WebSphere:blaname=myBLA
Batch mode example usage
- Using Jython string:
AdminTask.deleteBLA('-blaID myBLA')
- Using Jython list:
AdminTask.deleteBLA(['-blaID', 'myBLA'])
Interactive mode example usage
- Using Jython:
AdminTask.deleteBLA('-interactive')
editBLA
The
editBLA command modifies the description of a business-level application.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. (String, required)
Optional steps
For optional steps, use the .* characters to specify a read-only argument in the command syntax. Specify an empty string with the "" characters to keep the existing value of the argument. If you do not specify a value or an empty string for a writable argument, the command resets the argument to a null value.- -BLAOptions
- Use the BLAOptions step to specify a new description for the business-level
application of interest.
- name (read-only)
- Specifies the name of the business-level application.
- description
- Specifies a description of the business-level application.
Return value
The
command does not return output.
Batch
mode example usage
- Using Jython string:
AdminTask.editBLA('-blaID DefaultApplication –BLAOptions [[.* "my new description"]]')
- Using Jython list:
AdminTask.editBLA(['-blaID', 'DefaultApplication', '–BLAOptions', '[[.* "my new description"]]'])
Interactive mode example usage
- Using Jython:
AdminTask.editBLA('-interactive')
getBLAStatus
The
getBLAStatus command displays whether a business-level application
or composition unit is running or stopped.
Target
object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. Use the listBLAs command to display a list of business-level
application configuration IDs. (String, required)
Optional parameters
- -cuID
- Specifies the configuration ID of the composition unit of interest.
Use the listCompUnits command to display a list of composition unit
configuration IDs. (String, optional)
Return value
The
command returns the status of the business-level application or composition
unit of interest.
Batch mode example
usage
- Using Jython string:
AdminTask.getBLAStatus('-blaID WebSphere:blaname=myBLA -cuID Websphere:cuname=cu1')
- Using Jython list:
AdminTask.getBLAStatus(['-blaID', 'WebSphere:blaname=myBLA', '-cuID', 'Websphere:cuname=cu1'])
Interactive mode example usage
- Using Jython:
AdminTask.getBLAStatus('-interactive')
listBLAs
The
listBLAs command displays the business-level applications in your
configuration.
Target object
None
Optional parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. (String, optional)
- -includeDescription
- Specifies whether to include a description of each business-level
application that the command returns. Specify true to
display the business-level application descriptions. (String, optional)
Return value
The
command returns a list of configuration IDs for each business-level
application in your configuration, as the following example displays:
WebSphere:blaname=myBLA
WebSphere:blaname=yourBLA
Batch
mode example usage
The following example lists each business-level
application in the configuration:
Use the following examples to list each business-level
application in the configuration:
- Using Jython string:
AdminTask.listBLAs('-blaID myBLA')
- Using Jython list:
AdminTask.listBLAs(['-blaID', 'myBLA'])
Use the following examples to list each business-level
application and the corresponding descriptions:
- Using Jython string:
AdminTask.listBLAs('-includeDescription true')
- Using Jython list:
AdminTask.listBLAs(['-includeDescription', 'true'])
Interactive mode example usage
- Using Jython string:
AdminTask.listBLAs('-interactive')
listControlOps
The
listControlOps command displays the control operations for a business-level
application and the corresponding composition units.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. (String, required)
Optional parameters
- -cuID
- Specifies the composition unit of interest. (String, optional)
- -opName
- Specifies the operation name of interest. (String, optional)
- -long
- Specifies whether to include additional configuration information
in the command output. (String, optional)
Return value
The
command returns a list of operations, operation descriptions, and
parameter descriptions for the query scope, as the following example
displays:
"Operation: start"
"Description: Start operation"
"Operation handler ID: com.mycompany.myasset.ControlOpHandler"
"Operation handler data URI: None"
"Operation: stop"
"Description: Stop operation"
"Operation handler ID: com.mycompany.myasset.ControlOpHandler"
"Operation handler data URI: None"
"Operation: clearCache"
"Description: Clears specified cache or all caches"
"Operation handler ID: com.mycompany.myasset.ControlOpHandler"
"Operation handler data URI: None"
"Parameter: cacheName"
"Description: Name of cache to clear. If not specified, all caches are cleared."
Batch mode example usage
- Using Jython string:
AdminTask.listControlOps('-blaID myBLA –cuID myservice.jar –long true')
- Using Jython list:
AdminTask.listControlOps(['-blaID', 'myBLA', '–cuID', 'myservice.jar', '–long true'])
Interactive mode example usage
- Using Jython:
AdminTask.listControlOps('-interactive')
startBLA
The
startBLA command starts the business-level application of interest.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
to start. The command accepts an incomplete configuration ID if the
system matches the string to a unique ID in your configuration. (String,
required)
Return value
The
command returns a status message if the business-level application
starts. If the business-level application does not start, the command
does not return output. The following example displays the status
message output:
BLA ID of started BLA if the BLA was not already running.
Batch mode example usage
- Using Jython string:
AdminTask.startBLA('-blaID myBLA')
- Using Jython list:
AdminTask.startBLA(['-blaID', 'myBLA'])
Interactive mode example usage
- Using Jython:
AdminTask.startBLA('-interactive')
stopBLA
The
stopBLA command stops the business-level application of interest.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
to stop. The command accepts an incomplete configuration ID if the
system matches the string to a unique ID in your configuration. (String,
required)
Return value
The
command returns a status message if the business-level application
stops. If the business-level application does not stop, the command
does not return output. The following example displays the status
message output:
BLA ID of stopped BLA if the BLA was not already stopped.
Batch mode example usage
- Using Jython string:
AdminTask.stopBLA('-blaID myBLA')
- Using Jython list:
AdminTask.stopBLA(['-blaID', 'myBLA'])
Interactive mode example usage
- Using Jython:
AdminTask.stopBLA('-interactive')
viewBLA
The
viewBLA command displays the name and description of the business-level
application of interest.
Target object
None
Required parameters
- -blaID
- Specifies the configuration ID of the business-level application
of interest. The command accepts an incomplete configuration ID if
the system matches the string to a unique business-level application.
(String, required)
Optional parameters
None
Return value
The command returns configuration
information for the business-level application of interest, as the
following example displays:
Specify BLA options (BLAOptions)
Specify options for BLA
*BLA Name (name): [DefaultApplication]
BLA Description (description): []
Batch mode example usage
- Using Jython string:
AdminTask.viewBLA('-blaID DefaultApplication')
- Using Jython list:
AdminTask.viewBLA(['-blaID', 'DefaultApplication'])
Interactive mode example usage
- Using Jython:
AdminTask.viewBLA('-interactive')