Ways to update Java EE applications on WebSphere deployment targets

Ways to update enterprise application files

Option Method Comments Starting after update
Console update wizard Application Types > WebSphere enterprise applications > application > Update > [application|module|file] > Next

Full application Update .ear file.
Single module Update .war, .sar, enterprise bean .jar, or connector .rar file.
Single file Update file other than .ear, .war, .sar, EJB .jar, or .rar.
Partial application Update or remove multiple files.
Enterprise applications > application > Start
Monitored directory Add an application or module with same file name to the monitored directory. Install EAR files by adding them to a monitored directory Started automatically. For installations on a deployment manager monitored directory, WAS does not start an application or module automatically if the node agent or server is not running.
Application properties files Install EAR files by adding properties files to a monitored directory Started automatically. For installations on a deployment manager monitored directory, WAS does not start an application or module automatically if the node agent or server is not running.
wsadmin scripts Use the update or the updateInteractive command wsadmin AdminControl Start the application using the invoke command and the startApplication attribute.
Java API Manage applications through programming Invoke the startApplication method on an ApplicationManager Bean using AdminControl.
Rapid deployment tools No need to assemble the J2EE application files prior to deployment. No need to use other installation tools mentioned in this table. 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 Update the application (.ear), web module (.war), enterprise bean .jar or HTTP plug-in configuration file. We can also use the administrative console to update applications. Any new function which uses annotations can interact substantially with Hot Deployment. See The metadata-complete attribute. Use any of the previous options to start the application. Clicking Start on the Enterprise applications page is the easiest option.

We can update .ear, enterprise bean .jar, web module .war, 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, WAS 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 WAS V6 -- Part 5 Flexible options for updating deployed applications.
If we update module metadata while an application is running, restarting the application might not be sufficient for the changes to take effect. For example, if we change descriptors in running Java EE 6 applications that use annotations, we must reinstall the application. If we 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, we might need to change the metadata-complete attribute.

When metadata-complete is false, two new files are written:

web_merged.xml Contains the results of merged in web.xml with annotations metadata
ibm-metadata.xml 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.

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 below:.
<?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, we 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, we 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.

Update enterprise application files
Remove enterprise files
Install enterprise application files by adding them to a monitored directory
Install enterprise application files by adding properties files to a monitored directory
Get started with wsadmin scripting
Starting applications
Use administrative programs (JMX)
Manage applications through programming
Starting an application through programming
Update installed applications using wsadmin
Enterprise application collection
Commands for the AdminApp object
Commands for the AdminControl object
IBM WebSphere Developer Technical Journal: System management for WAS V6 -- Part 5 Flexible options for updating deployed applications
Rapid deployment of J2EE applications

web_merged.xml	Contains the results of merged in web.xml with annotations metadata
ibm-metadata.xml	Contains additional annotations-related data, which cannot be stored in web_merged.xml.