Using XDoclet with web applications

JRun provides integration with XDoclet, an open-source tool that generates code and deployment descriptors for EJBs, web applications, and JSP tag libraries.

XDoclet generates the web.xml and jrun-web.xml files using the settings in the WebDoclet task defined in the XDoclet configuration file. It uses your comments in servlets to create servlet definitions, filters, mappings, and other settings. In addition, you can merge files into the deployment descriptors that define session persistence settings and virtual mappings.

JRun supports basic XDoclet tags, which generate elements in the web.xml file and JRun-specific XDoclet tags, which generate elements in the jrun-web.xml file.

XDoclet uses Apache's Ant and its configuration file resembles build.xml files. XDoclet's configuration file is jrun_root/lib/xdoclet.xml.

For more information, see the XDoclet website at http://sourceforge.net/projects/xdoclet/.

Enabling the XDoclet service

You enable XDoclet using the XDocletService section of the jrun.xml file.

To enable XDoclet:

Create a servlet class file that contains XDoclet comments.
Name the servlet using a naming convention supported by the warSourceFiles attribute in the XDocletService section of the JRun server's jrun.xml file, or add a warSourceFiles attribute that matches your servlet's filename.
The default naming conventions are:
- *Servlet.java
- *Tag.java
- *Filter.java
  These default naming conventions match all servlets whose names end with Servlet, Tag, or Filter and have a .java extension.
Enable XDoclet support for all files in a directory by adding a watchedWARDirectory attribute of the XDocletService section of the JRun server's jrun.xml file.
The default directory is:
jrun_root/default-ear/default-war
This directory is commented out by default. You must uncomment the watchedWARDirectory attribute to watch it. You can also add additional directories for JRun to watch.
Save a servlet class in a directory that enables XDoclet support.
JRun generates entries for the servlet in the web application's deployment descriptors.

Configuring XDoclet resources

You configure XDoclet resources in the jrun_root/lib/xdoclet.xml. You can assign XDoclet to be part of the build with a JRun subtask. The JRun subtask is represented in the xdoclet.xml file as <jrunwebxml/>. The following table lists the attributes of the <jrunwebxml/> subtask:

Attribute

Description

xmlencoding

The encoding of the jrun-web.xml file. The default is UTF-8.

destdir

Specifies the destination directory for outputting JRun-specific deployment descriptor files. The default is the destdir parameter of webdoclet task.

mergedir

Specifies the directory for merge files; the merge files can be session-config.xml and virtual-mapping.xml.

contextRoot

Specifies the context root of the web application. The context-root defaults to the name of the directory or JAR that contains the web application.

reload

Specifies whether to automatically reload servlets, servlet helper classes, and JSP helper classes. Defaults to false.

compile

Specifies whether to automatically compile servlets, servlet helper classes, and JSP helper classes. Setting this to true degrades performance. Defaults to false.

loadSystemClassesFirst

Specifies whether system classes should be loaded before enterprise and web application classes. The normal classloader delegation model loads the system classes first; however, the servlet specification suggests loading web application classes first. Defaults to true.

Attribute	Description
`xmlencoding`	The encoding of the jrun-web.xml file. The default is UTF-8.
`destdir`	Specifies the destination directory for outputting JRun-specific deployment descriptor files. The default is the `destdir` parameter of `webdoclet` task.
`mergedir`	Specifies the directory for merge files; the merge files can be session-config.xml and virtual-mapping.xml.
`contextRoot`	Specifies the context root of the web application. The context-root defaults to the name of the directory or JAR that contains the web application.
`reload`	Specifies whether to automatically reload servlets, servlet helper classes, and JSP helper classes. Defaults to false.
`compile`	Specifies whether to automatically compile servlets, servlet helper classes, and JSP helper classes. Setting this to true degrades performance. Defaults to false.
`loadSystemClassesFirst`	Specifies whether system classes should be loaded before enterprise and web application classes. The normal classloader delegation model loads the system classes first; however, the servlet specification suggests loading web application classes first. Defaults to true.

For an example of the <jrunwebxml/> task, see "XDoclet configuration example".

Merging files into web.xml

You can define merge files that are used by XDoclet when building the deployment descriptors. You can define settings such as session persistence and virtual mappings in these external merge files. These merge files are named session-config.xml and virtual-mapping.xml. You define the location of these merge files in the XDoclet configuration file.

Using XDoclet tags

You use a combination of jrun.xml attributes and JavaDoc-style comments in your servlet class files to control the processing performed by XDoclet. This section describes the standard XDoclet tags and JRun-specific tags in your source code that are used by XDoclet.

XDoclet comments start with the @ sign.

Standard web application XDoclet tags

Basic XDoclet tags start with the @jsp: or @web: prefix. These tags are part of the basic XDoclet architecture. When you use these tags in your source files, XDoclet uses them to create entries in the web application's web.xml file.

The following table describes the standard XDoclet tags used for web application components:

Tag

Description

@jsp:attribute

Declares the specified field as a JSP tag attribute. This tag should be placed on getter methods.

@jsp:tag

Declares the class as a class implementing a JSP tag and specifies various properties of that tag.

@jsp:validator-init-param

Declares init parameters for the Validator with the specified parameter name, value and description.

@jsp:variable

Declares a JSP tag variable and information on the scripting variables defined.

@web:ejb-local-ref

Defines a local EJB reference with the specified name, type, home interface name, local interface name, link name, and description. The value of the link parameter must be the ejb-name of an enterprise bean in the same J2EE application unit.

@web:ejb-ref

Defines a remote EJB reference with the specified name, type, home interface name, remote interface name, link name, and description. The value of the link parameter must be the ejb-name of an enterprise bean in the same J2EE application unit.

@web:env-entry

Defines a environment entry with the specified name, type and value.

@web:filter

Declares the class as a Filter class, with the specified name, display-name, icon and description. Applicable to Servlet 2.3 only.

@web:filter-init-param

Declares init parameters for the Filter with the specified parameter name, value and description. Applicable to Servlet 2.3 only.

@web:filter-mapping

Defines the mapping for the Filter. Either url-pattern or servlet-name should be specified. Applicable to Servlet 2.3 only.

@web:listener

Declares the class as a Listener class.

@web:resource-env-ref

Defines a resource environment reference with the specified name, type and description.

@web:resource-ref

Defines a resource reference with the specified name, type, description, authentication (auth) and scope.

@web:security-role

Defines a security role with the specified role-name and description.

@web:security-role-ref

Defines a security role reference with the name role-name to a security role link named role-link.

@web:servlet

Declares the class as a Servlet class, with the specified name, display-name, icon and description.

@web:servlet-init-param

Declares init parameters for the Servlet with the specified parameter name, value and description.

@web:servlet-mapping

Defines the mapping for the Servlet to the specified url-pattern.

Tag	Description
@jsp:attribute	Declares the specified field as a JSP tag attribute. This tag should be placed on getter methods.
@jsp:tag	Declares the class as a class implementing a JSP tag and specifies various properties of that tag.
@jsp:validator-init-param	Declares init parameters for the Validator with the specified parameter name, value and description.
@jsp:variable	Declares a JSP tag variable and information on the scripting variables defined.
@web:ejb-local-ref	Defines a local EJB reference with the specified name, type, home interface name, local interface name, link name, and description. The value of the link parameter must be the ejb-name of an enterprise bean in the same J2EE application unit.
@web:ejb-ref	Defines a remote EJB reference with the specified name, type, home interface name, remote interface name, link name, and description. The value of the link parameter must be the ejb-name of an enterprise bean in the same J2EE application unit.
@web:env-entry	Defines a environment entry with the specified name, type and value.
@web:filter	Declares the class as a Filter class, with the specified name, display-name, icon and description. Applicable to Servlet 2.3 only.
@web:filter-init-param	Declares init parameters for the Filter with the specified parameter name, value and description. Applicable to Servlet 2.3 only.
@web:filter-mapping	Defines the mapping for the Filter. Either url-pattern or servlet-name should be specified. Applicable to Servlet 2.3 only.
@web:listener	Declares the class as a Listener class.
@web:resource-env-ref	Defines a resource environment reference with the specified name, type and description.
@web:resource-ref	Defines a resource reference with the specified name, type, description, authentication (auth) and scope.
@web:security-role	Defines a security role with the specified role-name and description.
@web:security-role-ref	Defines a security role reference with the name role-name to a security role link named role-link.
@web:servlet	Declares the class as a Servlet class, with the specified name, display-name, icon and description.
@web:servlet-init-param	Declares init parameters for the Servlet with the specified parameter name, value and description.
@web:servlet-mapping	Defines the mapping for the Servlet to the specified url-pattern.

For more information, including a complete list of tags and their parameters, see the XDoclet website at http://xdoclet.sourceforge.net/.

JRun-specific XDoclet tags

JRun-specific XDoclet tags start with the @jrun: prefix. When you use these tags in your source files, XDoclet uses them to create entries in the jrun-web.xml file. All of these tags are class-level tags. The following table lists JRun-specific XDoclet tags:

Tag

Description

@jrun:ejb-local-ref

Caution: Describes a mapping between the ejb-ref-name that the bean developer provides and its JNDI name. The deployer provides the actual JNDI name.

@jrun:ejb-ref

Describes a mapping between the ejb-ref-name that the bean developer provides and its JNDI name. The deployer provides the actual JNDI name. Used in: entity, message-driven, session

@jrun:resource-env-ref

Describes a mapping between the resource-env-name that the bean developer provides and its JNDI name. The deployer provides the actual JNDI name.

@jrun:resource-ref

Describes a mapping between the resource name that the bean developer provides and its JNDI name. The deployer provides the actual JNDI name.

Tag	Description
@jrun:ejb-local-ref	*Caution:* Describes a mapping between the ejb-ref-name that the bean developer provides and its JNDI name. The deployer provides the actual JNDI name.
@jrun:ejb-ref	Describes a mapping between the ejb-ref-name that the bean developer provides and its JNDI name. The deployer provides the actual JNDI name. Used in: entity, message-driven, session
@jrun:resource-env-ref	Describes a mapping between the resource-env-name that the bean developer provides and its JNDI name. The deployer provides the actual JNDI name.
@jrun:resource-ref	Describes a mapping between the resource name that the bean developer provides and its JNDI name. The deployer provides the actual JNDI name.

For more information on JRun-specific XDoclet tags, see the online descriptor documentation, available from the documentation home page. For online examples of EJBs that use XDoclet, see the samples JRun server.

XDoclet examples

This section shows Java source files that use XDoclet tags and of the xdoclet.xml configuration file.

Servlet example

The following example shows a simple servlet that uses XDoclet to define the servlet's url-pattern mapping and initialization parameters:

import javax.servlet.http.*;

import javax.servlet.*;
import java.io.*;

/**

�* A hello world.
�*
�* @web:servlet name="SimpleServlet" display-name="Simple Servlet" load-on-startup="1"
�* @web:servlet-init-param name="param1" value="value1"
�* @web:servlet-init-param name="param2" value="value2"
�* @web:servlet-mapping url-pattern="/hellaworld/*"
�* 
�* @author�����Macromedia
�* @created ���Mar 14, 2002
�* @version����$1.0 $
�**/

public class SimpleServlet extends HttpServlet {

��public void doGet( HttpServletRequest request, HttpServletResponse response ) 
     throws IOException, ServletException {
����PrintWriter out = response.getWriter()
����out.println("Hella World");
��}
}

Filter example

The following example shows a filter servlet that uses XDoclet to add a filter definition, map the filter to all XML files, and define the filter's initialization parameters:

import javax.servlet.*;

import javax.servlet.http.*;
import java.util.*;

/**

�* Tests adding filters to web.xml using xdoclet.
�*
�* @web:filter name="XDocletFilter" display-name="XDoclet Test Filter"
�* @web:filter-init-param name="param1" value="value1"
�* @web:filter-init-param name="param2" value="value2"
�* @web:filter-mapping url-pattern="/*.xml"
�*
�* @author�����Macromedia
�* @created ���Mar 14, 2002
�* @version����$1.0 $
�**/

public class XDocletFilter extends GenericFilter {

��public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain) 
     throws java.io.IOException, javax.servlet.ServletException {
����chain.doFilter(req, resp);
��}
}

XDoclet configuration example

The following example defines the WebDoclet task in the xdoclet.xml file:

<webdoclet

��sourcepath="${xdoclet.working.dir}"
��destdir="${xdoclet.working.dir}"
��classpathref="project.class.path">
��<!-- Include Struts Support -->
��<fileset dir="${xdoclet.working.dir}">
����<include name="**/*Servlet.java" />
����<include name="**/*Filter.java" />
����<include name="**/*Tag.java" />
����<include name="**/*Action.java" />
��</fileset>
��<deploymentdescriptor servletspec="2.3" destdir="${war.meta.dir}" />
��<jsptaglib jspversion="1.2"
����destdir="${war.meta.dir}/tlds"
����shortname="j2ee"
��/>
��<jrunwebxml
����destdir="${war.meta.dir}"
����contextRoot="webapp"
����reload="true"
����compile="true"
����loadSystemClassesFirst="false"
��/>
</webdoclet>

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/jrun/4/Programmers_Guide/servletxml8.htm

Programmer's Guide
JRun and XML