Servlet 3.0 web-fragment.xml

Thursday May 07, 2009

In JSR 315: Java Servlet 3.0 Specification, web-fragment.xml is introduced for pluggability of library jars which are packaged under WEB-INF/lib. The content of web.xml and web-fragment.xml are almost the same. One can define servlets, filters and listeners there. One can also specify metadata-complete=true in a given web-fragment.xml. In the latter case, the annotation processing of classes in that jar would be skipped. With web-fragment.xml, library jars can be self-contained and provide web related metadata information.

The basic differences of web.xml and web-fragment.xml are summarized in the following table:

	web.xml	web-fragment.xml
Location	WEB-INF of the war file	META-INF directory of JAR file inside WAR file's WEB-INF/lib
Ordering related element	<absolute-ordering>	<ordering>

Ordering of web fragments

If there are more than one web-fragment jars, then one may like to specify the order of processing web-fragment.xml and annotations. This is important. For instance, filters will be executed in the order specified in web.xml. Similary for listeners. In Servlet 3.0, <absolute-ordering> is introduced in web.xml and <ordering> is introduced in web-fragment.xml. The ordering of web-fragments is specified in the following priority:

• from <absolute-ordering> in web.xml if it exists
• from <ordering> for each web-fragment.xml if it exists
• otherwise unspecified

absolute-ordering in web.xml

The <absolute-ordering> in web.xml provides a way to specify the ordering of loading web-fragment.xml and annotation processing of web fragment. For instance,

<web-app>
    ...
    <absolute-ordering>
        <name>A</name>
         <others/>
        <name>B</name>
    <absolute-ordering>
</web-app>

In the above example, the web fragment A would be processed first and web fragment B would be processed last. Note the name A and B are specified in name element of web-fragment.xml (see examples below).

ordering in web-fragment.xml

If there is no <absolute-ordering> in web.xml, then one would look at <ordering> in web-fragment.xml. The details are described in section 8.2.3 of Servlet 3.0 spec. Let us look at some examples.

• There is only one jar having <ordering> in web-fragment.xml.

  <web-fragment>
    <name>A</name>
    ...
    <ordering>
        <before>
            <others/>
        </before>
    </ordering>
</web-fragment>

  In this case, web-fragment A would be processed first.

• There are two jars having <ordering> in web-fragment.xml, namely
  web-fragment A:

  <web-fragment>
    <name>A</name>
    ...
    <ordering>
        <before>
            <others/>
        </before>
    </ordering>
</web-fragment>

  web-fragment B:

  <web-fragment>
    <name>B</name>
    ...
    <ordering>
        <before>
            <others/>
        </before>
    </ordering>
</web-fragment>

  Both web-fragment A and B would like to be processed first. In this case, one only guarantee that both A and B are processed before other web-fragments. But the ordering of A and B are not determined, that is arbitrary in this case.

• There are two jars having <ordering> in web-fragment.xml, namely
  web-fragment A:

  <web-fragment>
    <name>A</name>
    ...
    <ordering>
        <before>
            <others/>
        </before>
    </ordering>
</web-fragment>

  web-fragment B:

  <web-fragment>
    <name>B</name>
    ...
    <ordering>
        <after>
            <name>A</name>
        </after>
        <before>
            <others/>
        </before>
    </ordering>
</web-fragment>

  In this case, A would be processed first, then followed by B, and then other web-fragments.

If one would like to have a deterministic ordering, then I would recommend to use absolute-ordering in web.xml.

Servlet 3.0 Security Annotations

Monday May 04, 2009

In Servlet 2.5, only @DeclareRoles and @RunAs are supported in servlets. And @DenyAll, @PermitAll, @RolesAllowed are only supported for EJBs. In JSR 315: Java Servlet 3.0 Specification, @DenyAll, @PermitAll, @RolesAllowed will be supported in servlets. Furthermore, it supports JSR 250: Common Annotations for the Java Platform MR1:

• @TransportProtected, a new annotation indicates whether the transport is confidential or none.
• @DenyAll will also be available at the TYPE level.

The mapping of the @DenyAll, @PermitAll, @RolesAllowed and @TransportProtected to security constraint are described in Chapter 13.4.1 of Servlet 3.0 specification. These annotations can be applied to:

• the servlet class
• one of the following methods in HttpServlet:
  • doDelete
  • doGet
  • doHead
  • doOptions
  • doPost
  • doPut
  • doTrace

Note that method level authorization annotations (@DenyAll, @PermitAll, @RolesAllowed) override those in class level for the associated http method. Similarly, method level @TransportProtected overrides the one in class level.

In this blog, we illustrate the usages of these annotations by examples.

Example 1: Type Level

@WebServlet("/myurl")
@RolesAllowed("javaee")
public class TestServlet extends HttpServlet {
    ...
}

In this case, all http methods are protected and accessible only by users with role javaee.

Example 2: Method Level

@WebServlet("/myurl")
public class TestServlet extends HttpServlet {
    @PermitAll
    protected void doGet(HttpServletRequest req, HttpServletResponse res)
            throws IOException, ServletException {
        ...
    }

    @RolesAllowed("javaee")
    protected void doPost(HttpServletRequest req, HttpServletResponse res)
            throws IOException, ServletException {
        ...
    }

    @DenyAll
    protected void doTrace(HttpServletRequest req, HttpServletResponse res)
            throws IOException, ServletException {
        ...
    }
}

The behaviors of the above servlet can be summarized as follows:

Http method	Behavior
GET	all can access GET method
POST	only authenticated users with role javaee can access POST method
TRACE	no one can access TRACE method

Example 3: Type and Method Level

@WebServlet("/myurl")
@RolesAllowed("javaee")
public class TestServlet extends HttpServlet {
    ...

    @RolesAllowed("staff")
    protected void doPost(HttpServletRequest req, HttpServletResponse res)
            throws IOException, ServletException {
        ...
    }

    @PermitAll
    protected void doTrace(HttpServletRequest req, HttpServletResponse res)
            throws IOException, ServletException {
        ...
    }
}

The behaviors of the above servlet can be summarized as follows:

Http method	Behavior
POST	only authenticated users with role staff can access POST method
TRACE	all can access TRACE method
methods other than POST and TRACE	only authenticated users with role javaee can access

Example 4: @TransportProtected and @RolesAllowed

@WebServlet("/myurl")
@TransportProtected
public class TestServlet extends HttpServlet {
    ...

    @TransportProtected(false)
    @RolesAllowed("javaee")
    protected void doTrace(HttpServletRequest req, HttpServletResponse res)
        throws IOException, ServletException {

        ...
    }
}

The behaviors of the above servlet can be summarized as follows:

Http method	Behavior
TRACE	no https, only authenticated users with role javaee can access TRACE method
methods other than TRACE	require https