<webdoclet/> Task

This task allows you to generate various web-related files using nested subtasks and template files.

You don't have to deal with monolithic web.xml or taglib.tld files, you set the deployment meta-data per component. You don't have to worry about outdating deployment meta-data whenever you touch the code. The deployment meta-data is continuously integrated. And the whole process is, in its nature, round-trip.

See Parameters And Nested Elements Applicable To All Doclet Tasks.

Nested Elements

deploymentdescriptor

Creates web.xml deployment descriptor.

Parameters

Attribute Description Required
xmlencoding The encoding of the ejb-jar.xml file. No, default is "UTF-8"
destdir Destination directory for output deployment descriptor file. No, default is destdir parameter of webdoclet task
mergedir Merge directory where webdoclet looks for files to be merged with generated files. No, required, if the merge feature used
servletspec The version of Servlet spec webdoclet should adhere, currently "2.2" and "2.3" defined. If, for example, "2.3" specified, then webdoclet will generate Servlet 2.3-compatible web.xml file. No, default is "2.3"
smallicon The file name for small GIF or JPEG icon image used to represent the parent element in a GUI tool. No
largeicon The file name for small GIF or JPEG icon image used to represent the parent element in a GUI tool. No
displayname The display-name element contains a short name that is intended to be displayed by tools. The display name need not be unique. No
description Provides text describing the web application. The description should include any information that WAR producer wants to provide to the consumer of WAR (i.e., to the Deployer). Typically, the tools used by WAR consumer will display the description when processing the parent element that contains the description. No
distributable If "true" indicates that this web application is programmed appropriately to be deployed into a distributed servlet container, "false" otherwise. No, default is "true"
contextparam nested elements Contains the declaration of a web application’s servlet context initialization parameters. It's a nested element and has these parameters:

name: Contains the name of a parameter. Each parameter name must be unique in the web application.
value: Contains the value of a parameter.

 No
sessiontimeout Defines the default session timeout interval for all sessions created in this web application. The specified timeout must be expressed in a whole number of minutes. If the timeout is 0 or less, the container ensures the default behavior of sessions is never to time out. No, default is "0"
welcomefile nested elements An ordered list of welcomefile nested elements. The welcomefile element contains file name to use as a default welcome file, such as index.html. No
taglib nested elements used to describe a JSP tag library. It's a nested element and has these parameters:

uri: Describes a URI, relative to the location of the web.xml document, identifying a Tag Library used in the Web Application.
location: the location (as a resource relative to the root of the web application) where to find the Tag Libary Description file for the tag library.

 No
validateXml Validates the generated xml file according to the DTD file contained inside xdoclet.jar. No, default is false

Merge Points

Merge File Name Description Required
web-settings.xml The file where you specify the global settings for the web application according to the following DTD:

<!ELEMENT icon (small-icon?, large-icon?)>
<!ELEMENT small-icon (#PCDATA)>
<!ELEMENT large-icon (#PCDATA)>
<!ELEMENT display-name (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT distributable EMPTY>
<!ELEMENT context-param (param-name, param-value, description?)>
<!ELEMENT param-name (#PCDATA)>
<!ELEMENT param-value (#PCDATA)>

 No
filter-mappingss.xml The file where filter-mappings are defined according to the following DTD:

<!ELEMENT filter-mapping (filter-name, (url-pattern | servlet-name))>
<!ELEMENT filter-name (#PCDATA)>
<!ELEMENT servlet-name (#PCDATA)>
<!ELEMENT url-pattern (#PCDATA)>

 No
web-sec-rolerefs-{0}.xml The file where per servlet security role-refs are defined according to the following DTD. {0}designates the servlet class name.

<!ELEMENT security-role-ref (description?, role-name, role-link)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT role-name (#PCDATA)>
<!ELEMENT role-link (#PCDATA)>

 No
servlet-mappings.xml The file where servlet mappings are defined according to the following DTD:

<!ELEMENT servlet-mapping (servlet-name, url-pattern)>
<!ELEMENT servlet-name (#PCDATA)>
<!ELEMENT url-pattern (#PCDATA)>

 No
mime-mappings.xml The file where mime type mapping are defined according to the following DTD:

<!ELEMENT mime-mapping (extension, mime-type)>
<!ELEMENT extension (#PCDATA)>
<!ELEMENT mime-type (#PCDATA)>

 No
error-pages.xml The file where error pages are defined according to the following DTD:

<!ELEMENT error-page ((error-code | exception-type), location)>
<!ELEMENT error-code (#PCDATA)>
<!ELEMENT exception-type (#PCDATA)>
<!ELEMENT location (#PCDATA)>

 No
taglibs.xml The file where taglibs are defined according to the following DTD:

<!ELEMENT taglib (taglib-uri, taglib-location)>
<!ELEMENT taglib-uri (#PCDATA)>
<!ELEMENT taglib-location (#PCDATA)>

 No
ejb-resourcerefs-{0}.xml The file where EJB resource references are defined for the servlet or filter according to the following DTD:

<!ELEMENT resource-env-ref (description?, resource-env-ref-name, resource-env-ref-type)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT resource-env-ref-name (#PCDATA)>
<!ELEMENT resource-env-ref-type (#PCDATA)>

 No
web-security.xml The file where security settings for the web application are defined according to the following DTD:

<!ELEMENT security-constraint (display-name?, web-resource-collection+, auth-constraint?, user-data-constraint?)>
<!ELEMENT web-resource-collection (web-resource-name, description?, url-pattern*, http-method*)>
<!ELEMENT web-resource-name (#PCDATA)>
<!ELEMENT url-pattern (#PCDATA)>
<!ELEMENT http-method (#PCDATA)>
<!ELEMENT user-data-constraint (description?, transport-guarantee)>
<!ELEMENT transport-guarantee (#PCDATA)>
<!ELEMENT login-config (auth-method?, realm-name?, form-login-config?)>
<!ELEMENT auth-method (#PCDATA)>
<!ELEMENT realm-name (#PCDATA)>
<!ELEMENT form-login-config (form-login-page, form-error-page)>
<!ELEMENT form-login-page (#PCDATA)>
<!ELEMENT form-error-page (#PCDATA)>

 No
web-sec-roles.xml The file where security role names for the web application are defined according to the following DTD:

<!ELEMENT security-role (description?, role-name)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT role-name (#PCDATA)>

 No
web-env-entries-{0}.xml The file where environment entries for the servlet or filter are defined according to the following DTD. {0}designates the servlet or filter class name.

<!ELEMENT env-entry (description?, env-entry-name, env-entryvalue?, env-entry-type)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT env-entry-name (#PCDATA)>
<!ELEMENT env-entry-value (#PCDATA)>
<!ELEMENT env-entry-type (#PCDATA)>

 No
web-ejbrefs-{0}.xml The file where EJB refrences for the servlet or filter are defined according to the following DTD. {0}designates the servlet or filter class name.

<!ELEMENT ejb-ref (description?, ejb-ref-name, ejb-ref-type, home, remote, ejb-link?)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT ejb-ref-name (#PCDATA)>
<!ELEMENT ejb-ref-type (#PCDATA)>
<!ELEMENT home (#PCDATA)>
<!ELEMENT remote (#PCDATA)>
<!ELEMENT ejb-link (#PCDATA)>

 No
web-ejbrefs-local-{0}.xml The file where local EJB references for the servlet or filter are defined according to the following DTD. {0}designates the servlet or filter class name. Applicable only to 2.3+ versions of Servlet specification.

<!ELEMENT ejb-local-ref (description?, ejb-ref-name, ejb-ref-type, local-home, local, ejb-link?)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT ejb-ref-name (#PCDATA)>
<!ELEMENT ejb-ref-type (#PCDATA)>
<!ELEMENT local-home (#PCDATA)>
<!ELEMENT local (#PCDATA)>
<!ELEMENT ejb-link (#PCDATA)>

 No
welcomefiles.xml Specify welcome files in this file according to the following DTD, alternatively you can also use <welcomeFiles/> nested element.

<!ELEMENT welcome-file-list (welcome-file+)>
<!ELEMENT welcome-file (#PCDATA)>

 No
servlets.xml Specify other servlets in this files. No
filters.xml Specify other filters in this files. No

Remember you should preserve the package directory structure in mergedir. If the bean is test.bank.AccountBean then ejb-env-entries-Account.xml should be located at test/bank directory in mergedir.

jsptaglib

Creates taglib.tld deployment descriptor.

Parameters

Attribute Description Required
xmlencoding The encoding of the taglib.tld file. No, default is "UTF-8"
destdir Destination directory for output deployment descriptor file. No, default is destdir parameter of webdoclet task
mergedir Merge directory where webdoclet looks for files to be merged with generated files. No, required, if the merge feature used
taglibversion The taglib version. No, default is "1.0"
jspversion The version of JSP spec webdoclet should adhere, currently "1.2" and "1.1" defined. If, for example, "1.2" specified, then webdoclet will generate JSP 1.2-compatible taglib.tld file. No, default is "1.2"
smallicon The file name for small GIF or JPEG icon image used to represent the parent element in a GUI tool. No
largeicon The file name for small GIF or JPEG icon image used to represent the parent element in a GUI tool. No
displayname The display-name element contains a short name that is intended to be displayed by tools. The display name need not be unique. No
description Provides text describing the web application. The description should include any information that JSP producer wants to provide to the consumer of tag library. No
validateXml Validates the generated xml file according to the DTD file contained inside xdoclet.jar. No, default is false

Merge Points

Merge File Name Description Required
taglib-settings.xml The file where you specify the global settings for the tag library according to the following DTD:

<!ELEMENT tlib-version (#PCDATA) >
<!ELEMENT jsp-version (#PCDATA) >
<!ELEMENT short-name (#PCDATA) >
<!ELEMENT uri (#PCDATA) >
<!ELEMENT display-name (#PCDATA) >
<!ELEMENT small-icon (#PCDATA) >
<!ELEMENT large-icon (#PCDATA) >
<!ELEMENT description(#PCDATA) >

 No
tag-example-{0}.xml

Provides an informal description of an example of the use of a tag according to the following DTD:

<!ELEMENT example (#PCDATA) >

 No

Remember you should preserve the package directory structure in mergedir. If the bean is test.bank.AccountBean then ejb-env-entries-Account.xml should be located at test/bank directory in mergedir.

Class level Tags

@web:filter

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

Parameter Usage
[name]: String The name for the filter. Unique within the application.
[display-name]: String The display name of the filter.
[icon]: String The icon for the filter.
[description]: String A description for the filter.

@web:filter-init-param

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

Parameter Usage
name: String The name of the init parameter.
[value]: String The value for the parameter.
[description]: String An optional description of the parameter.

@web:filter-mapping

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

Parameter Usage
[url-pattern]: String The url pattern the filter should match.
[servlet-name]: String The servlet name for the filter.

@web:servlet

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

Parameter Usage
name: String The name of the servlet - unique within the application.
[display-name]: String An optional display name for the servlet.
[icon]: String An optional icon for the servlet.
[description]: String An optional description for the servlet.

@web:servlet-init-param

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

Parameter Usage
name: String The name of the servlet init parameter.
value: String The value of the servlet init parameter.
[description]: String An optional description for the servlet parameter.

@web:servlet-mapping

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

Parameter Usage
url-pattern: String A url pattern for the servlet to match.

@web:listener

Declares the class as a Listener class.

@web:security-role-ref

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

Parameter Usage
role-name: String The name of the role reference.
[role-link]: String The name of the role link.

@web:resource-env-ref

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

Parameter Usage
name: String The name of the resource environment refernece.
type: String The type of the referenced resource.
[description]: String An optional description of the resource reference.

@web:resource-ref

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

Parameter Usage
name: String The name of the resource reference.
type: String The type of the referenced resource.
auth: "Application" | "Container" The authentication for the resource.
[description]: String An optional description for the resource reference.
[scope]: "Shareable" | "Unshareable" The scope of the resource.

@web:security-role

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

Parameter Usage
role-name: String The role name.
[description]: String The description of the role.

@web:env-entry

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

Parameter Usage
name: String The name of the env-entry.
type: String The type of the env-entry.
[value]: String The value of the env-entry.

@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.

Parameter Usage
name: String The name or the ejb reference.
type: String The expected type of the referenced enterprise bean. Must be one of the following: Entity or Session.
home: String The home interface of the referenced ejb.
remote: String
The remote interface of the referenced ejb.
[link]: String The link to the EJB.
[description]: String An optional description for the ejb-ref.

@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.

Parameter Usage
name: String The name of the ejb-local-ref.
type: String The expected type of the referenced enterprise bean. Must be one of the following: Entity or Session.
home: String The local home interface of the ejb ref.
local: String The local interface of the referenced ejb.
[link]: String The link to the ejb.
[description]: String An optional description for the ejb-ref

@jsp:validator-init-param

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

Parameter Usage
name: String The name of the validator init param.
value: String The value of the validator init param
[description]: String An optional description for the validator.

@jsp:tag

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

Parameter Usage
name: String The name of the JSP tag.
[tei-class]: String The tei class for the JSP.
[body-content]: "JSP" | "empty" | "tagdependent" The body content field for the tag.
[display-name]: String An optional display name for the tag.
[small-icon]: String An optional small icon for the tag.
[large-icon]: String An optional large icon for the tag.
[description]: String An optional description for the tag.

@jsp:variable

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

Parameter Usage
[name-given]: String The variable name as a constant.
[name-from-attribute]: String The name of an attribute whose (translation time) value will give the name of the variable. One of name-given or name-from-attribute is required.
[class]: String Name of the class of the variable. java.lang.String is default.
[declare]: boolean Whether the variable is declared or not. True is the default.
[scope]: "NESTED" | "AT_BEGIN" | "AT_END" The scope of the scripting variable defined. NESTED is default.
[description]: String An optional description of the variable.

@jsp:attribute

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

Parameter Usage
[required]: boolean Whether the attribute is required.
[rtexprvalue]: boolean Whether the attribute is a runtime attribute.
[type]: String The type of the attribute.
[description]: String An optional description of the attribute.