Defining the context root of a web application in Oracle WebLogic server

Defining the context root in deployment descriptors

According with JavaEE 5 specification, a Web application deployed as part of an Enterprise Application (EAR) has the context root defined as following:

  • specified in the standard deployment descriptor (DD) META-INF/application.xml
<?xml version = '1.0' encoding = 'windows-1252'?>
<application 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_5.xsd"
             version="5"
             xmlns="http://java.sun.com/xml/ns/javaee">
    <display-name>WebappWithCtxRootApp</display-name>
    <module>
        <web>
            <web-uri>WebappWithCtxRoot.war</web-uri>
            <context-root>InitialCtxRoot</context-root>
        </web>
    </module>
</application>

  • if context-root element contains an empty string, the context root of the web module is the name of the file relative to the root of the application package, but with the .war extension removed
    <module>
        <web>
            <web-uri>WebappWithCtxRoot.war</web-uri>
            <context-root></context-root> <!-- ==>  WebappWithCtxRoot -->
        </web>
    </module>

Note: The empty string is allowed only for one web module per EAR. All the other web modules must have non-empty and distinct names for their context root definitions.

  • if the module is not specified in the application.xml or the DD is missing altogether, then the context root is the name of the file relative to the root of the application package, but with the .war extension removed (as in the empty-string case)

Note: The web modules will be assigned a complete name in the namespace of the web server at deployment time. This is why the context root name must be distinct among the others (including the empty string one) . Also, it cannot be changed after deployment, unless the application is updated/redeployed.

For more information on this, read JavaEE 5 specification, sections:
-  EE.8.3.1 – Assembling a Java EE Application
-  EE.8.4.2 – Deploying a Java EE Application
  • In addition to the above, Oracle Weblogic server allows another way of specifying the context root (in case the application.xml file is missing), by using its specific deployment descriptor  for web apps - weblogic.xml
<?xml version = '1.0' encoding = 'windows-1252'?>
<weblogic-web-app
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-web-app
            http://www.bea.com/ns/weblogic/weblogic-web-app/1.0/weblogic-web-app.xsd"
        xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app">
    <context-root>InitialCtxRoot</context-root>
</weblogic-web-app>

Defining the context root in deployment plan

Deploying the same application to different customers typically requires to change some of the configuration to adjust it to the target environment (IP addresses, port numbers, context roots etc). In case of context root, this would mean managing several versions of the application.xml or weblogic.xml files. This is not very convenient since these files are seen as part of the application itself and very likley maintained into a source control system.

The alternative would be to use a Deployment Plan (DP) – feature of Weblogic server that allows to define variables for the configuration parts we know are subject to change, and use them to update the configuration at deployment time.

Note : The current version of Weblogic server does not allow the change of the context root element in the application.xml file. Therefore, the application.xml DD must NOT be present within the EAR, relying on the weblogic.xml DD to define the context root (see Oracle Fusion Middleware 11g – Deploying Applications to Oracle WebLogic Server – section 4: “Configuring Applications for Production Deployment”)

Steps:

1. Create a variable in Deployment Plan file

<variable-definition>
    <variable>
        <name>WebAppCtxRootVar</name>
        <value>CustomCtxRoot</value>
    </variable>
<variable-definition>

2. Assign the variable to the context-root element within weblogic.xml

<module-override>
    <module-name>WebappWithCtxRoot.war</module-name>
    <module-type>war</module-type>
    <module-descriptor external="false">
        <root-element>weblogic-web-app</root-element>
        <uri>WEB-INF/weblogic.xml</uri>
        <variable-assignment>
            <name>WebAppCtxRootVar</name>
            <xpath>/weblogic-web-app/context-root</xpath>
            <operation>replace</operation>
        </variable-assignment>
    </module-descriptor>
</module-override>

3. Remove the META-INF/application.xml DD from the EAR

 [oracle@localhost upload]$ zip -d WebappWithCtxRootApp.ear META-INF/application.xml
deleting: META-INF/application.xml

[oracle@localhost upload]$ unzip -l WebappWithCtxRootApp.ear
Archive:  WebappWithCtxRootApp.ear
 Length     Date   Time    Name
 --------    ----   ----    ----
      344  01-05-11 16:47   META-INF/weblogic-application.xml
     1937  01-05-11 16:47   WebappWithCtxRoot.war
 --------                   -------
 2281                   2 files

4. Deploy the application specifying the DP

[oracle@localhost upload]$ java weblogic.Deployer \
>                               -adminurl t3://localhost:7001 \
>                               -username weblogic \
>                               -deploy WebappWithCtxRootApp.ear \
>                               -name WebappWithCtxRootApp \
>                               -plan Plan.xml

5. Run the app

5 Comments.

  1. Weblogic Deployment Plan « Lukasz's Blog - pingback on 2011/02/16 at 09:43
  2. Richard van den Berg

    Thanks for this clear article with useful background information.

    I only get this to work if I upload the war with plan.

    But if i place that war into ear, the deployment plan works except for the context-root.

    • Richard van den Berg

      The next information gives a clue why changing context-root with plan is not working in ear.

      Note:
      Oracle does not support using a deployment plan to change the context-root in an application.xml file. However, if an application is deployed as a library, you can either change the context-root through an weblogic-application.xml file or use the deployment plan to change the context-root in an weblogic-application.xml file.

      So i deploy now during development my war directory with plan to get different context root as testing ear deployment.
      (TIP: use fast-swap=true)

    • If you remove the application.xml from the ear, as in the blog article, it will work.

  3. Hi,

    U have a nice site.This site made me clear all my issues of defining the context root in deployment descriptor.Thanks a lot.

    Oracle Managed Services.

Trackbacks and Pingbacks: