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

1. Overview
2. Install an enterprise application on a deployment target.
3. Extract the properties for a deployed enterprise application.
4. Update a single file in a deployed enterprise application.
5. Remove a single file from a deployed enterprise application.
6. Update a single module in a deployed enterprise application.
7. Remove a single module from a deployed enterprise application.
8. Replace, add, or delete multiple files of a deployed enterprise application.
9. Replace the entire deployed enterprise application.
10. Uninstall an application from a deployment target.
11. Edit the deployment options of a deployed application.
12. Redeploy an application.

Overview

Use application properties files to...

• install enterprise application files on a server or cluster
• update deployed applications or modules
• uninstall deployed applications or modules

An enterprise application file must conform to Java EE specifications.

Before installing enterprise application files on an application server, 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...

profile_home/bin/wsadmin -lang Jython

We can use interactive mode with the commands below:

AdminTask.command_name('-interactive')

Instead of running the wsadmin commands manually to apply an application properties file, we can add the properties file to a monitored directory. The product automatically runs the wsadmin commands.

If we are installing a stand-alone web application archive (WAR) or a 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

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. 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. 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. 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. Update the application.

   Running applyConfigProperties applies the properties file.

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. Update the application.

   Running the applyConfigProperties command applies the properties file.

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.

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.

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

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

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.

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.

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. Update the application.

   Running the applyConfigProperties command applies the properties file.

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.

   For IBM extension and binding files, the .xmi or .xml file name extension is different depending on whether we 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.

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
  Use properties files to modify enterprise application deployment properties. An enterprise application must conform to Java EE specifications.

Related:

Installable enterprise module versions

Assemble applications

Install enterprise application files by adding properties files to a monitored directory

Properties file syntax

Prepare for application update settings

PropertiesBasedConfiguration .