Ways to update enterprise application files

You can update Java™ Platform, Enterprise Edition (Java EE) application files deployed on a server in several ways.

Table 1. Ways to update application files. You can update application files using the console, wsadmin, programming, or deployment tools
Option	Method	Comments	Starting after update
Administrative console update wizard See Updating enterprise applications with the console. To remove a single file from a Java EE application or module, see the topic on removing enterprise files.	Briefly, do the following: Go to the Enterprise applications page. Click Applications > Application Types > WebSphere enterprise applications in the console navigation tree. Select the application to update and click Update. On the Preparing for application update page, identify the application, module or files to update and click Next. Complete steps in the update wizard and click Finish.	On the Preparing for application update page: Use Full application to update an .ear file. Use Single module to update a .war, .sar, enterprise bean .jar, or connector .rar file. Use Single file to update a file other than an .ear, .war, .sar, EJB .jar, or .rar file. Use Partial application to update or remove multiple files.	On the Enterprise applications page, select the updated application and click Start.
wsadmin scripts See the topic on updating installed applications using the wsadmin scripting tool.	Use the update command or the updateInteractive command in a script or at a command prompt. For more information on the update and updateInteractive commands, see the topic on commands for the AdminApp object.	The Getting started with wsadmin scripting topic provides an overview of wsadmin.	Start the application using the invoke command and the startApplication attribute. For more information about the invoke command, see the topic on commands for the AdminControl object.
Java application programming interfaces See the topic on using administrative programs (JMX).	Update deployed applications by completing the steps in the topic on managing applications through programming.	Update an application in the following ways: Update the entire application Add to, replace or delete multiple files in an application Add a module to an application Update a module in an application Delete a module in an application Add a file to an application Update a file in an application Delete a file in an application	Invoke the startApplication method on an ApplicationManager MBean using AdminControl.
Rapid deployment tools See topics under Rapid deployment of J2EE applications.	Briefly, do the following: Update your J2EE application files. Set up the rapid deployment environment. Create a free-form project. Launch a rapid deployment session. Drop your updated application files into the free-form project.	Rapid deployment tools offer the following advantages: You do not need to assemble your J2EE application files prior to deployment. You do not need to use other installation tools mentioned in this table to deploy the files.	Use any of the previous options to start the application. Clicking Start on the Enterprise applications page is the easiest option.
Hot deployment and dynamic reloading	Briefly, do the following: Update your application (.ear), web module (.war), enterprise bean .jar or HTTP plug-in configuration file. Follow instructions in Hot deployment and dynamic reloading to update your file.	If you are new to WebSphere® Application Server, use the administrative console to update applications. That option is easier. Hot deployment and dynamic reloading is more difficult to complete. You must directly manipulate the application or module file on the server where the application is deployed. In particular, any new function that uses annotations can interact substantially with Hot Deployment. For more information, see the metadata-complete attribute when you deploy applications with hot deployment.	Use any of the previous options to start the application. Clicking Start on the Enterprise applications page is the easiest option.

You can update .ear, enterprise bean .jar, web module .war, Session Initiation Protocol (SIP) archive (.sar), connector .rar, application client .jar, and any other files used by an installed application.

If the application is updated while it is running, WebSphere Application Server automatically stops the application, updates the application logic and restarts the application. If the application does not start automatically, start it manually using one of the Starting options. For more information on the restarting of updated applications, refer to Fine-grained recycle behavior in IBM® WebSphere Developer Technical Journal: System management for WebSphere Application Server V6 -- Part 5 Flexible options for updating deployed applications.

If you update module metadata while an application is running, restarting the application might not be sufficient for the changes to take effect. For example, if you change descriptors in running Java EE 6 applications that use annotations, you must reinstall the application. If you change classes that introduce, remove, or alter class hierarchies within an application, and those changes impact annotated classes, you also must reinstall the application.

The metadata-complete attribute

When updating the metadata for a web module, you might need to change the metadata-complete attribute.

When metadata-complete is false, two new files are written: web_merged.xml, which contains the results of merged in web.xml with annotations metadata, plus a new file, ibm-metadata.xml, which contains additional annotations-related data, which cannot be stored in web_merged.xml. The web_merged.xml file also contains additional metadata that is read from web-fragment.xml in JAR files under WEB-INF/lib of the WAR.
When metadata-complete is true, web_merged.xml is NOT generated and ibm-metadata.xml is NOT created. The ibm-metadata.xml file is only generated if a web_merged.xml file is generated.

Note: The metadata-complete attribute can be omitted from web.xml (or web-fragment.xml). When metadata-complete is omitted, its default value is false.

The metadata-complete attribute must be added to the web.xml file or the web_merged.xml file as shown in the following example:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" 
xmlns:xsi="http://www.w3.org/2011/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
http://java.sun.com/xml/ns/javaee/web-app_3.0.xsd" 
version="3.0" metadata-complete="true">
<display-name>TestServlet30</display-name>
</web-app>

The web.xml and web_fragment.xml files should be updated, if these files are driving the hot deployment update. If only web_merged.xml is updated, the hot deployment changes are lost if any administrative action is taken that causes a regeneration of web_merged.xml.

Important: If metadata-complete is false in web.xml, you must update web.xml and web_merged.xml on hot deployment of Servlet (web) 2.5 applications. If metadata-complete is true in web.xml, you must update ONLY web.xml on hot deployment of Servlet (web) 2.5 applications.

Processing of web.xml in a WAR file and ejb-jar.xml in an EJBJAR file are the same, with web_merged.xml created for a WAR file if the web.xml is absent or has metadata-complete set to false, with ejb-jar_merged.xml created for an EJBJAR file if the ejb-jar.xml is absent or has metadata-complete set to false.

In either case, an ibm-metadata.xml is created whenever a merged XML is created. (And only if the merged XML is created.)

If the deployment changes metadata-complete from false to true, the XML file (web.xml or ejb-jar.xml) is created or replaced, no merged XML file is created, and no ibm-metadata.xml is created.

The additional case is for EJB content in a WAR file (EJB-IN-WAR). For this case, there are additional complex rules:

The web.xml metadata-complete setting interacts with the EJB-IN-WAR processing.
When no EJB content is present in the WAR file, no EJB-IN-WAR processing is performed..
Deployment might independently change metadata-complete from false to true for either the web.xml or the ejb-jar.xml.
ibm-metadata.xml is created when either of the merged XML is created. (And is not created when neither merged XML is created.)

As to EJB-IN-WAR, the following rules apply:

When the web.xml has metadata-complete set to true, and no ejb-jar.xml is present, no EJB-IN-WAR processing is done, even when EJB annotations are present in the WAR file.
When the web.xml has metadata-complete set to false (or when the web.xml is absent), and when no ejb-jar.xml is present, EJB-IN-WAR processing is performed only when EJB annotations are present in the WAR file.
When an ejb-jar.xml is present, the metadata-complete setting of the web.xml is not used to determine what EJB processing is done. When an ejb-jar.xml is present, what EJB-IN-WAR processing is done is determined by the metadata-complete setting of the ejb-jar.xml.