2008-08-22

How to use a deployment plan ?

So far, I've been working with several clients who have a strong need to override some values, according to the target environment when they are deploying their archive.

BEA/Oracle offers such a mechanism from WebLogic Server 9, which is called "Deployment Plan".

It is quite well exposed in the official documentation : http://edocs.bea.com/wls/docs91/deployment/plan.html

You also may take a look at Understanding Deployment Plan Contents

 

How does it look like and how does it work ?

Here is a sample of a plan.xml :

<?xml version='1.0' encoding='UTF-8'?>
<deployment-plan
    xmlns=http://www.bea.com/ns/weblogic/deployment-plan
    xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
    xsi:schemaLocation="http://www.bea.com/ns/weblogic/deployment-plan
http://www.bea.com/ns/weblogic/deployment-plan/1.0/deployment-plan.xsd">
    <application-name>sample</application-name>
    <variable-definition>
        <variable>
            <name>MyNewSessionTimeout</name>
            <value>600</value>
        </variable>

    </variable-definition>

    <module-override>
        <module-name>DatasourceCaller.war</module-name>
        <module-type>war</module-type> 
        <module-descriptor external="true">
            <root-element>weblogic-web-app</root-element>
            <uri>WEB-INF/weblogic.xml</uri>
            <variable-assignment>
                <name>MyNewSessionTimeout</name>
                <xpath>/weblogic-web-app/session-descriptor/timeout-secs</xpath>
            </variable-assignment
>
        </module-descriptor>

        <module-descriptor external="false">
            <root-element>web-app</root-element>
            <uri>WEB-INF/web.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>
    <config-root>D:\BEA_ROOT\applications\sample\plan</config-root>
</deployment-plan>



The mechanism works by first defining a variable with a value (blue section) and then assigning it to an application (purple section).


As you can see XPath is used to qualify the path of the attribute to update. For instance, here it's "/weblogic-web-app/session-descriptor/timeout-secs".


You will notice that the XPath indicated is simply the path to that attribute in the following weblogic.xml deployment descriptor.

<?xml version="1.0" encoding="UTF-8"?>
    <weblogic-web-app
        xmlns=http://www.bea.com/ns/weblogic/90
        xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
        xsi:schemaLocation="http://www.bea.com/ns/weblogic/90 http://www.bea.com/ns/weblogic/920/weblogic-web-app.xsd">
        <session-descriptor>
            <timeout-secs>600</timeout-secs>
        </session-descriptor>

    </weblogic-web-app>



How do I know if there's already a plan linked to my application ?


Well, that part is easy to answer. Either you have :



image


Or :

image


See the difference ? :)


 


How do I create a deployment plan ?


Console




When you go on the console, on your deployment, you will see a tab called "Configuration > General".


Here you will be able to see some tuning values defined for your application.


If you did not configure your deployment descriptor accordingly, some default values will be displayed like :



image


 


Modifying these values will lead to the creation of a deployment plan.



image


Save you plan where you want to and you're done.


 



weblogic.PlanGenerator


BEA offers a tool dedicated to plan creation. As every tool, you first have to set your classpath first to be able to use it.


(This can be done by executing the script setWLSEnv). Here is an example of how it works. 



java weblogic.PlanGenerator


-all // option exporting all the editable options


-plan samplePlan.xml // the name of the plan to be generated


myApp


Full Ex : java weblogic.PlanGenerator -all -plan mySamplePlan.xml D:\BEA_ROOT\user_projects\applications\sample\sample.war 


 


Then you should normally have the following message as a result : 



Generating plan for application D:\BEA_ROOT\user_projects\applications\sample\sample.war


Export option is: all Exporting properties...


Saving plan to C:\Documents and Settings\mbutton\samplePlan.xml...


<14 avr. 2008 15 h 07 CEST> <Info> <J2EE Deployment SPI> <BEA-260086>


<The descriptor information at D:\Temp\[...]\weblogic.xml was saved to configuration area.>


<14 avr. 2008 15 h 07 CEST> <Info> <J2EE Deployment SPI> <BEA-260072>


<Saved configuration for application, sample.war>


 



To better understand the different categories of options available, read the documentation : Understanding Deployment Property Classifications


Personnaly, I encountered some problems using it.


Actually, some attributes are considered as non-editable when generating the plan, but if you manually override them, it works ...


Then, I would advise you to use this tool for a first shot and then modify it with your values.


(So far, all the values I changed through a plan were successfully updated).


 


Hand :)


It's a xml file, then you may write it from the beginning. I wouldn't advise you to do so because the chances of getting an error are much higher.


But if you're really willing to do it yourself, take a look at http://www.bea.com/ns/weblogic/90/weblogic-deployment-plan.xsd, it should help.


 


How do I link it to my deployment ?


Console


Unfortunately, through the console, when you deploy a new application, you cannot reference the deployment plan directly.


You will have to install your application and then update it. First, check the application then "Update" button :



image



Then change the plan path to reflect the actual location of your deployment plan and update the whole stuff.



image


 


Or there is another way to take the plan into account, but as I said earlier it's not visible from the console.


You'll have to respect a certain directory structure to have your deployment plan automatically bound to your application.


I will advise you to follow the best practices described by BEA : Steps for Creating an Application Installation Directory.


To sum up, your directory should look like :


SampleApplication
----> V1
----> app
----> SampleApplication.war
----> plan
----> plan.xml
----> V2
----> app
----> SampleApplication.war
----> plan
----> plan.xml

 



And then when you will deploy the open directory V1 or V2, the sample application will be deployed as well as the associated deployment plan.


 


weblogic.Deployer


You may update your application and specify the plan to use : 



java weblogic.Deployer -username weblogic -password weblogic -adminurl t3://localhost:7001 -update-name SampleApplicationBis -plan SamplePlan.xml 


(If you're wondering why the action is 'update' and not 'redeploy', read Understanding Redeployment Behavior for Deployment Configuration Changes)


The result will be displayed like that : 



weblogic.Deployer invoked with options: -username weblogic -adminurl t3://localhost:7001 -update -name SampleApplicationBis -plan SamplePlan.xml
<21 aout 2008 08 h 55 CEST> <Info> <J2EE Deployment SPI> <BEA-260121> <Initiating update operation for application,


SampleApplicationBis [archive: null], to configured targets.>
Task 3 initiated: [Deployer:149026]update application SampleApplicationBis on AdminServer.
Task 3 completed: [Deployer:149026]update application SampleApplicationBis on AdminServer.
Target state: update completed on Server AdminServer
 


Or you may install your application for the very first time : 



java weblogic.Deployer -username weblogic -password weblogic -adminurl t3://localhost:7001 -deploy -name SampleApplicationBis -plan SamplePlan.xml  


You will have a similar result than when updating (see above). 


WLST


It is of course possible to use WLST to deploy the application and the deployment plan or simply to update an application.


 


How can I check that my values have been taken into account ?


Console


Through the console, simply go to the "Configuration > General" tab of your deployment and check the new values


(if they belong to this section, else you will have to check thanks to WLST, described later in this section).



image 


WLST


The console is fine, but you can't see all. Nor can you with WLST :) But it's much more complete.


For that, just connect to the server on which the application is deployed (if you're not in development mode, it is normally NOT your administration server).


For instance, let's assume we've got a admin server listening on port 7001 and a managed server listening on 7011.


You app is deployed on the managed server, then you will type : 



connect ('weblogic', 'weblogic', 't3://localhost:7011') // Using the same credentials than the admin


serverRuntime() // Allows you to switch to the runtime tree


cd ('ApplicationRuntimes') // You always will have to go in that directory


cd ('ApplicationSampleBis') // This is the name of our application (you may have to go in a directory representing the EAR prior to reach the WAR)


cd('ComponentRuntimes') // You always will have to go in that directory


cd ('AdminServer_/sample') // Change to the directory whose name is composed of your server name and the context root of you app (type ls() if you want to be sure)


ls()


 


And the result will show you the runtime values. For instance, before :




image


 


And after :



image


 


Troubleshooting


"My values are not updated : what am I missing ?" Well, I won't pretend I'm going to solve your problem, but let's try :)


First, check that your plan is defined in the console as stated in the "How do I know if there's already a plan linked to my application" section.


If it's the case, check that the name you defined in your plan, for the module is correct. WLST will give you the component name (in serverRuntime tree) :

image



And it must be the same in your plan : 



<module-override>
<module-name>Extract</module-name>
<module-type>war</module-type> 


And last but not least, the values you want to override MUST have been defined in your deployment descriptor. It's an override, not a definition. 


Links


If you're French, I would advise you to go the excellent post of my colleague Benoit Moussaud : http://blog.xebia.fr/2008/04/17/les-plans-de-deploiement-weblogic/






8 comments:

Anonymous said...

Hi. Great great article, although it did not help me solve my issue. I am running into a deployment error in my application where if i install the application from the console using the .beabuild.txt document in my .metadata\.plugins\org.eclipse.core.resources\.projects\PROJECT_NAME\beadep\DOMAIN_NAME\PROJECT_EAR
folder, it installs and deploys fine. If i add the same project to my Servers view in Weblogic Workshopand try to publish from there, the deployment fails. I've looked everywhere for a solution and i pinned it down to this by comparing logfiles for both a correct and incorrect deployment:

Just before reading and parsing my web app web.xml file, there seems to be a request issued to undeploy the same EAR. The log goes like this:

BEA-423120 WEB-INF/client-classifications.xml file not found at uri [my-portal-web.war]. Classifications functionality not enabled.>

BEA-149038 Initiating Task for my-portal-ear : [Deployer:149026]remove application my-portal-ear on AdminServer.>

I then get the lines

BEA-149059 Module my-portal-web of application my-portal-ear is transitioning from STATE_ADMIN to STATE_NEW on server AdminServer.

000000 deregister: my-portal-ear/my-portal-web.war#com.bea.wlw.runtime.descriptor.urltemplate.config

BEA-403301 Auto lease timer is still running for lease PortalFrameworkDotFileLease&my-portal-ear&my-portal-web.war.

BEA-420666 [my-portal-web] Undeploying the portlet application in webapp [/WEB-INF/portlet.xml].

From there the web.xml and ejb-jar files are parsed and after that the Spring sessionFactory object is destroyed as well my ServletConfiguration and i get a ERROR DUMP and deployment fails. Sometimes it attributes it to a deployment timeout.

The correct deployment lines go like:

BEA-423120>WEB-INF/client-classifications.xml file not found at uri [my-portal-web.war]. Classifications functionality not enabled.>

BEA-403301 Auto lease timer is still running for lease PortalFrameworkDotFileLease&my-portal-ear&my-portal-web.war.

and the same parsing goes on and nothing gets destroyed and the application deploys fine.

My reasoning is this, and let me know if i am wrong:

Deploying whether from the console or from workshop must be done according to a deployment plan. Even though it is not configurable it must be first created and stored somewhere. So if i can find where the file is located and modify it i should be able to remove the reference to undeploying an application that is not there and causing my build to fail.

If you have any insight on the deployment process from Workshoplike where temprary configuration files are stored, that will help me solve this i would be ultimately grateful. Documentation is sparse or non existing on the topi9c.

sync said...

Thanks for the article. I have browse the doc on deployment but could find a solution for my issue.

Is there by any chance we could customize the JRE being used per application (or domain) in deployment plan, or using other method?

i.e., WLS 10.3 bundled with JDK 1.6 and would like to use JDK 1.5 for a specific web app.

Thanks.

Maxence Button said...

Hi !

For anonymous, your problem was answered via email.
(didn't get any feedback, thus I guess you're not stuck anymore)

For sync, well, I'm afraid you won't be able to do that. WLS 10.3 is compatible with JDK1.5 client but the server has to run with a JDK1.6 (but it was sensed to be compatible with both in the early specification draft).

What you should do is have both WLS10.3 and WLS10.1 installed and deploy all your application in a 10.3 domain. For the specific application that requires (by the way, are you sure about that ?) a JDK1.5, deploy it on a 10.1 domain.

Hope it helps !

GSB said...

There it is, in a previous comment, the mysterious BEA-403301 info message about some AutoTimer. I receive this in my Weblogic Portal 10.2 portal deployment and can not find a way to suppress it. More importantly, I'm not sure what it means (although my application deploys ok). Any info on that is greatly appreciated.

Anonymous said...

Hi,

very helpful document. I was able to use it for overriding some values in weblogic.xml. However, I am trying to update the virtual-directory-mapping using deployment plan but m unsuccessful. Any help would be appreciated.

Varun Rajan said...

Hello Maxence,

The article has been a lot of help for me. I would like to know if we can use Deployment Plan for automating the datasource configuration in different Environments. For ex : I want to be able to change the username, pwd and url for the datasources while migrating to different environments

Jim said...

Hi Maxence,

Can we use a deployment plan to set an application use a work manager with constraints attached to it??

I've already created the work manager & constraints thru the admin console.

Now i want the application to use it. how do i set the dispatch policy in the plan?

Khue said...

Hi Maxence. Thanks for your article.
I also want to know that can we override the virtual-directory-mapping.

If it is possible, in the case that I have two virtual-directory-mapping definition, how the variable assignment distingquish between the two?

Thanks a lot.