web-fragment.xml « Miles to go …

September 4, 2009

TOTD #101: Applying Servlet 3.0/Java EE 6 “web-fragment.xml” to Lift – Deploy on GlassFish v3

Filed under: frameworks, glassfish, javaee, totd — Tags: javaee6, servlet3, v3, web-fragment.xml — arungupta @ 3:00 am

TOTD #100 explained how to deploy Lift framework applications on GlassFish v3. As explained in TOTD #91, Java EE 6 defines how the framework configuration deployment descriptor can be defined in “META-INF/web-fragment.xml” in the JAR file of the framework instead of mixing it with "WEB-INF/web.xml" which is intended for application deployment descriptor aspects.

This Tip Of The Day (TOTD) explains how to leverage ”web-fragment.xml” to deploy a Lift application on a Java EE 6 compliant container. The original "lift-*.jar" files are untouched and instead a new JAR file is included that contains only the framework configuration deployment descriptor.

The generated "web.xml" from TOTD #100 looks like:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
<filter>
 <filter-name>LiftFilter</filter-name>
 <display-name>Lift Filter</display-name>
 <description>The Filter that intercepts lift calls</description>
 <filter-class>net.liftweb.http.LiftFilter</filter-class>
</filter>

<filter-mapping>
 <filter-name>LiftFilter</filter-name>
 <url-pattern>/*</url-pattern>
</filter-mapping>

</web-app>

The deployment descriptor defines a Servlet Filter (LiftFilter) that registers the Lift framework with the Web container. And then it defines a URL mapping to "/*". All of this information is required by the Lift framework for request dispatching. And so that makes this fragment suitable for "web-fragment.xml".

Here are simple steps to make this change:

Remove “src/main/webapp/WEB-INF/web.xml” because no application specific deployment descriptors are required.

Include “lift-web-fragment.jar” in the “WEB-INF/lib” of your application by adding the following fragment in your “pom.xml”:

<dependencies>

. . .

  <!– web-fragment –>
  <dependency>
    <groupId>org.glassfish.extras</groupId>
    <artifactId>lift-web-fragment</artifactId>
    <version>1.0</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

. . .

<repositories>
  <repository>
    <id>maven2-repository.dev.java.net</id>
    <name>Java.net Repository for Maven</name>
    <url>http://download.java.net/maven/2/</url>
  </repository>
</repositories>

This file contains only “META-INF/web-fragment.xml” with the following content:

<web-fragment>
 <filter>
 <filter-name>LiftFilter</filter-name>
 <display-name>Lift Filter</display-name>
 <description>The Filter that intercepts lift calls</description>
 <filter-class>net.liftweb.http.LiftFilter</filter-class>
 </filter>

 <filter-mapping>
 <filter-name>LiftFilter</filter-name>
 <url-pattern>/*</url-pattern>
 </filter-mapping>
</web-fragment>

Create the WAR file without “web.xml” by editing “pom.xml” and adding the following fragment:

<build>
   . . .
  <plugins>
    . . .
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <version>2.1-beta-1</version>
      <configuration>
        <failOnMissingWebXml>false</failOnMissingWebXml>
      </configuration>
    </plugin>
  </plugins>
</build>

That’s it, now now you can create a WAR file using “mvn package” and deploy this web application on GlassFish v3 latest promoted build (61 as of today) as explained in TOTD #100.

Technorati: totd glassfish v3 lift scala javaee6 servlet web-fragment

Share and Enjoy:

Comments (9)

August 11, 2009

TOTD #91: Applying Java EE 6 “web-fragment.xml” to Apache Wicket – Deploy on GlassFish v3

Filed under: glassfish, javaee, totd, wicket — Tags: javaee6, servlet3, v3, web-fragment.xml — arungupta @ 4:00 am

“Extensibility” is a major theme of Java EE 6. This theme enables seamless pluggability of other popular Web frameworks with Java EE 6.

Before Java EE 6, these frameworks have to rely upon registering servlet listeners/filters in “web.xml” or some other similar mechanism to register the framework with the Web container. Thus your application and framework deployment descriptors are mixed together. As an application developer you need to figure out the magical descriptors of the framework that will make this registration.

What if you are using multiple frameworks ? Then “web.xml” need to have multiple of those listeners/servlets. So your deployment descriptor becomes daunting and maintenance nightmare even before any application deployment artifacts are added.

Instead you should focus on your application descriptors and let the framework developer provide the descriptors along with their jar file so that the registration is indeed magical.

For that, the Servlet 3.0 specification introduces “web module deployment descriptor fragment” (aka “web-fragment.xml”). The spec defines it as:

A web fragment is a logical partitioning of the web app in such a way that the frameworks being used within the web app can define all the artifacts without asking devlopers to edit or add information in the web.xml.

Basically, the framework configuration deployment descriptor can now be defined in “META-INF/web-fragment.xml” in the JAR file of the framework. The Web container picks up and use the configuration for registering the framework. The spec clearly defines the rules around ordering, duplicates and other complexities.

TOTD #86 explained how to get started with Apache Wicket on GlassFish. This Tip Of The Day (TOTD) explains how to leverage ”web-fragment.xml” to deploy a Wicket application on GlassFish v3. The basic concepts are also discussed here.

For the “Hello World” app discussed in TOTD #86, the generated “web.xml” looks like:

<?xml version=”1.0″ encoding=”ISO-8859-1″?>
<web-app xmlns=”http://java.sun.com/xml/ns/j2ee”
         xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
         xsi:schemaLocation=”http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd”
         version=”2.4″>

<display-name>helloworld</display-name>

         <!–
              There are three means to configure Wickets configuration mode and they are
              tested in the order given.
              1) A system property: -Dwicket.configuration
              2) servlet specific <init-param>
              3) context specific <context-param>
              The value might be either “development” (reloading when templates change)
              or “deployment”. If no configuration is found, “development” is the default.
        –>

        <filter>
                <filter-name>wicket.helloworld</filter-name>
                <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
                <init-param>
                        <param-name>applicationClassName</param-name>
                        <param-value>org.glassfish.samples.WicketApplication</param-value>
                </init-param>
        </filter>

<filter-mapping>
<filter-name>wicket.helloworld</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

</web-app>

This deployment descriptor defines a Servlet Filter (wicket.helloworld) that registers the Wicket framework with the Web container. The filter specifies an initialization parameter that specifies the class name of the Wicket application to be loaded. And it also contains some other information that is also relevant to the framework. None of this application is either required or specified by the application. And so that makes this fragment a suitable candidate for “web-fragment.xml”.

Here are the simple steps to make this change:

Remove “src/main/webapp/WEB-INF/web.xml” because no application specific deployment descriptors are required.

Include “wicket-quickstart-web-fragment.jar” in the “WEB-INF/lib” directory of your application by adding the following fragment in your “pom.xml”:

. . .
        <!– web-fragment –>
        <dependency>
            <groupId>org.glassfish.extras</groupId>
            <artifactId>wicket-quickstart-web-fragment</artifactId>
            <version>1.0</version>
            <scope>runtime</scope>
        </dependency>
    </dependencies>

. . .

    <repositories>
        <repository>
            <id>maven2-repository.dev.java.net</id>
            <name>Java.net Repository for Maven</name>
         &nbsp
; <url>http://download.java.net/maven/2/</url>
        </repository>
    </repositories>

This file contains only “META-INF/web-fragment.xml” with the following content:

<web-fragment>
        <filter>
                <filter-name>wicket.helloworld</filter-name>
                <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
                <init-param>
                        <param-name>applicationClassName</param-name>
                        <param-value>org.glassfish.samples.WicketApplication</param-value>
                </init-param>
        </filter>

        <filter-mapping>
                <filter-name>wicket.helloworld</filter-name>
                <url-pattern>/*</url-pattern>
        </filter-mapping>
</web-fragment>

Create the WAR file without “web.xml” by editing “pom.xml” and adding the following fragment:

<plugins>
. . .
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.1-beta-1</version>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                </configuration>
            </plugin>
. . .
</plugins>

That’s it, now you can create a WAR file using “mvn package” and deploy this web application on GlassFish v3 latest promoted build (58 as of today) as explained in TOTD #86.

The updated WAR file structure looks like:

helloworld-1.0-SNAPSHOT
helloworld-1.0-SNAPSHOT/META-INF
helloworld-1.0-SNAPSHOT/WEB-INF
helloworld-1.0-SNAPSHOT/WEB-INF/classes
helloworld-1.0-SNAPSHOT/WEB-INF/classes/log4j.properties
helloworld-1.0-SNAPSHOT/WEB-INF/classes/org
helloworld-1.0-SNAPSHOT/WEB-INF/classes/org/glassfish
helloworld-1.0-SNAPSHOT/WEB-INF/classes/org/glassfish/samples
helloworld-1.0-SNAPSHOT/WEB-INF/classes/org/glassfish/samples/HomePage.class
helloworld-1.0-SNAPSHOT/WEB-INF/classes/org/glassfish/samples/HomePage.html
helloworld-1.0-SNAPSHOT/WEB-INF/classes/org/glassfish/samples/WicketApplication.class
helloworld-1.0-SNAPSHOT/WEB-INF/lib
helloworld-1.0-SNAPSHOT/WEB-INF/lib/log4j-1.2.14.jar
helloworld-1.0-SNAPSHOT/WEB-INF/lib/slf4j-api-1.4.2.jar
helloworld-1.0-SNAPSHOT/WEB-INF/lib/slf4j-log4j12-1.4.2.jar
helloworld-1.0-SNAPSHOT/WEB-INF/lib/wicket-1.4.0.jar
helloworld-1.0-SNAPSHOT/WEB-INF/lib/wicket-quickstart-web-fragment-1.0.jar

Notice, there is no “web.xml” and the additional “wicket-quickstart-web-fragment-1.0.jar” and everything works as is!

It would be nice if the next version of wicket-*.jar can include “META-INF/web-fragment.xml” then everything will work out-of-the-box