Creating deployment plans
Deployment plans are part of the JSR-88 deployment standard, although not explicitly stated in this standard. A deployment plan is an XML document that defines a custom WebLogic Server deployment environment. This configuration can be used to override the specific settings defined into the application archive.
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 of 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 JEE application archive without proprietary deployment descriptors and put all of those proprietary deployment descriptor values outside of that archive.
There are several alternatives for creating a deployment plan: start by setting your environment to include the WLS classpath:
C:\wls1211_dev\user_projects\domains\base_domain\bin>setDomainEnv.cmd
Then, you can use the PlanGenerator utility to create a deployment plan for your application
java weblogic.PlanGenerator -all WLSDemo.ear Generating plan for application WLSDemo.ear Export option is: all Exporting properties... Saving plan to C:\wls1211_dev\user_projects\domains\base_domain\bin\plan.xml... <8-ago-2012 11.52.48 CEST> <Info> <J2EE Deployment SPI> <BEA-260072> <Saved configuration for application, WLSDemo.ear>
Let’s check the file plan.xml which contains all the application specific settings. We will not include the whole plan.xml file here which is quite verbose; however we will include as example, how to customize some parameters contained in it.
A deployment plan is an XML file which basically defines some variables using unique names and assigns the variables values to specific elements of the custom deployment descriptors. The specific XML elements are referenced using XPath expressions.
Example: customizing the Web application root context
Open the file plan.xml file and edit it with a text editor. Next, locate the following <variable> element:
<variable> <name>WeblogicWebApp_ContextRoots_xxxxxxxxxxxxxx</name> <value xsi:nil="true"></value> </variable>
Note that the xxxxxxxxxxxxxx will actually be an unique identifier created by the Plan Generator in order to define an unique name for the variable. In the following example, we will replace it with a meaningful name that will be referenced through the file.
Now edit the above snippet section, so that it looks like this:
<variable> <name>WeblogicWebApp_CustomContext</name> <value>/newcontext</value> </variable>
Futher down in the file, locate the <variable-assignment> element which points to “weblogic-web-app/context-root” XPath expression and change the variable name to : “WeblogicWebApp_CustomContext” so that it matches with your variable:
<variable-assignment> <name>WeblogicWebApp_CustomContext</name> <xpath>weblogic-web-app/context-root</xpath> <origin>planbased</origin> <operation>replace</operation> </variable-assignment>
Also notice, we have included an additional “replace” operation in it, which will obviously replace the default context with the new one (“/newcontext”).
Save the plan.xml file. What we just did is overriding the context-root element in the WebLogic Server web application deployment descriptor- weblogic.xml. The new context root is “newcontext”.
Fine, now switch to the administration console and choose to update the application from the Deployments menu.
Click the Change Path button associated with the Deployment plan path as shown:
Now select the radio button for the new plan.xml file and click Next. If necessary, use the hyperlinks next to the Current Location field to navigate to the <APP_HOME> directory.
In the next screen select the radio button “Redeploy this application using the following deployment files”. Then click Finish. Now your application should be accessible using the new web context (newcontext).
Example: customizing the JDBC modules
The first example we have covered is good starting point for creating some more customization. One real world example could be to provide a deployment plan which updates the information contained in a JDBC module that is part of your application. It is likely to happen that your application will be distributed in different environments (development/production/test) where different databases are used. For example:
<wls:resource-description>
<wls:res-ref-name>JDBCOracleModule</wls:res-ref-name>
<wls:jndi-name>jdbc/OracleModule</wls:jndi-name>
</wls:resource-description>In this example, if we were to change the JNDI name where the JDBC module is bound, we would need modifying the XML descriptors where the JNDI name is defined.
By using a deployment plan instead, you could simply modify the value of the JDBC resources in plan.xml and update the application accordingly. Let’s suppose we want to change the JNDI binding of a sample TestEJB when porting the application in production, by changing it from “jdbc/OracleModule” to “jdbc/ProductionOracleModule”.
Start by generating a plan.xml deployment plan using the PlanGenerator utility. Now open your plan.xml and set the value element for your data source in a variable:
<variable> <name>MyDataSource_binding</name> <value>jdbc/ProductionOracleModule</value> </variable>
The above variable name (“MyDataSource_binding”) needs to be referenced in a corresponding variable-assignment stanza which sets the correct JNDI binding for your resource:
<module-override>
<module-name>TestEJB.jar</module-name>
. . . . .
<uri>META-INF/weblogic-ejb-jar.xml</uri>
<variable-assignment>
<name>MyDataSource_binding</name>
<xpath>/weblogic-ejb-jar/weblogic-enterprise-bean/[ejb-name="TestEJB"]/resource-description/[res-ref-name="MyDataSource"]/jndi-name</xpath>
</variable-assignment>
</module-descriptor>
</module-override>What if the data source is referenced as well in Web applications, let’s say it’s injected in a Servlet? no worry! You can provide a module-override also for the Web module; in this case we will override the weblogic.xml:
<module-override>
<module-name>wls.war</module-name>
. . . .
<uri>WEB-INF/weblogic.xml</uri>
<variable-assignment>
<name>MyDataSource_binding</name>
<xpath>/weblogic-web-app/resource-description/[res-ref-name="jdbc/ ProductionOracleModule "]/res-ref-name</xpath>
<origin>planbased</origin>
</variable-assignment>
</module-descriptor>
</module-override>
Generating the deployment plan using the administration console
If you don’t feel like using the command line to generate the deployment plan, you can do this step using the administration console instead. Navigate to your application from the Deployments option:
Then click on your application and move to the Configuration tab. In the lower part of the screen you will be able to change the application settings such as the Context Root path. Change this value to a new context path and save.
Once you have modified some values of the configuration, the deployment plan assistant will kick in, asking you to save these changes in a deployment plan. All you have to do is providing a convenient location for the file (highly suggested to use the name plan.xml).
The last step will be customizing the plan.xml file, as we showed earlier and updating your application using that file.
This excerpt has been taken from the “Enterprise Application Servers Cookbook” which is a practical, easy to understand guide that discusses about the three major industry Application Servers in the Java EE market: Oracle Weblogic, JBoss EAP and IBM Websphere. Including 600 pages of handy recipes, this book promises to teach you all about the three application servers using an enjoyable style and including detailed comparison between them.
