You can use application properties files to install enterprise
application files on a server,
update deployed applications or modules, or uninstall deployed applications
or modules. An enterprise application file must conform to Java Platform, Enterprise Edition
(Java EE) specifications.
Before you begin
Before you can install enterprise application files on
an application server, you must assemble modules as needed. Also,
configure the target application server. As part of configuring the
server, determine whether your application files can be installed
to your deployment targets.
Start the wsadmin scripting tool.
To start wsadmin using the Jython language, run the wsadmin
-lang Jython command from the bin directory
of the deployment target profile.
About this task
Using an application properties file, you can install,
update, or uninstall an enterprise application or module.
Run
administrative commands using wsadmin to deploy an application.
Table 1. Actions for application properties
files. You can specify properties that install, update,
or uninstall applications.Action |
Procedure |
create (install) |
- Specify properties that identify the application and deployment
target.
- Run the applyConfigProperties command to install
the application.
|
modify (update) |
- Edit application properties in the properties file. To update
an application file, specify in the Properties section:
- Update=true
- operationType=add, operationType=update or operationType=delete
- contentType=file, contentType=moduleFile, contentType=partialapp,
or contentType=app
- 2. Run the applyConfigProperties command to
update the deployed application.
|
delete (uninstall) |
- Remove properties that identify the deployment target from the
properties file.
- Run the deleteConfigProperties command to uninstall
the deployed application.
|
create Property |
Not applicable |
delete Property |
Not applicable |
Optionally, you can use interactive mode with the commands:
AdminTask.command_name('-interactive')
Instead
of running the wsadmin commands manually to apply an application properties
file, you can add the properties file to a monitored directory. The
product automatically runs the wsadmin commands. See Installing enterprise
application files by adding properties files to a monitored directory.
If
you are installing a stand-alone web application archive (WAR) or
a Session Initiation Protocol (SIP) archive (SAR), specify the context
root of the WAR or SAR file. The context root is combined with the
defined servlet mapping (from the WAR file) to compose the full URL
that users type to access the servlet. For example, if the context
root is /gettingstarted and the servlet mapping is MySession,
then the URL is http://host:port/gettingstarted/MySession.
This
topic describes how to complete the following procedures:
Procedure
- Install an enterprise application on a deployment
target.
- Create a properties file that identifies the application
and deployment target.
Open an editor and create a properties
file such as the following to install an Application configuration
object:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
CreateDeleteCommandProperties=true
ResourceId=Deployment=
# Properties
Name=hello
TargetServer=!{serverName}
TargetNode=!{nodeName}
EarFileLocation=/temp/Hello.ear
#TargetCluster=cluster1
#
EnvironmentVariablesSection
#
#
#Environment Variables
cellName=myCell04
nodeName=myNode
serverName=myServer
- Run the applyConfigProperties command
to install the application.
Running the applyConfigProperties command
applies the properties file. In this Jython example, the optional -reportFileName parameter
produces a report named report.txt:
AdminTask.applyConfigProperties(['-propertiesFileName myObjectType.props -reportFileName report.txt '])
- Extract the properties for a deployed enterprise
application.
Run the extractConfigProperties command
to extract the configuration attributes and values of a deployed enterprise
application to a properties file:
AdminTask.extractConfigProperties('[-propertiesFileName myApp.props -configData Application=MyApplication]')
Running
this Jython example produces a file named myApp.props that
lists the properties of an Application configuration object named MyApplication.
You can use the extracted properties file to view and edit the properties
of the application. The MapModulesToServers section of the properties
file resembles the following:
#
# SubSection 1.0.2
# MapModulesToServers Section. taskName and row0 should not be edited. row0 contains column names for the task.
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
#Properties
#
taskName=MapModulesToServers
row2={"My Web Application" MyWebApplication.war,WEB-INF/web.xml WebSphere:cell=!{cellName},
node=!{nodeName},server=!{serverName}
23 moduletype.web "Web Module"}
row1={"My Enterprise Java Bean" My.jar,META-INF/ejb-jar.xml WebSphere:cell=!{cellName},node=!{nodeName},
server=!{serverName} 20 moduletype.ejb "EJB Module"}
mutables={false false true false false false} #readonly
row0={module uri server ModuleVersion moduletype moduletypeDisplay} #readonly
By
default, the extractConfigProperties command produces
output that displays all columns, including hidden and non-hidden
columns, of install task and task data values in separate rows. The mutables row
shows which columns you can edit (true) and which
you cannot edit (false).
To enhance the output
of application properties, run the AdminTask extractConfigProperties command
with the SimpleOutputFormat option. When the option
is set to true, the output displays non-hidden columns
of application properties in columnName=value pairs.
Hidden columns of application properties are not included in the output.
The enhanced output makes it easier for you to find and edit application
property values. You can use an edited properties file to install
or update an application. The following example specifies the SimpleOutputFormat option
in the extractConfigProperties command:
AdminTask.extractConfigProperties('[-propertiesFileName myApp.props -configData Application=MyApplication
-option [[SimpleOutputFormat true]]]')
With
the SimpleOutputFormat option, the MapModulesToServers
section of the extracted application properties file resembles the
following:
#
# SubSection 1.0.2
# MapModulesToServers Section. taskName and lines marked as "#readonly" should not be edited.
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
#Properties
#
taskName=MapModulesToServers
row0={ module="My Enterprise Java Bean" #readonly
uri=My.jar,META-INF/ejb-jar.xml #readonly
server=WebSphere:cell=!{cellName},node=!{nodeName},server=!{serverName} }
row1={ module="My Web Application" #readonly
uri=MyWebApplication.war,WEB-INF/web.xml #readonly
server=WebSphere:cell=!{cellName},node=!{nodeName},server=!{serverName} }
- Update a single file in a deployed enterprise
application.
- Edit the application properties file so that it specifies
the file to add or change.
Edit the properties of an
Application configuration object. Specify Update=true,
an operation type such as operationType=add, and contentType=file in
the Properties section. The following example adds the addMe.jsp file
to a deployed application named hello:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
CreateDeleteCommandProperties=true
ResourceId=Deployment=hello
#
#
# Properties
#
Name=hello
Update=true
operationType=add
contentType=file
contentURI=test.war/com/ibm/addMe.jsp
contentFile=c:/temp/addMe.jsp
- Run the applyConfigProperties command
to update the application.
Running the applyConfigProperties command
applies the properties file. For an example, see the install step.
- Remove a single file from a deployed enterprise
application.
- Edit the application properties file so that it specifies
the file to remove.
Edit the properties of an Application
configuration object. Specify Update=true, operationType=delete,
and contentType=file in the Properties section. The
following example removes the addMe.jsp file
from a deployed application named hello:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
CreateDeleteCommandProperties=true
ResourceId=Deployment=hello
#
#
# Properties
#
Name=hello
Update=true
operationType=delete
contentType=file
contentURI=test.war/com/ibm/addMe.jsp
- Run the applyConfigProperties command
to update the application.
Running the applyConfigProperties command
applies the properties file. For an example, see the install step.
- Update a single module in a deployed enterprise
application.
- Edit the application properties file so that it specifies
the Java EE module to add or change.
Edit the properties
of an Application configuration object. Specify Update=true,
an operation type such as operationType=add, and contentType=moduleFile in
the Properties section. The following example adds the Increment.jar file
to a deployed application named hello:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
CreateDeleteCommandProperties=true
ResourceId=Deployment=hello
#
#
# Properties
#
Name=hello
Update=true
operationType=add
contentType=modulefile
#contextRoot=”/mywebapp” # required for web module only
contentURI=Increment.jar
contentFile=c:/apps/app1/Increment.jar
deployEJB=false
- Run the applyConfigProperties command
to update the application.
Running the applyConfigProperties command
applies the properties file. For an example, see the install step.
- Remove a single module from a deployed enterprise
application.
- Edit the application properties file so that it specifies
the Java EE module to remove.
Edit the properties of an Application configuration object.
Specify Update=true, operationType=delete,
and contentType=moduleFile in the Properties section.
The following example removes the test.war file
from a deployed application named hello:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
CreateDeleteCommandProperties=true
ResourceId=Deployment=hello
#
#
# Properties
#
Name=hello
Update=true
operationType=delete
contentType=moduleFile
contentURI=test.war
- Run the applyConfigProperties command
to update the application.
Running the applyConfigProperties command
applies the properties file. For an example, see the install step.
- Replace, add, or delete multiple files of
a deployed enterprise application.
This option specifies
to update multiple files of an installed application by uploading
a compressed file. Depending on the contents of the compressed file,
a single use of this option can replace files in, add new files to,
and delete files from the installed application. Each entry in the
compressed file is treated as a single file and the path of the file
from the root of the compressed file is treated as the relative path
of the file in the installed application.
- To replace a file, a file in the compressed file must have the
same relative path as the file to be updated in the installed application.
- To add a new file to the installed application, a file in the
compressed file must have a different relative path than the files
in the installed application.
- The relative path of a file in the installed application is formed
by concatenation of the relative path of the module (if the file is
inside a module) and the relative path of the file from the root of
the module separated by /.
- To remove a file from the installed application, specify metadata
in the compressed file using a file named META-INF/ibm-partialapp-delete.props at
any archive scope. The ibm-partialapp-delete.props file
must be an ASCII file that lists files to be deleted in that archive
with one entry for each line. The entry can contain a string pattern
such as a regular expression that identifies multiple files. The file
paths for the files to be deleted must be relative to the archive
path that has the META-INF/ibm-partialapp-delete.props file.
For more information on the metadata
.props file
to include in compressed files, see the
"Replace, add, or delete
multiple files" section in Preparing for application update settings.
- Edit the application properties file so that it specifies
the compressed file.
Edit the properties of an Application
configuration object. Specify Update=true, operationType=update,
and contentType=partialapp in the Properties section.
The following example uses the myAppPartial.zip compressed
file to update a deployed application named hello:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
CreateDeleteCommandProperties=true
ResourceId=Deployment=hello
#
#
# Properties
#
Name=hello
Update=true
operationType=update
contentType=partialapp
contentFile= c:/temp/MyApp/myAppPartial.zip
- Run the applyConfigProperties command
to update the application.
Running the applyConfigProperties command
applies the properties file. For an example, see the install step.
- Replace the entire deployed enterprise application.
This option specifies to replace the application already
installed on a deployment target with a new (updated) enterprise application .ear file.
- Edit the application properties file so that it specifies
the application file.
Edit the properties of an Application
configuration object. Specify Update=true, operationType=update,
and contentType=app in the Properties section. The
following example replaces the newApp1.ear file
of a deployed application named hello. The useDefaultBindings=true property
instructs the product to generate default bindings for the application.
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
CreateDeleteCommandProperties=true
ResourceId=Deployment=hello
#
#
# Properties
#
Name=hello
Update=true
operationType=update
contentType=app
contentFile=c:/apps/app1/newApp1.ear
useDefaultBindings=true
When the full application is updated,
the old application is uninstalled and the new application is installed.
When the configuration changes are saved and subsequently synchronized,
the application files are expanded on the node where application will
run. If the application is running on the node while it is updated,
then the application is stopped, application files are updated, and
application is started.
- Run the applyConfigProperties command
to update the application.
Running the applyConfigProperties command
applies the properties file. For an example, see the install step.
- Uninstall an application from a deployment
target.
You can uninstall an application in either of
two ways:
- Specify CreateDeleteCommandProperties=true and
run the deleteConfigProperties command.
- Edit the properties file so that it identifies the application
but no longer identifies the deployment target. For example, specify
properties such as the following to uninstall an Application configuration
object named hello:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
CreateDeleteCommandProperties=true
ResourceId=Deployment=hello
#
#
# Properties
#
Name=hello
#
- Run the deleteConfigProperties command to uninstall
the application.
AdminTask.deleteConfigProperties('[-propertiesFileName myApplication.props
-reportFileName report.txt]')
- Specify DELETE=true and run the applyConfigProperties command.
- Edit the properties file so that it identifies the application
but no longer identifies the deployment target. For example, specify
properties such as the following to uninstall an Application configuration
object named hello:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
DELETE=true
ResourceId=Deployment=hello
# Properties
Name=hello
- Run the applyConfigProperties command.
For
an example, see the
install step.
- Edit the deployment options of a deployed application.
- Edit the properties file so that it specifies new or
changed deployment options.
For example, specify properties
such as the following for an Application configuration object named appl:
#
# Header
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Deployment=appl
#
#
# Properties
#
taskName=AppDeploymentOptions
row1={$(APP_INSTALL_ROOT)/$(CELL)
AppDeploymentOption.Yes
AppDeploymentOption.No
AppDeploymentOption.No
AppDeploymentOption.No
""
off .*\.dll=755#.*\.so=755#.*\.a=755#.*\.sl=755
"WASX.SERV1 [x0617.27]"
AppDeploymentOption.No
AppDeploymentOption.No}
mutables={true true true true true true true true false true true}
row0={installed.ear.destination
distributeApp
useMetaDataFromBinary
createMBeansForResources
reloadEnabled
reloadInterval
validateinstall
filepermission
buildVersion
allowDispatchRemoteInclude
allowServiceRemoteInclude} #readonly
row1 contains current values for each
property. To change a property, modify values in row1.
mutables specifies
whether a given property can be changed.
row0 specifies
deployment property names.
- Run the applyConfigProperties command
to update the application.
Running the applyConfigProperties command
applies the properties file. For an example, see the install step.
- Redeploy an application.
- Edit the properties file so that it specifies deployment
options as needed.
For example, specify properties such
as the following for an Application configuration object named
myApp.
- mutables specifies whether a given property can
be changed.
- row0 specifies deployment property names.
- row1 contains current values for each property.
To change a property, modify values in row1.
#
# Header MapModulesToServers
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Deployment=!{applicationName}
#
#
# Properties
#
taskName=MapModulesToServers
mutables={false false true false false false} #readonly
row0={module uri server ModuleVersion moduletype moduletypeDisplay} # readonly
row1={“My Web Module” myWebModule.war,WEB-INF/web.xml WebSphere:cell=!{cellName},node=!{nodeName},
server=!{serverName} 14 moduletype.web "Web Module"}
row2={"My EJB module" MyEjbModule.jar,META-INF/ejb-jar.xml WebSphere:cell=!{cellName},node=!{nodeName},
server=!{serverName} 13 moduletype.ejb "EJB Module"}
#
#
# Header MapRolesToUsers
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
# Properties
#
taskName=MapRolesToUsers
row0={role role.everyone role.all.auth.user role.user role.group role.all.auth.realms role.user.access.ids role.group.access.ids} #readonly
mutables={false true true true true true true true} #readonly
row1={administrator AppDeploymentOption.No AppDeploymentOption.No "adminuser" "admingroup"
AppDeploymentOption.No "" ""}
#
# Header BindJndiForEJBNonMessageBinding
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
#Properties
#
taskName=BindJndiForEJBNonMessageBinding
row0={EJBModule EJB uri JNDI ModuleVersion localHomeJndi remoteHomeJndi} #readonly
mutables={false false false true false true true} #readonly
row1={"My EJB module" myEjb myEjbModule.jar,META-INF/ejb-jar.xml myEjb 20 "" “"}
#
#
# Header MapEJBRefToEJB
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
#Properties
#
taskName=MapEJBRefToEJB
row0={module EJB uri referenceBinding class JNDI ModuleVersion} #readonly
mutables={false false false false false true false} #readonly
row1={"My EJB module" myEJB MyEjbModule.jar,META-INF/ejb-jar.xml myEJB
com.ibm.defaultapplication.Increment Increment 23}
#
#
# Header DataSourceFor20EJBModules
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
#Properties
#
taskName=DataSourceFor20EJBModules
row0={AppVersion EJBModule uri JNDI resAuth login.config.name auth.props dataSourceProps} #readonly
mutables={false false false true true true true true} #readonly
row1={13 "My EJB module" MyEjbModule.jar,META-INF/ejb-jar.xml MyDataSource
cmpBinding.perConnectionFactory "" "" ""}
#
#
# Header DataSourceFor20CMPBeans
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
# Properties
#
taskName=DataSourceFor20CMPBeans
row0={AppVersion EJBVersion EJBModule EJB uri JNDI resAuth login.config.name auth.props} #readonly
mutables={false false false false false true true true true} #readonly
row1={13 13 "My EJB module" MyEjb MyEjbModule.jar,META-INF/ejb-jar.xml myDataSource
cmpBinding.perConnectionFactory "" ""}
#
#
# Header MapWebModToVH
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
# Properties
#
taskName=MapWebModToVH
row0={webModule uri virtualHost} #readonly
mutables={false false true} #readonly
row1={"My Web Application" MyWebModule.war,WEB-INF/web.xml default_host}
#
#
# Header CtxRootForWebMod
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
# Properties
#
taskName=CtxRootForWebMod
row0={webModule uri web.contextroot} #readonly
mutables={false false true} #readonly
row1={"My Web Application" MyWebModule.war,WEB-INF/web.xml /}
#
#
# Header MapSharedLibForMod
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
# Properties
#
taskName=MapSharedLibForMod
row0={module uri sharedLibName} #readonly
mutables={false false true} #readonly
row2={"My Web Application" MyWebModule.war,WEB-INF/web.xml ""}
row1={myApp META-INF/application.xml ""}
#
#
# Header JSPReloadForWebMod
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
# Properties
#
taskName=JSPReloadForWebMod
row0={webModule uri jspReloadEnabled jspReloadInterval} #readonly
mutables={false false true true} #readonly
row1={"My Web Application" MyWebModule.war,WEB-INF/ibm-web-ext.xmi AppDeploymentOption.Yes 10}
#
#
# Header SharedLibRelationship
#
ResourceType=Application
ImplementingResourceType=Application
ResourceId=Cell=!{cellName}:Deployment=!{applicationName}
#
#
# Properties
#
taskName=SharedLibRelationship
row0={module uri relationship compUnitName matchTarget origRelationship}
#readonly
mutables={false false true true true false} #readonly
row2={"My Web Application" MyWebModule.war,WEB-INF/web.xml "" "" AppDeploymentOption.Yes ""}
row1={myApp META-INF/application.xml "" "" AppDeploymentOption.Yes ""}
#
EnvironmentVariablesSection
#
# Environment Variables
#
cellName=myCell04
applicationName=myApp
nodeName=myNode
serverName=myServer
In this example, only the most common
tasks such as MapModulesToServer and CtxRootForWebMod are shown. You
can obtain properties for tasks that are not in the example by extracting
the properties of an existing application and modifying the contents
of the extracted properties file to match the environment of your
application.
Supported configurations: For IBM® extension
and binding files, the .xmi or .xml file name extension is different
depending on whether you are using a pre-Java EE 5 application or
module or a Java EE 5 or later
application or module. An IBM extension
or binding file is named ibm-*-ext.xmi or ibm-*-bnd.xmi where * is
the type of extension or binding file such as app, application, ejb-jar,
or web. The following conditions apply:
- For an application or module that uses a Java EE version prior to version 5, the file
extension must be .xmi.
- For an application or module that uses Java EE 5 or later, the file extension must
be .xml. If .xmi files are included with the application or module,
the product ignores the .xmi files.
However, a Java EE
5 or later module can exist within an application that includes pre-Java
EE 5 files and uses the .xmi file name extension.
The ibm-webservices-ext.xmi, ibm-webservices-bnd.xmi, ibm-webservicesclient-bnd.xmi, ibm-webservicesclient-ext.xmi,
and ibm-portlet-ext.xmi files continue to use
the .xmi file extensions.
sptcfg
- Run the applyConfigProperties command
to update the application.
Running the applyConfigProperties command
applies the properties file. For an example, see the install step.
Results
You can use the properties file to configure and manage
the application object and its properties.
What to do next
Save the changes to your configuration.