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:
The Web component programmer is responsible for providing the deployment
descriptor associated with the developed web components. The Web component
provider's responsibilities and the application assembler's responsibilities
are to provide an XML deployment descriptor that conforms to the deployment
descriptor's XML DTD as defined in the Java TM Servlet
Specification Version 2.3. (Refer to
$JONAS_ROOT/xml/web-app_2_3.dtd
).
To customize the Web components, information not defined in the standard
XML deployment descriptor may be needed. For example, the information may
include 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 that is specific to JOnAS. The JOnAS-specific
deployment descriptor's XML DTD is located 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-'.
JOnAS interprets the <!DOCTYPE> tag at the parsing of the deployment
descriptor XML files.
The parser first tries to get the specified DTD via the classpath, then it
uses the specified URL (or path).
In the two following examples, the parser gets the
jonas-web-app_3_1.dtd
DTD file via the URL or in the
/usr/local/jonas/xml/ directory.
<!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"> <!DOCTYPE jonas-web-app SYSTEM "/usr/local/jonas/xml/jonas-web-app_3_1.dtd">
The standard deployment descriptor (web.xml) should contain structural information that includes the following:
The JOnAS-specific deployment descriptor (jonas-web.xml) may contain information that includes:
<host> element: If the configuration file of the web container contains virtual hosts, the host on which the WAR file is deployed can be set.
<context-root> element: The name of the context on which the application will be deployed should be specified. If it is not specified, the context-root used can be one of the following:
<java2-delegation-model> element: Set the compliance to the java 2 delegation model.
<?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>
<?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>
Although some characters, such as ">", are legal, it is good practice to replace them with XML entity references. The following is a list of the predefined entity references for XML:
< | < | less than |
> | > | greater than |
& | & | ampersand |
' | ' | apostrophe |
" | " | quotation mark |