11gR1 Update and a Deployment Plan Example for WebLogic Server

7-23-09 Update: I updated this post slightly overnight after I thought of a few additional comments, an easier approach and I took in feedback from a comment.

11gR1 Release

It is a very exciting time to be involved with Oracle Fusion Middleware.  First, there are many new features and capabilities in the recently released 11gR1 that I’m learning about in training this week.  My focus is mostly on WebLogic Server and surrounding technologies categorized in the Application Grid space and the SOA products.  Beyond the best-of-breed qualities in the stand-alone middleware products, there is an ever-increasing amount of synergy between Oracle’s other products, both middleware and elsewhere.  The number of products certified and making use of WebLogic Server is incredible.  This has high value for customers in the consolidation of skill-sets and infrastructure.  I am personally very impressed with the amount of innovation that has occurred in a little over a year since Oracle acquired BEA Systems, and I’m excited about what is coming in future releases.  My blog folder where I store ideas for future blog entries just keeps getting more and more backlogged as I come across things worth investigating and sharing.

Deployment Plan JSR-88 Example in WebLogic Server

The Forum Question

One of the ways I gauge the increasing interest in WebLogic Server is the increasing number of posts in the WebLogic Server - General forum on OTN.  Today was an especially busy day and someone inquired on a fairly straight-forward problem:

Can I change the context root of a web application without modifying the archive?

How can you do it?

Fortunately if you need to make minor configuration adjustments in application deployment descriptors (such as web.xml, weblogic.xml, application.xml, or weblogic-application.xml), but do not need to change any application code you can use a Deployment Plan (also known as JSR-88) to do this in WebLogic Server deployments.  I’m not going to go into great detail here, but the essential idea is that an xml file, usually called Plan.xml that is located outside the application archive, can be used to override or set undeclared values in the deployment descriptors that are embedded in an application archive.  See the image below.

Why would you ever need this?

There are many reasons why you may not want to modify an application archive, one of which is testing.  For example, if you have successfully completed testing for a particular version an application, it is desirable to keep the application archive unmodified between environments so you can have increased confidence that the application will behave the same in multiple environments as it is promoted.  Another reason might be portability.  You could have one generic J2EE or JEE application archive without proprietary deployment descriptors and put all of those proprietary deployment descriptor values outside of that archive.  I know that WebLogic Portal code used this feature at one time to change the verbosity of a log level that was set with a Servlet initialization paramter, so you could also use this to change configuration values at runtime provided those are in a supported deployment descriptor.

Several other WebLogic bloggers have addressed Deployment Plans, so before I write about how I addressed this particular forum question, just know that you can get a general overview and more detailed examples from the following posts:

A Simple Example

There is a context-root element in a web application module’s weblogic.xml file that specifies the context root of the application.  When building a web application with Oracle Enterprise Pack for Eclipse, the value is automatically set to the Web Application name.  Check out the WEB-INF/weblogic.xml from my Web Application named PlanWEB.

<?xml version="1.0" encoding="UTF-8"?>
<wls:weblogic-web-app xmlns:wls="http://xmlns.oracle.com/weblogic/weblogic-web-app" 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/web-app_2_5.xsd http://xmlns.oracle.com/weblogic/weblogic-web-app http://xmlns.oracle.com/weblogic/weblogic-web-app/1.0/weblogic-web-app.xsd">
    <wls:weblogic-version>10.3.1</wls:weblogic-version>
    <wls:context-root>PlanWEB</wls:context-root>
</wls:weblogic-web-app>

I have confirmed that my application is deployed and listening at the /PlanWEB context root on my server.  How you deploy it, weblogic.Deployer, WLST, or the console is up to you.  Now lets say I want to change the context root to /FooWEB at runtime, even though the weblogic.xml file in the application archive will have PlanWEB listed in the deployment descriptor.

Option 1 – The Console – The easy GUI driven way

Browse the deployment, specifically to the web module of the context root you want to change.  Here’s a shot of my Deployments page after I have expanded the EAR to see it’s modules.

Home –> Deployments –> PlanEAR

console1

Click on PlanWEB, then click the configuration tab and look at the bottom of that page.  You’ll see the current context root, but not editable (depending on your console preferences it may already be editable).

contextRoot


  • Lock and edit the console if you have not already and put in a new value like “FooWEB” and click the save button.
  • The next page should prompt you for the location where the console should write the plan.xml file on the file system.  Choose whatever location makes sense, but it probably makes sense to put it somewhere in the domain directory structure or some other standard or convention you come up with.
  • Now activate the session.  The context root should now be /FooWEB and the configuration tab of the console show now also reflect that.

FooWEB

Here is my plan.xml that the WebLogic Server Console generated for me.

<?xml version='1.0' encoding='UTF-8'?>
<deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/weblogic/deployment-plan http://xmlns.oracle.com/weblogic/deployment-plan/1.0/deployment-plan.xsd">
  <application-name>foo</application-name>
  <variable-definition>
    <variable>
      <name>WeblogicWebApp_ContextRoots_12483492503430</name>
      <value>"FooWEB"</value>
    </variable>
  </variable-definition>
  <module-override>
    <module-name>PlanEAR.ear</module-name>
    <module-type>ear</module-type>
    <module-descriptor external="false">
      <root-element>weblogic-application</root-element>
      <uri>META-INF/weblogic-application.xml</uri>
    </module-descriptor>
    <module-descriptor external="false">
      <root-element>application</root-element>
      <uri>META-INF/application.xml</uri>
    </module-descriptor>
    <module-descriptor external="true">
      <root-element>wldf-resource</root-element>
      <uri>META-INF/weblogic-diagnostics.xml</uri>
    </module-descriptor>
  </module-override>
  <module-override>
    <module-name>PlanWEB.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>WeblogicWebApp_ContextRoots_12483492503430</name>
        <xpath>/weblogic-web-app/context-root</xpath>
        <operation>replace</operation>
      </variable-assignment>
    </module-descriptor>
    <module-descriptor external="false">
      <root-element>web-app</root-element>
      <uri>WEB-INF/web.xml</uri>
    </module-descriptor>
  </module-override>
  <config-root>C:\temp\foo\plan</config-root>
</deployment-plan>

Option 2 – weblogic.PlanGenerator – a more manual approach that could be used for automation

Here are the steps for creating the deployment plan yourself with weblogic.PlanGenerator.


  • Export the EAR file to a directory – my enterprise archive name is PlanEAR.ear
  • Go to your domain's bin dir with a shell and call setDomainEnv
  • Call a command like this from the dir where the EAR is with the configured shell:

java weblogic.PlanGenerator -all -plan Plan.xml PlanEAR.ear


  • That should generate a Plan.xml file in that directory with a bunch of stubs for values you could change at runtime in the Plan.xml file.  
  • Change the value of the variable for the context root.  Note that the variable name is auto-generated, but it still yields a clue by the variable name prefix.

Original:

<variable>
<name>WeblogicWebApp_ContextRoots_12482790756401</name>
<value xsi:nil="true"></value>
</variable>

New:

<variable>
<name>WeblogicWebApp_ContextRoots_12482790756401</name>
<value>FooWEB</value>
</variable>


  • Note that I did not use quotes for FooWEB whereas the console approach did use them.  Either way seemed to work just fine.
  • In order to override the context root we need to do a replace operation in the variable assignment since the element already exists in the archive. Edit Plan.xml again, this time modifying the relevant variable assignment section of the Plan.xml.  Note, if the weblogic.xml did not already have the context-root explicitly listed as an xml element, then the original section could have been used.

Original:

<variable-assignment> 
<name>WeblogicWebApp_ContextRoots_12482790756401</name> 
<xpath>/weblogic-web-app/context-root</xpath>
</variable-assignment>

New:

<variable-assignment> 
<name>WeblogicWebApp_ContextRoots_12482790756401</name> 
<xpath>/weblogic-web-app/context-root</xpath>
<operation>replace</operation> 
</variable-assignment>

Now we can use the weblogic.Deployer command for a redeployment with this new deployment plan Plan.xml and the EAR.  We also could have used WLST.

java weblogic.Deployer -adminurl t3://localhost:7001 -user weblogic -password welcome1 -redeploy -name PlanEAR -source PlanEAR.ear -targets AdminServer -plan Plan.xml

After the command completes, I can now access the application at http://locahost:7001/FooWEB/.


Special thanks to fellow bloggers Max, Edwin, and Benoit for their entries related to this topic.  Cheers.

Comments:

Deployment Plan in Action (Screencast) English version: http://bit.ly/SbQPx French version: http://blog.xebia.fr/2008/04/17/les-plans-de-deploiement-weblogic/

Posted by Benoit Moussaud on July 22, 2009 at 02:26 PM PDT #

Thanks for providing good article. But is this applicable for weblogic 9.2, since you are using weblogic 10?

Posted by Suharman on August 30, 2009 at 08:35 PM PDT #

Yes, WLS 9.2 has deployment plan support as well. I'm not sure if the console has the same features for automatically creating plan.xml for you based on a web form, but certainly you can use deployment plan with WLS 9.2 as this MedRec link illustrates from the 9.2 documentation. http://download.oracle.com/docs/cd/E13222_01/wls/docs92/medrec_tutorials/redeploy.html Thanks, James

Posted by james.bayer on August 30, 2009 at 08:56 PM PDT #

Is it possible to update the plan.xml in an automated way ( ie. Are there any weblogic api's that can be used in the command-line) to update it so the archive can be ported to various environments without editing the xml file manually ? Thanks, Ron

Posted by Ron Karim on November 30, 2009 at 12:08 AM PST #

Ron, I am not aware of any specialized plan.xml update tooling. Most likely this is because it's simply XML. So it should be extremely trivial to use any XML tooling / scripting functionality to automaically parse and edit plan.xml files that is xml aware. I could envision shipping a file with default values like FOO_URL_REPLACE_ME that were edited by a script before deployment. Thanks, James

Posted by James Bayer on November 30, 2009 at 03:23 AM PST #

Hi James, Thanks for such a great article! Do you know if there is a way to add library-ref elements into weblogic-application.xml? Thanks!

Posted by Rodolfo on September 01, 2010 at 04:13 AM PDT #

Sorry for the delay Rodolfo. I'm not sure about an EAR, but this came up in another email from support from a Rodolfo (which I assume is you?). I tried it for a WAR with weblogic.xml and it works. I use two variable assignments that use xpath like this: /weblogic-web-app/library-ref/library-name d:\temp>java weblogic.appmerge -output merged.war -plan d:\temp\plan.xml -librarydir d:\Oracle\fmw11gr1ps2\wlserver_10.3\common\deployable-libraries LibraryRefsWeb.war Thanks, James

Posted by james.bayer on September 13, 2010 at 02:44 PM PDT #

Post a Comment:
Comments are closed for this entry.
About

James Bayer Image
I was formerly a Product Manager on the WebLogic Server team based out of Oracle HQ. You can find my new blog at http://iamjambay.com.
Follow Me on Twitter
Oracle WebLogic

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today