What is WebAphere Application Edition Management (AEM)?
From the WebSphere InfoCenter: Application edition management enables management of interruption-free production application deployments. Using this feature, you can validate a new edition of an application in your production environment without affecting users, and upgrade your applications without incurring user outages. You can also run multiple editions of a single application concurrently, directing different users to different editions, as the ODR maintains not only traditional application state (for example, HTTP session) affinity, but also application version affinity. The ability to queue requests is also employed with the Intelligent Management application edition function if an “atomic” application update that allows pre-provisioning of a new application version, and an “atomic” update of all users from the old application version to the new application version, is desired.
WebSphere Portal only takes advantage of application (portlet) versioning. Since the Portal servlet aggregates portlet markup, the use of ODR will not facilitate routing of certain users to particular versions of a portlet as happens with applications (e.g. servlets) in WebSphere Application Server. The main use of this function in a portal context would be the ability to quickly “roll back” from a current version of a portlet to a previous version in case errors are found or to “roll forward” when a new version is ready to deploy.
Support (or Lack There-of)
The use of AEM is officially “unsupported” in a Portal context. This is mainly due to three reasons. First is the list of caveats which immediately follow. Second is that the Portal UI screens do not have appropriate fields to support AEM versioning. Lastly is the lack of testing of this WebSphere feature.
If a problem does arise with the use of AEM, the IBM Portal support team cannot and will not accept problem reports (PMRs) that arise from arise from the use of AEM in portlets that are being deployed and managed as outlined below in this paper.
However, AEM does work in a limited fashion with WebSphere Portal. This paper shows how to use AEM along with some of the important considerations to consider before employing AEM.
There are several caveats that must be considered when using AEM in a Portal context. Some of these include (but may not be limited to):
1) Portlet Preferences: if a new “edition” of a portlet is created, and the "new" edition adds or removes a portlet preferences, problems will arise. This is due to the way that portlet preferences are stored in the internal Portal database. Don't add or remove portlet preferences in versions of a portlet under AEM control. In other words, the external API of the portlet that is versioned should remain precisely the same.
2) WSRP: WSRP has not been fully tested and the results of changing the “producer” edition is not clear. It is suppected that this would work fine as long as the external API of the producer portlet does not change.
3) Theme module contribution: if the versioned portlet is using module contribution support, to contribute to the theme, the theme cache will have the old contribution unless you clear the theme cache when you also switch the portlet edition via AEM in WAS.
4) Portlet Cache: if the portlet cache is enabled and the AEM portlet is configured to portlet cache, you would have to manually clear out the portlet cache everytime you switch in WAS or accept that the cached version of the HTML markup might be wrong until the portlet cache times out.
5) Legal Requirements: With AEM, it may NOT be known what portlet was in use at a given point in time. Many customers have legal processes in place that require that customer to be able to clearly document what was on the site on a particular point in time. The is no provision in AEM to handle this. However, SystemOut.log files can show when a portlet version was changed. So archiving of logs can aid in this problem.
6) Portlet Eventing: if the portlet is using the JSR286 eventing API, existing page wires can break if different versions change the wiring/eventing model. Again, don't change the external API of the version(s).
7) Portlet Installation: To use AEM, you must use the “pre-deployed portlet EAR” method for installing portlets. And, just like with regular pre-deployed portlets, you cannot switch back to using the Portal GUI to deploy WAR files once a portlet is deployed as an EAR and registered to Portal using XMLAccess. If you do switch installation methods for an already registed portlet, you in an indeterminent state from which recovery might be impossible.
8) “In Use” Portlets: Just as with regular portlet deployments, updating (or changing the version of a portlet) can affect users that are currently using that portlet; particularly if that portlet was “stateful”. The “drain” feature of AEM can help with this. If the drain period is long enough, the probability that users might still be on the portlet decreases.
9) Other caveats: There might be other issues not specifically documented here. The use of AEM in a Portal context should be tested to insure it meets your needs.
Steps to Use AEM In a Portal Context
I have created a portlet call “AEMTest”. It is extremely simple and merely prints the version of itself on the browser screen. Here is the “3rd” version's HTML output:
I created this portlet in RAD. I deployed the initial version (version 1) in WebSphere Application Server as an EAR with this application.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<application id="Application_ID" version="6" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_6.xsd">
The initial version was installed on a deployment manager to a static cluster with no version specified. In the image immediately following is a screen shot from that installation:
Notice that the “Application edition” field is blank. At this point, I “started” the application from the deployment manager console. The portlet was then registered to Portal via the following XMLAccess script:
<request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PortalConfig_8.0.0.xsd" type="update" create-oids="true">
<web-app action="update" uid="AEM.test.alexlang.webap" active="true" predeployed="true"> <url>file:/opt/IBM/WebSphere85/wp_profile/installedApps/aclaix85Cell/AEMTest.ear/AEMTest.war</url>
<portlet-app action="update" active="true" name="com.ibm.aemtest.AEMTestPortlet.47ae6c3a35" uid="AEM.test.alexlang.portlet-app">
<portlet action="update" active="true" name="AEMTest"/>
At this point, I verified the original version worked as expected.
Then, two additional editions of this application were installed. The additional versions merely change the displayed version number in the browser. However, this time the Application edition was noted as in the attached screen shot. This was for “version 2”. Similarly, “version 3” was installed.
Switching Between Versions
With multiple versions (editions) of the same portlet deployed on WebSphere, one can now switch between the “active” version of the edition using the “Edition Control Center” on the Deployment Manager. Using the “Rollout” button on the screen for the “AEMTest” application, allows one to activate and start the desired version on the cluster with one action.
In the following screen, one can see that the “version 3” of the AEMTest portlet is the active version.