Devbits

JEE 5 makes most of the deployment descriptors optional. For example, the annotation @Stateless can be used to identify a stateless session bean instead of adding a declaration in META-INF/ejb-jar.xml of an EJB module. To add to this, WebLogic Server 10 has extended the JEE annotation support to include annotations that make web module’s deployment descriptor optional. For example, the @WLServlet annotation can be used as an alternate for declaration in WEB-INF/web.xml. Finally, the JEE Spec has made the META-INF/application.xml optional in an enterprise application. In case META-INF/application.xml is absent, the app servers are required to examine the contents and make inference about their types. For example, a module ending with “.war” must be interpreted as a web module and should be deployed as one.

With configuration scattered around in source files and packaging details, an administrator might want to examine the consolidated configuration. The developer of the application might also want to examine the container’s view of the configuration for debugging. Two of the build time tools packaged with WebLogic Server help the administrators & the developers do exactly this. Both AppMerge & AppC now support a new flag “writeInferredDescriptors”. When this flag is used, these tools write out an updated version of the descriptors that include the configuration information from annotations and packaging. In case, the descriptors does not exist in the source application, these tools write out new descriptors if the flag is used.

Let’s assume we have an application flight.ear that has no descriptors. It has two archived modules:

$ jar tf flight.ear
statusApp.war
statusCheck.jar

Let’s assume that statusApp.war has no descriptors and has one Servlet that is annotated with @WLServlet annotation.

$ jar tf statusApp.war
WEB-INF/
WEB-INF/classes/
WEB-INF/classes/weblogic/
WEB-INF/classes/weblogic/examples/
WEB-INF/classes/weblogic/examples/flight/
WEB-INF/classes/weblogic/examples/flight/Status.class

Let’s assume that the statusCheck.jar has no descriptors either. It has some class files, one of which is a Stateless session bean that’s annotated with @Stateless & @Remote annotations

$ jar tf statusCheck.jar
weblogic/
weblogic/examples/
weblogic/examples/flight/
weblogic/examples/flight/FlightCheck.class
weblogic/examples/flight/FlightCheckBean.class

If we were to invoke AppMerge in the following way, it’ll generate a new version of flight.ear, called flightX.ear.

$ java weblogic.appmerge -writeInferredDescriptors -output flightX.ear/ flight.ear

(In this example, I appended a ‘/’ at the end of flightX.ear so that the tool creates the output application as a directory. We could drop the '/' in the end (-output flightX.ear) and the tool would generate an archive.)

If we were now to examine flightX.ear, it’ll have a deployment descriptor.

$ cat flightX.ear/META-INF/application.xml
<?xml version='1.0' encoding='UTF-8'?>
<jav:application xmlns:jav="http://java.sun.com/xml/ns/javaee">
  <jav:module>
    <jav:web>
      <jav:web-uri>statusApp.war</jav:web-uri>
      <jav:context-root>statusApp</jav:context-root>
    </jav:web>
  </jav:module>
  <jav:module>
    <jav:ejb>statusCheck.jar</jav:ejb>
  </jav:module>
</jav:application>

Similarly, the two modules in flightX.ear would now have descriptors:

$ jar tf flightX.ear/statusApp.war WEB-INF/web.xml
WEB-INF/web.xml
$ jar tf flightX.ear/statusCheck.jar META-INF/ejb-jar.xml
META-INF/ejb-jar.xml

These descriptors can now be examined to see how the containers would deal with the module deployment. Note that the descriptors in the modules would have “metadata-complete” attribute on the root element set to true.

The flag "writeInferredDescriptors" can also be used for deployment optimization. If we were to deploy flightX.ear, the annotation processing would not be done because metadata-complete is set to true. Module discovery wouldn’t be done either because META-INF/application.xml would now be present in the application.

I tend to use more of command line tools for WebLogic Server administration. But I do use console especially when I am examining and debugging domains on remote machines. It's great news that WebLogic Server console has become much faster with this release. And the configuration locking mechanism is now implicit in development mode. So I can simply go ahead and make the configuration changes without having to explicitly acquire locks.

This video captures how fast the console works on my laptop. It's a Pentium M 1.8GHz with 2GB RAM running Windows XP SP2. I installed WebLogic Server 10.3 on it, created a new domain and started domain's admin server. In this video, I used the console to deploy and monitor a simple web application.

With WebLogic Server 10.3, there have been some changes in deployment descriptor schemas. This post discusses some of the issues that we faced in maintaining multiple loosely related XML schemas and how we tackled them. Note that none of these changes require changes to deployment descriptors. As always, old applications would continue to deploy and run without any change.

Old Namespace
We started off with a shared & stable set of schema in 9.0, all of which shared a common namespace URI: http://www.bea.com/ns/weblogic/90. Since then we haven’t made any incompatible changes to the schemas, and making any such change seems unlikely. However, the schemas do change across major releases, minor releases and even in maintenance packs. Such changes are almost always independent of each other, that is, it’s highly likely that only one of the schema document changes.

The main problem with http://www.bea.com/ns/weblogic/90 was that it included version information. When schema changes were made for a minor release or for a maintenance pack, we had to update the namespace for that schema. This was usability issue. In such a release, when an application developer wrote new descriptors, she had to deal with similar looking but different namespaces.

We could come up with a solution to schema versioning without changing the namespace within a major release, but we would still have to change the namespace once the schema changes happen for the next major release. This was a tooling issue. An application developer who performed pre-validation on her descriptors would have to change her descriptor to use the new namespace. This was also a maintenance issue for us. Each time we changed the namespace, we had to change our internal components that took care of backward compatibility.

The old convention also forced the same namespace on all the schemas. This contributed to the usability issue mentioned in the previous section. Also, it added to maintenance by forcing us to move the unchanged schemas to a new a namespace, every major release. This model did not fit well with modularity either. As teams owning the schemas spread out, we would need extra communication and co-ordination to avoid type name collisions for new types being added.

New namespaces
With WebLogic Server 10.3, all schemas now declare their own namespaces, none of which have any version in namespace URI. The general pattern of new namespace URIs is http://www.bea.com/ns/weblogic/. For example, the namespace URI for weblogic.xml is http://www.bea.com/ns/weblogic/weblogic-web-app

This change addresses the two major problems and lays out a road map for schema versioning in the future. This will help the schemas evolve independently. Representing an entire namespace in one schema also provides a cleaner extensibility model for our application developers and ISVs.

In general, namespace URI wouldn't be changed even across major releases, unless drastic changes occur and we are forced to introduce incompatible changes. Again note that even if drastic changes to schema force us to change the namespace URI, old applications would continue to work without any change.

For documentation and referencing, we do need to capture the version information of the schema, inside the schema. This is done using the “version” attribute of element at the top of each schema:

<xsd:schema ..

  version=”1.0”>

..

</xsd:schema>

We also introduced “version” attribute at the root element of each descriptor. This is somewhat similar to the version attribute for each of the Java EE descriptors. The Java EE descriptors version attribute is required and is an enumeration of supported versions. But we are not strict about this because our parsing infrastructure does a good job of in-memory conversion of document into the latest schema structure. Also, our schemas are revised more often than those of Java EE. So introducing an enumeration of possible values would be cumbersome to maintain in the future. Hence, our version attribute is optional and and of string type. Containers might use this value in the future. Here is how this would look in a descriptor:

<weblogic-web-app version=”1.0”>

..

</weblogic-web-app>

Schema Locations
Each version of every schema is published on the web for reference. The same location may also be used for schema validation in case an XML parser or editor honors schemaLocation attribute. To get the URL for a given version of any schema use the namespace URI as a URL and visit this URL using your browser. An index of various versions for that schema would show up. Each of these entries links to the published schema for that version. For example, if you visit http://www.bea.com/ns/weblogic/weblogic-web-app you would find link to version 1.0 of this schema pointing to http://www.bea.com/ns/weblogic/weblogic-web-app/1.0/weblogic-web-app.xsd

In due course, the schemas would be migrated from BEA domain to Oracle domain. The namespace URIs themselves might be changed too, for branding and consistency purposes. But the pattern of namespace URIs would continue to be the same. Whenever these changes happen, they'll be duly documented.

(Picture licensed from Brian Marco under Creative Commons)