Network Deployment (Distributed operating systems), v8.0 > Scripting the application serving environment (wsadmin) > Use properties files to manage system configuration > Manage specific configuration objects using properties files

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 you can install 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 your deployment targets.

Start wsadmin.sh. 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, you can install, update, or uninstall an enterprise application or module.

Run administrative commands using wsadmin to deploy an application.

Actions for application properties files. We 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 applyConfigProperties 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. Run applyConfigProperties to update the deployed application.
delete (uninstall)	1. Remove properties that identify the deployment target from the properties file. 2. Run deleteConfigProperties 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 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.

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 applyConfigProperties to install the application.

     Run applyConfigProperties 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]')
  

  Run 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 you can edit (true) and which you cannot edit (false).

  New feature: 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]]]')
  

  New feature:

  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 applyConfigProperties to update the application.

     Run applyConfigProperties 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 applyConfigProperties to update the application.

     Run applyConfigProperties 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 applyConfigProperties to update the application.

     Run applyConfigProperties 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 applyConfigProperties to update the application.

     Run applyConfigProperties 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. Use 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 applyConfigProperties to update the application.

     Run applyConfigProperties 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 applyConfigProperties to update the application.

     Run applyConfigProperties 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 deleteConfigProperties.
    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 deleteConfigProperties to uninstall the application.

       AdminTask.deleteConfigProperties('[-propertiesFileName myApplication.props
       -reportFileName report.txt]')
       

  • Specify DELETE=true and run applyConfigProperties.
    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 applyConfigProperties.

       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 applyConfigProperties to update the application.

     Run applyConfigProperties 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.

     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 applyConfigProperties to update the application.

     Run applyConfigProperties 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.
Installable enterprise module versions
Assembling applications
Install enterprise application files by adding properties files to a monitored directory

Related

Properties file syntax
Prepare for application update settings
PropertiesBasedConfiguration command group using wsadmin.sh

+

Search Tips   |   Advanced Search