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

We 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 EE specifications.

Before we 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 the application files can be installed to the 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.

Use an application properties file, we can install, update, or uninstall an enterprise application or module.

Run administrative commands using wsadmin to deploy an application.

files. We can specify properties that install, update,

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, we can use interactive mode with the commands:

AdminTask.command_name('-interactive')

Instead of running wsadmins manually to apply an application properties file, we can add the properties file to a monitored directory. The product automatically runs wsadmins. See Installing enterprise application files by adding properties files to a monitored directory.

If we are installing a stand-alone 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:

• Install an enterprise application on a deployment target.

• Extract the properties for a deployed enterprise application.

• Update a single file in a deployed enterprise application.

• Remove a single file from a deployed enterprise application.

• Update a single module in a deployed enterprise application.

• Remove a single module from a deployed enterprise application.

• Replace, add, or delete multiple files of a deployed enterprise application.

• Replace the entire deployed enterprise application.

• Uninstall an application from a deployment target.

• Edit the deployment options of a deployed application.

• Deploy an application again.

• Install an enterprise application on a deployment target.

  1. Create a properties file identifying 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 Application=MyApplication]')

  Running this Jython example produces a file named myApp.props that lists the properties of an Application configuration object named MyApplication. We 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 we can edit (true) and which we 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. We 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.

  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.

  We 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. We 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 the 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

  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

We can use the properties file to configure and manage the application object and its properties.

What to do next

Save the changes to the configuration.

Subtopics

• Work with application deployment properties files
  We can use properties files to modify enterprise application deployment properties. An enterprise application must conform to Java EE specifications.

Related concepts

Installable enterprise module versions

Related tasks

Assembling applications

(dist)(zos) Install enterprise application files by adding properties files to a monitored directory

Properties file syntax

Preparing for application update settings

PropertiesBasedConfiguration (AdminTask)