# Defining the Web Deployment Descriptor

## Target Audience and Content

The target audience for this guide is the Web component provider, i.e. the person in charge of developing the Web components on the server side. It describes how the Web component provider should build the deployment descriptors of its Web components.

The content of this guide is the following:

1. Target Audience and Content
2. Principles
3. Example of Web Deployment Descriptors
4. Tips

## Principles

The Web component programmer is responsible for providing the deployment descriptor associated to the developed web components. As one goes along the different steps of the application development and deployment life cycle of the Web components, (development, assembly, deployment), the deployment descriptor has to be completed.

The Web component provider's responsibilities and the Application Assembler's responsibilities is to provide a XML deployment descriptor respecting the deployment descriptor's XML DTD defined in the Java TM Servlet Specification Version 2.3. (See `$JONAS_ROOT/xml/web-app_2_3.dtd`).

To be able to customize the Web components, informations not defined in the standard XML deployment descriptor may be needed. Such information includes for example the mapping of the name of referenced resources to its JNDI name. This information can be specified, during the deployment phase, within another XML deployment descriptor, which is specific to JOnAS. The JOnAS specific deployment descriptor's XML DTD can be found in `$JONAS_ROOT/xml/jonas-web-app_X_Y.dtd`. The file name of the JOnAS specific XML deployment descriptor must be the file name of the standard XML deployment descriptor prefixed by '`jonas-`'.

The JOnAS interpretation of the <!DOCTYPE> tag is particular, at the parsing of the deployment descriptor XML files.
The parser try, first, to get the specified DTD via the classpath, and then via the specified URL (or path).

Examples: in these two following examples, the parser get the `jonas-web-app_2_6.dtd` DTD file via the URL or in the /usr/local/jonas/xml/ directory.

        <!DOCTYPE jonas-web-app PUBLIC "-//ObjectWeb//DTD JOnAS Web App 2.6//EN" "http://www.objectweb.org/jonas/dtds/jonas-web-app_2_6.dtd">
        <!DOCTYPE jonas-web-app SYSTEM "/usr/local/jonas/xml/jonas-web-app_2_6.dtd">

The standard deployment descriptor (web.xml) should contain structural information including:

- Servlet's description (including Servlet's name, Servlet's class or jsp-file, Servlet's initialization parameters,
- Environment entries,
- EJB references,
- EJB local references,
- Resource references,
- Resource env references.

The JOnAS specific deployment descriptor (jonas-web.xml) may contain information including:

- The JNDI name of the external resources referenced by a Web component,
- The JNDI name of the external resources environment referenced by a Web component,
- The JNDI name of the referenced bean's by a Web component,
- The name of the virtual host on which to deploy the servlets,
- The name of the context root on which to deploy the servlets.
- The compliance of the web application classloader to the java 2 delegation model or not.

<host> element : If you have virtual hosts in the configuration file of the web container, you can set the host on which the WAR file is deployed.

<context-root> element : Specify the name of the context on which the application will be deployed. If it is not specified, the context-root used can be :

- If the war is packaged into an EAR file : the context-root used is the context specified in the application.xml file
- If the war is standalone, the context-root is the name of the war file. ie : for jadmin.war, the context-root is /jadmin

If the context-root is / or empty, the web application is deployed as ROOT context. ie : http://localhost:8080/

<java2-delegation-model> element : Set the compliance to the java 2 delegation model.

- if true : the web application context uses a classloader using the Java 2 delegation model.(ask parent classloader first)
- if false : the class loader looks inside the web application first, before asking parent class loaders.

## Example of Web Deployment Descriptors

- Example of a standard Web Deployment Descriptor (web.xml) :

      <?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>
        <servlet>
          <servlet-name>Op</servlet-name>
            <servlet-class>org.objectweb.earsample.servlets.ServletOp</servlet-class>
        </servlet>

        <servlet-mapping>
          <servlet-name>Op</servlet-name>
          <url-pattern>/secured/Op</url-pattern>
        </servlet-mapping>

        <security-constraint>
          <web-resource-collection>
            <web-resource-name>Protected Area</web-resource-name>
              <!-- Define the context-relative URL(s) to be protected -->
      	<url-pattern>/secured/*</url-pattern>
      	<!-- If you list http methods, only those methods are protected -->
      	<http-method>DELETE</http-method>
              <http-method>GET</http-method>
              <http-method>POST</http-method>
      	<http-method>PUT</http-method>
          </web-resource-collection>
          <auth-constraint>
            <!-- Anyone with one of the listed roles may access this area -->
            <role-name>tomcat</role-name>
            <role-name>role1</role-name>
          </auth-constraint>
        </security-constraint>

        <!-- Default login configuration uses BASIC authentication -->
        <login-config>
          <auth-method>BASIC</auth-method>
          <realm-name>Example Basic Authentication Area</realm-name>
        </login-config>

        <env-entry>
          <env-entry-name>envEntryString</env-entry-name>
          <env-entry-value>This is a string from the env-entry</env-entry-value>
          <env-entry-type>java.lang.String</env-entry-type>
        </env-entry>

        <!-- reference on a remote bean without ejb-link-->
        <ejb-ref>
          <ejb-ref-name>ejb/Op</ejb-ref-name>
          <ejb-ref-type>Session</ejb-ref-type>
          <home>org.objectweb.earsample.beans.secusb.OpHome</home>
          <remote>org.objectweb.earsample.beans.secusb.Op</remote>
        </ejb-ref>

        <!-- reference on a remote bean using ejb-link-->
        <ejb-ref>
          <ejb-ref-name>ejb/EjbLinkOp</ejb-ref-name>
          <ejb-ref-type>Session</ejb-ref-type>
          <home>org.objectweb.earsample.beans.secusb.OpHome</home>
          <remote>org.objectweb.earsample.beans.secusb.Op</remote>
          <ejb-link>secusb.jar#Op</ejb-link>
        </ejb-ref>

        <!-- reference on a local bean -->
        <ejb-local-ref>
          <ejb-ref-name>ejb/OpLocal</ejb-ref-name>
          <ejb-ref-type>Session</ejb-ref-type>
          <local-home>org.objectweb.earsample.beans.secusb.OpLocalHome</local-home>
          <local>org.objectweb.earsample.beans.secusb.OpLocal</local>
          <ejb-link>secusb.jar#Op</ejb-link>
        </ejb-local-ref>
      </web-app>

- Example of a specific Web Deployment Descriptor (jonas-web.xml):

      <?xml version="1.0" encoding="ISO-8859-1"?>
      <!DOCTYPE jonas-web-app PUBLIC "-//ObjectWeb//DTD JOnAS Web App 3.1//EN"
                                     "http://www.objectweb.org/jonas/dtds/jonas-web-app_3_1.dtd">
      <jonas-web-app>
        <!-- Mapping between the referenced bean and its JNDI name, override the ejb-link
             if there is one in the associated ejb-ref in the standard Web Deployment Descriptor -->
        <jonas-ejb-ref>
          <ejb-ref-name>ejb/Op</ejb-ref-name>
          <jndi-name>OpHome</jndi-name>
        </jonas-ejb-ref>

        <!-- the virtual host on which deploy the web application -->
        <host>localhost</host>

        <!-- the context root on which deploy the web application -->
        <context-root>/web-application</context-root>
      </jonas-web-app>

## Tips

Some characters, such "<" and "&" are strictly illegal in the XML data.
Others, such ">", are legal, but it is a good habit to replace them by XML entity references.

Here is the list of the predefined entity references in XML:

&lt; | < | less than
&gt; | > | greater than
&amp; | & | ampersand
&apos; | ' | apostrophe
&quot; | " | quotation mark