To facilitate the creation of deployment plans there is a new portlet now available. The Plan Creator wizard available from the Geronimo Administration Console makes deployment easier by walking you through a sequence of steps to auto-generate the geronimo-web.xml for a given WAR file.
The wizard work by looking into the references declared in the web.xml as well as what is now defined withing the code itself via annotations. Depending on the type of application the Plan Creator wizard will present a series of pages requesting specific information to resolve the references and dependencies. The wizard also offers default values which work for most of the configurations.
Depending on the type of application you are deploying, you may be presented with six separate pages to address the application's specific configuration. These pages are (in sequence):
- Load WAR
- Initial configuration
- Resolve references
- Security
- Resolve module dependencies
- Review plan and deploy
This document offers a series of different sample application so you can have a better understanding of how this wizard works.
Supported features
The Plan Creator wizard will help you generate the appropriate deployment plan for the application you are deploying. The wizard currently works for web apps and supports the following features.
- References: EJB, EJB Local, JDBC Connection Pool, JMS Connection Factory, JMS Destination, JavaMail Session & Web Service references declared in the web-apps are auto discovered and users are asked to resolve them by listing Available Resources in the server environment to which they can be linked.
- Above type of references declared inside the Java classes through Annotations are also auto discovered.
- Simplified configuration of Security.
The following sections provide sample applications with different features so you can better appreciate the wizard behavior.
Sample with annotations
There are four simple applications attached to give you a better idea of how the plan creator wizard would work when deploying web applications.
JDBC access
This sample is a very simple database access application that uses annotations. For this example we have created a sample BankDB database on the embedded Derby as well as a database connection pool. Although we will not be covering in this section how to create a database or a connection pool we still provide in the #Attachments section some SQL sample to generate the required sample database.
The Annotations-TestJDBCAccess.zip file provides a BankDB.sql, WebAppJDBCAccessAnnotations.war which is the WAR we will be deploying and a sample of the generated deployment plan WebAppJDBCAccessAnnotations_generatedPlan.xml. Download and extract the zip file to a directory of your convenience.
WebAppJDBCAccessAnnotations.war includes a Servlet and a JSP. The following excerpt shows the annotation part the wizard has identified and will likely be prompting for additional information while deploying the application.
...
import javax.annotation.Resource;
...
/**
* Servlet implementation class for Servlet: ListCustomers
*
*/
public class ListCustomers extends javax.servlet.http.HttpServlet implements javax.servlet.Servlet {
@Resource(name = "jdbc/MyDataSource")
private DataSource dataSource;
...
With the server up and running access the Geronimo Administration Console with a web browser and click on Plan Creator on the left menu.
Browse to the WebAppJDBCAccessAnnotations.war you just extracted and click on Configure. In the resulting screen you will be configuring the web application identity. You may want to change the default proposed values however, for this example, we will be accepting the defaults. Click Next.
In the following screen, the wizard would have identified all WAR references that need to be resolved. The references listed on this screen are specific to this application. The JDBCRef column is showing the resource name defined in ListCustomers.java. See @Resource(name = "jdbc/MyDataSource") from the excerpt above.
As mentioned earlier, for this example we created a database connection pool we called BankDB_Pool. From the JDBC Pools pull-down menu you can now select the appropriate connection pool and click Next.
The following screen list all available modules and allows you specify the modules this WAR has dependencies on. This screen also provides a default selection, in this case the database connection pool will be already selected. Accept the default and click Next. For most scenarios the default values should be sufficient.
The final configuration page displays the generated deployment plan and allows you to make any additional editing. The following example shows the generated deployment plan.
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1">
<dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">
<dep:moduleId>
<dep:groupId>default</dep:groupId>
<dep:artifactId>WebAppJDBCAccessAnnotations</dep:artifactId>
<dep:version>1.0</dep:version>
<dep:type>war</dep:type>
</dep:moduleId>
<dep:dependencies>
<dep:dependency>
<dep:groupId>console.dbpool</dep:groupId>
<dep:artifactId>BankDB_Pool</dep:artifactId>
<dep:version>1.0</dep:version>
<dep:type>rar</dep:type>
</dep:dependency>
</dep:dependencies>
</dep:environment>
<context-root>WebAppJDBCAccessAnnotations</context-root>
<nam:resource-ref xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.2">
<nam:ref-name>jdbc/MyDataSource</nam:ref-name>
<nam:pattern>
<nam:groupId>console.dbpool</nam:groupId>
<nam:artifactId>BankDB_Pool</nam:artifactId>
<nam:version>1.0</nam:version>
<nam:name>BankDB_Pool</nam:name>
</nam:pattern>
</nam:resource-ref>
</web-app>
The last step is to actually deploy and start the application, click on Deploy WAR.
You should receive two confirmation messages stating the application was successfully deployed and successfully started. The Launch Web App link takes your browser directly to the application you just deployed based on the context root you defined earlier. Finish takes you to the Plan Creator portlet again to start deploying a new application.
EJB access
This sample is a simple web application that accesses a Session EJB. It requires a JAR to be deployed before you can deploy the web application. In the #Attachments section we have included all the files you need to test the deployment of this sample application.
The Annotations-TestEJBAccess.zip file provides the CurrencyConverterEJB.jar that needs to be deployed first, the WebAppEjbAccessAnnotations.war which is the WAR we will be deploying and a sample of the generated deployment plan WebAppEjbAccessAnnotations_generatedPlan.xml. Download and extract the zip file to a directory of your convenience.
With the server up and running access the Geronimo Administration Console with a web browser and click on Deploy New on the left menu. We will now deploy the WAR prerequisite JAR file.
On the Archive: field browse to the CurrencyConverterEJB.jar file you just extracted and click "Install", this will install and start the JAR. You can verify the status of this JAR by clicking on EJB JARs link from the menu on the left. It should display something like this:
Component Name State default/CurrencyConverterEJB/1199743733609/jar running
WebAppEjbAccessAnnotations.war includes a Servlet and a JSP. The following excerpt shows the annotation part the wizard has identified and will likely be prompting for additional information while deploying the application.
...
public class ConverterHandler extends javax.servlet.http.HttpServlet implements
javax.servlet.Servlet {
@EJB(name = "ejb/Converter")
private Converter converter;
...
With the prerequisite JAR just installed click on Plan Creator on the left menu to proceed with the WAR installation. Browse to the WebAppEjbAccessAnnotations.war you just extracted and click on Configure. In the resulting screen you will be configuring the web application identity. You may want to change the default proposed values however, for this example, we will be accepting the defaults. Click Next.
In the following screen, the wizard would have identified all WAR references that need to be resolved. The references listed on this screen are specific to this application. The EJBRef column is showing the resource name defined in ConverterHandler.java. See @EJB(name = "ejb/Converter") from the excerpt above.
From the EJBs Deployed pull-down menu select the JAR you deployed earlier ConverterBean (default/CurrencyConverterEJB/1199743733609/jar) and click Next.
The following screen list all available modules and allows you specify additional modules this WAR has dependencies on. This screen also provides a default selection, in this case the EJB JAR you deployed previously will be already selected. Accept the default and click Next. For most scenarios the default values should be sufficient.
The final configuration page displays the generated deployment plan and allows you to make any additional editing. The following example shows the generated deployment plan.
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1">
<dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">
<dep:moduleId>
<dep:groupId>default</dep:groupId>
<dep:artifactId>WebAppEjbAccessAnnotations</dep:artifactId>
<dep:version>1.0</dep:version>
<dep:type>war</dep:type>
</dep:moduleId>
<dep:dependencies>
<dep:dependency>
<dep:groupId>default</dep:groupId>
<dep:artifactId>CurrencyConverterEJB</dep:artifactId>
<dep:version>1199743733609</dep:version>
<dep:type>jar</dep:type>
</dep:dependency>
</dep:dependencies>
</dep:environment>
<context-root>WebAppEjbAccessAnnotations</context-root>
<nam:ejb-ref xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.2">
<nam:ref-name>ejb/Converter</nam:ref-name>
<nam:pattern>
<nam:groupId>default</nam:groupId>
<nam:artifactId>CurrencyConverterEJB</nam:artifactId>
<nam:version>1199743733609</nam:version>
<nam:name>ConverterBean</nam:name>
</nam:pattern>
</nam:ejb-ref>
</web-app>
The last step is to actually deploy and start the application, click on Deploy WAR.
You should receive two confirmation messages stating the application was successfully deployed and successfully started. The Launch Web App link takes your browser directly to the application you just deployed based on the context root you defined earlier. Finish takes you to the Plan Creator portlet again to start deploying a new application.
JMS access
This is a simple web application that accesses a JMS Connection Factory and a JMS destination. Producer servlet sends 5 messages to a JMS queue and the Consumer servlet synchronously receives messages from the same queue.
The Annotations-TestJMSAccess.zip file provides the WebAppJMSAccessAnnotations.war which is the WAR we will be deploying and a sample of the generated deployment plan WebAppJMSAccessAnnotations_generatedPlan.xml. Download and extract the zip file to a directory of your convenience.
WebAppJMSAccessAnnotations.war includes the two Servlets mentioned above and a JSP. The following excerpts show the annotation part the wizard has identified and will likely be prompting for additional information while deploying the application.
...
/**
* Servlet implementation class for Servlet: ProducerServlet
*
*/
public class ProducerServlet extends javax.servlet.http.HttpServlet implements javax.servlet.Servlet {
@Resource(name="jms/TestConnectionFactory")
private ConnectionFactory connectionFactory;
@Resource(name="jms/TestQueue")
private Queue queue;
...
...
/**
* Servlet implementation class for Servlet: ConsumerServlet
*
*/
public class ConsumerServlet extends javax.servlet.http.HttpServlet implements javax.servlet.Servlet {
@Resource(name="jms/TestConnectionFactory")
private ConnectionFactory connectionFactory;
@Resource(name="jms/TestQueue")
private Queue queue;
...
With the server up and running access the Geronimo Administration Console with a web browser and click on Plan Creator on the left menu.
Browse to the WebAppJMSAccessAnnotations.war you just extracted and click on Configure. In the resulting screen you will be configuring the web application identity. You may want to change the default proposed values however, for this example, we will be accepting the defaults. Click Next.
In the following screen, the wizard would have identified all WAR references that need to be resolved. The references listed on this screen are specific to this application. The JDBCRef column is showing the resource name defined in ListCustomers.java. See @Resource(name = "jdbc/MyDataSource") from the excerpt above.
As mentioned earlier, for this example we created a database connection pool we called BankDB_Pool. From the JDBC Pools pull-down menu you can now select the appropriate connection pool and click Next.
The following screen list all available modules and allows you specify the modules this WAR has dependencies on. This screen also provides a default selection, in this case the database connection pool will be already selected. Accept the default and click Next. For most scenarios the default values should be sufficient.
The final configuration page displays the generated deployment plan and allows you to make any additional editing. The following example shows the generated deployment plan.
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.2">
<dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">
<dep:moduleId>
<dep:groupId>default</dep:groupId>
<dep:artifactId>WebAppJMSAccessAnnotations</dep:artifactId>
<dep:version>1.0</dep:version>
<dep:type>war</dep:type>
</dep:moduleId>
<dep:dependencies>
<dep:dependency>
<dep:groupId>org.apache.geronimo.configs</dep:groupId>
<dep:artifactId>activemq-ra</dep:artifactId>
<dep:version>2.0-SNAPSHOT</dep:version>
<dep:type>car</dep:type>
</dep:dependency>
</dep:dependencies>
</dep:environment>
<context-root>WebAppJMSAccessAnnotations</context-root>
<nam:resource-ref xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.2">
<nam:ref-name>jms/TestConnectionFactory</nam:ref-name>
<nam:pattern>
<nam:groupId>org.apache.geronimo.configs</nam:groupId>
<nam:artifactId>activemq-ra</nam:artifactId>
<nam:version>2.0-SNAPSHOT</nam:version>
<nam:name>DefaultActiveMQConnectionFactory</nam:name>
</nam:pattern>
</nam:resource-ref>
<nam:resource-env-ref xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.2">
<nam:ref-name>jms/TestQueue</nam:ref-name>
<nam:pattern>
<nam:groupId>org.apache.geronimo.configs</nam:groupId>
<nam:artifactId>activemq-ra</nam:artifactId>
<nam:version>2.0-SNAPSHOT</nam:version>
<nam:name>SendReceiveQueue</nam:name>
</nam:pattern>
</nam:resource-env-ref>
</web-app>
The last step is to actually deploy and start the application, click on Deploy WAR.
You should receive two confirmation messages stating the application was successfully deployed and successfully started. The Launch Web App link takes your browser directly to the application you just deployed based on the context root you defined earlier. Finish takes you to the Plan Creator portlet again to start deploying a new application.