Using application properties files to install, update, and delete enterprise application files

You can use application properties files to install enterprise application files on a server or cluster, 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)
  1. Specify properties that identify the application and deployment target.
  2. Run the applyConfigProperties command to install the application.
modify (update)
  1. 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. 2. Run the applyConfigProperties command to update the deployed application.
delete (uninstall)
  1. Remove properties that identify the deployment target from the properties file.
  2. 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.
    1. 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
    2. 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 Deployment=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 Deployment=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.
    1. 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
    2. 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.
    1. 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
    2. 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.
    1. 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
    2. 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.
    1. 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
    2. 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.
    1. 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
    2. 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.

    1. 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.
    2. 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.
      1. 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
#
      2. Run the deleteConfigProperties command to uninstall the application.
        AdminTask.deleteConfigProperties('[-propertiesFileName myApplication.props 
-reportFileName report.txt]')
    • Specify DELETE=true and run the applyConfigProperties command.
      1. 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
      2. Run the applyConfigProperties command.

        For an example, see the install step.

  • Edit the deployment options of a deployed application.
    1. 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.

    2. 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.
    1. 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.

    2. 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.