husted 2002/07/07 12:00:14
Modified: conf/share struts-config_1_1.dtd
Log:
Update the comments documenting the DTD to enhance consistency and clarity. This is
the first update of two (about half-way through).
Revision Changes Path
1.24 +155 -130 jakarta-struts/conf/share/struts-config_1_1.dtd
Index: struts-config_1_1.dtd
===================================================================
RCS file: /home/cvs/jakarta-struts/conf/share/struts-config_1_1.dtd,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- struts-config_1_1.dtd 6 Jul 2002 01:12:56 -0000 1.23
+++ struts-config_1_1.dtd 7 Jul 2002 19:00:13 -0000 1.24
@@ -89,38 +89,41 @@
<!ATTLIST struts-config id ID #IMPLIED>
-<!-- The "data-sources" element describes a set of JDBC 2.0 Standard Extension
- data source objects which will be configured according to the nested
- "data-source" elements found inside.
+<!-- The "data-sources" element describes a set of DataSource objects [JDBC 2.0
+ Standard Extension]. The individual DataSource objects are configured through
+ nested "data-source" elements.
-->
-
<!ELEMENT data-sources (data-source*)>
<!ATTLIST data-sources id ID #IMPLIED>
-<!-- The "data-source" element describes a JDBC 2.0 Standard Extension data
- source object (that implements javax.sql.DataSource) which will be
- configured according to the properties and nested elements found here,
- and made available as a servlet context attribute (i.e. application
- scope bean). The following attributes are required:
-
- className Implementation subclass of the standard configuration
- bean, if you do not want to use the standard value.
+<!-- The "data-source" element describes a DataSource object [JDBC 2.0 Standard
+ Extension] that will be instantiated, configured, and made available as a
+ servlet context attribute (or "application-scope bean"). Any object can be
+ specified so long as it implements javax.sql.DataSource and can be
+ configured entirely from JavaBean properties. The following attributes
+ are required:
+
+ className The configuration bean for this DataSource object. If
+ specified, the object must be a subclass of the default
+ configuration bean.
[org.apache.struts.config.DataSourceConfig]
- key Servlet context attribute key under which this data
- source will be stored. Default is the value specified
- by string constant Action.DATA_SOURCE_KEY.
-
- NOTE: The attribute under which this data source is
- actually stored will be the key value suffixed by
- the application prefix for this sub-application
-
- type Fully qualified Java class name of the data source
- implementation class. This class must implement
- "javax.sql.DataSource" and be configurable totally
- from JavaBeans properties.
- [org.apache.struts.util.GenericDataSource]
+ key Servlet context attribute key under which this data source
+ will be stored. Default is the value specified by string
+ constant defined by Action.DATA_SOURCE_KEY. The application
+ module prefix (if any) is appended to the key
+ (${key}$prefix}).
+ [org.apache.struts.Action.DATA_SOURCE_KEY]
+
+ NOTE: The application module prefix includes the leading
+ slash, so the default datasource for a module named "foo" is
+ stored under "org.apache.struts.action.DATA_SOURCE/foo".
+
+ type Fully qualified Java class name for this data source object.
+ The class must implement DataSource [javax.sql.DataSource],
+ and the object must be configurable entirely from JavaBean
+ properties.
-->
<!ELEMENT data-source (set-property*)>
<!ATTLIST data-source id ID #IMPLIED>
@@ -129,45 +132,45 @@
<!ATTLIST data-source type %ClassName; #IMPLIED>
-<!-- The "global-exceptions" element configures the global handling of
- exceptions thrown by Actions to mappable resources (identified by
- application-relative URI paths). A global "exception" handler for a
- particular exception class can be locally overridden by defining an
- "exception" element with the same "type" attribute.
+<!-- The "global-exceptions" element describes a set of exceptions that might be
+ thrown by an Action object. The handling of individual exception types is
+ configured through nested exception elements. An "action" element may
+ override a global exception handler by registering a local exception handler
+ for the same exception type. Since Struts 1.1.
-->
<!ELEMENT global-exceptions (exception*)>
<!ATTLIST global-exceptions id ID #IMPLIED>
-<!-- The "exception" element describes a mapping of an exception that may
- occur during Action delegation and should be handled by the
- ActionServlet.
-
- bundle Servlet context attribute under which the message
- resources bundle from which this message should be
- acquired. Default is the value specified by the
- string constant Action.MESSAGES_KEY.
+<!-- The "exception" element registers an ExceptionHandler for an exception type.
+ The following attributes are defined:
- className Implementation subclass of the standard configuration
- bean, if you do not want to use the standard value.
+ bundle Servlet context attribute for the message resources bundle
+ associated with this handler. The default attribute is the
+ value specified by the string constant declared at
+ [org.apache.struts.Action.MESSAGES_KEY].
+
+ className The configuration bean for this ExceptionHandler object.
+ If specified, className must be a subclass of the default
+ configuration bean
[org.apache.struts.config.ExceptionConfig]
- handler Fully qualified Java class name of the exception handler
- which should handle this exception.
+ handler Fully qualified Java class name for this exception handler.
[org.apache.struts.action.ExceptionHandler]
- key Message resources key specifying the error message
- associated with this exception.
-
- path The application-relative path of the resource to
- forward to if this exception occurs.
+ key The key to use with this handler's message resource bundle
+ that will retrieve the error message template for this
+ exception.
+
+ path The module-relative URI to the resource that will complete
+ the request/response if this exception occurs.
+
+ scope The context ("request" or "session") that is used to access
+ the ActionError object [org.apache.struts.action.ActionError]
+ for this exception.
- scope Identifier of the scope ("request" or "session")
- within which the resulting ActionError will be
- made accessible
-
- type Fully qualified Java class name of the exception
- that is to be handled.
+ type Fully qualified Java class name of the exception type to
+ register with this handler.
-->
<!ELEMENT exception (icon?, display-name?, description?, set-property*)>
<!ATTLIST exception id ID #IMPLIED>
@@ -180,11 +183,13 @@
<!ATTLIST exception type %ClassName; #REQUIRED>
-<!-- The "form-beans" element is the root of the set of form bean descriptors
- for this application. The following attributes are defined:
+<!-- The "form-beans" element describes the set of form bean descriptors for this
+ application module. The following attributes are defined:
- type Fully qualified Java class name of the implementation
- class used for ActionFormBean objects. DEPRECATED.
+ type Fully qualified Java class to use when instantiating
+ ActionFormBean objects. If specified, the object must be a
+ subclass of the default class type.
+ DEPRECATED.
WARNING: For Struts 1.0, this value is ignored. You
can set the default implementation class name with the
@@ -196,26 +201,34 @@
<!ATTLIST form-beans type %ClassName; #IMPLIED>
-<!-- The "form-bean" element describes a particular form bean, which is a
+<!-- The "form-bean" element describes an ActionForm subclass
+ [org.apache.struts.action.ActionForm] that can be referenced by an "action"
+ element.
+
+
+The "form-bean" element describes a particular form bean, which is a
JavaBean that implements the org.apache.struts.action.ActionForm
class. The following attributes are defined:
- className Implementation subclass of the standard configuration
- bean, if you do not want to use the standard value.
+ className The configuration bean for this form bean object. If
+ specified, the object must be a subclass of the default
+ configuration bean.
[org.apache.struts.config.FormBeanConfig]
- dynamic Is the class identified by the "type" attribute
- a DynaActionForm with dynamic properties? If the
- type attribute is set to
- "org.apache.struts.action.DynaActionForm", this
- property defaults to true, otherwise it defaults
- to false.
-
- name Unique identifier of this bean, used to reference it
- in corresponding action mappings.
+ dynamic If the form bean type is a DynaActionForm subclass (that you
+ created), then (and only then) set this attribute to true. If
+ the type is set to the default DynaActionForm or any
+ conventional ActionForm subclass, then this attribute can be
+ omitted.
+ [true] if type is "org.apache.struts.action.DynaActionForm"
+ [false] otherwise
+
+ name The unique identifier for this form bean. Referenced by the
+ "action" element to specify which form bean to use with its
+ request.
- type Fully qualified Java class name of the implementation
- class to be used or generated
+ type Fully qualified Java class name of the ActionForm subclass
+ to use with this form bean.
-->
<!ELEMENT form-bean (icon?, display-name?, description?, set-property*,
form-property*)>
<!ATTLIST form-bean id ID #IMPLIED>
@@ -225,26 +238,27 @@
<!ATTLIST form-bean type %ClassName; #REQUIRED>
-<!-- The "form-property" element describes a particular JavaBean property of a
- form bean. It is utilized only when the "type" of the surrounding
- "form-bean" element is "org.apache.struts.action.DynaActionForm" (or
- a subclass of that class), and thus supports dynamic properties. The
- following attributes are defined:
-
- className Implementation subclass of the standard configuration
- bean, if you do not want to use the standard value.
+<!-- The "form-property" element describes a JavaBean property that can be used to
+ configure an instance of a DynaActionForm or a subclass thereof. This element
+ is only utilized when the "type" attribute of the enclosing "form-bean" element
+ is [org.apache.struts.action.DynaActionForm] or a subclass of DynaActionForm.
If
+ a custom DynaActionForm subclass is used, then the "dynamic" attribute of the
+ enclosing "form-bean" element must be set to true. Since Struts 1.1.
+
+ className The configuration bean for this form property object. If
+ specified, the object must be a subclass of the default
+ configuration bean.
[org.apache.struts.config.FormPropertyConfig]
- initial String representation of the initial value for
- this property. If not specified, primitives will
- by initialized to zero and objects to null.
-
- name JavaBeans property name of the property being described
- by this element.
-
- type Fully qualified Java class name of the implementation
- class of this bean property, optionally followed by "[]"
- to indicate that this property is indexed.
+ initial String representation of the initial value for this property.
+ If not specified, primitives will be initialized to zero and
+ objects initialized to null.
+
+ name The name of the JavaBean property described by this element.
+
+ type Fully qualified Java class name of the field underlying this
+ property, optionally followed by "[]" to indicate that the
+ field is indexed.
-->
<!ELEMENT form-property (set-property*)>
<!ATTLIST form-property className %ClassName; #IMPLIED>
@@ -253,14 +267,16 @@
<!ATTLIST form-property type %ClassName; #REQUIRED>
-<!-- The "global-forwards" element configures the global mappings of logical
- names (used within the application) to mappable resources (identified
- by application-relative URI paths). A global "forward" with a particular
- name can be locally overridden by defining a "forward" of the same name
- within an "action" element. The following attribute are defined:
-
- type Fully qualified Java class name of the implementation
- class used for ActionForward objects. DEPRECATED.
+<!-- The "global-forwards" element describes a set of ActionForward objects
+ [org.apache.struts.action.ActionForward] that are available to all Action
+ objects as a return value. The individual ActionForwards are configured
+ through nested "forward" elements. An "action" element may override a global
+ forward by defining a local "forward" of the same name.
+
+ type Fully qualified Java class to use when instantiating
+ ActionForward objects. If specified, the object must be a
+ subclass of the default class type.
+ DEPRECATED.
WARNING: For Struts 1.0, this value is ignored. You
can set the default implementation class name with the
@@ -272,33 +288,40 @@
<!ATTLIST global-forwards type %ClassName; #IMPLIED>
-<!-- The "forward" element describes a mapping of a logical name (used within
- the application) to a mappable resource identified by an
- application-relative URI path. The following attributes are defined:
+<!-- The "forward" element describes an ActionForward that is to be made
+ available to an Action as a return value. An ActionForward is referenced by
+ a logical name and encapsulates a URI. A "forward" element may be used to
+ describe both global and local ActionForwards. Global forwards are available
+ to all the Action objects in the application module. Local forwards can be
+ nested within an "action" element and only available to an Action object
+ when it is invoked through that ActionMapping.
- className Implementation subclass of the standard configuration
- bean, if you do not want to use the standard value.
+ className Fully qualified Java class name of ActionForward
+ subclass to use for this object.
[org.apache.struts.action.ActionForward]
- contextRelative Set to "true" if the path should be considered relative
- to the entire web application, rather than prefixed with
- the sub-application prefix, if it starts with a "/".
-
- name Unique identifier of this forward, used to reference it
- in application action classes.
-
- path The application-relative or context-relative path of
- the mapped resource (determined by the selected value
- for the "contextRelative" attribute). If contextRelative
- is false, this value is used in a calculation based on
- the "forwardPattern" property of the controller parameters
- for the current sub-application to calculate the
- resulting value. This value must begin with a slash
+ contextRelative Set this to "true" if, in a modular application, the path
+ attribute starts with a slash "/" and should be considered
+ relative to the entire web application rather than the module.
+ Since Struts 1.1.
+ [false]
+
+ name The unique identifier for this forward. Referenced by the
+ Action object at runtime to select - by its logical name -
+ the resource that should complete the request/response.
+
+ path The module-relative or context-relative path to the resources
+ that is encapsulated by the logical name of this
ActionForward.
+ If the path is to be considered context-relative when used in
+ a modular application, then the contextRelative attribute
+ should be set to true. This value should begin with a slash
("/") character.
- redirect Set to "true" if sendRedirect() should be used to forward
- to this resource, or "false" in order to use
- RequestDispatcher.forward() instead.
+ redirect Set to "true" if a redirect instruction should be issued to
+ the user-agent so that a new request is issued for this
+ forward's resource. If true, RequestDispatcher.Redirect is
+ called. If false, RequestDispatcher.forward is called instead.
+ [false]
-->
<!ELEMENT forward (icon?, display-name?, description?, set-property*)>
<!ATTLIST forward id ID #IMPLIED>
@@ -309,13 +332,15 @@
<!ATTLIST forward redirect %Boolean; #IMPLIED>
-<!-- The "action-mappings" element configures the mappings from submitted
- request paths to the corresponding Action classes that should be
- used to process these requests. The following attributes are
- defined:
-
- type Fully qualified Java class name of the ActionMapping
- implementation class to be used.
+<!-- The "action-mappings" element describes a set of ActionMapping objects
+ [org.apache.struts.action.ActionMapping] that are available to process
+ requests matching the url-pattern our ActionServlet registered with the
+ container. The individual ActionMappings are configured through nested
+ "action" elements. The following attributes are defined:
+
+ type Fully qualified Java class to use when instantiating
+ ActionMapping objects. If specified, the object must be a
+ subclass of the default class type.
WARNING: For Struts 1.0, this value is ignored. You
can set the default implementation class name with the
@@ -327,9 +352,9 @@
<!ATTLIST action-mappings type %ClassName; #IMPLIED>
-<!-- The "action" element describes a mapping from a request paths to the
- corresponding Action classes that should be used to process these
- requests. The following attributes are defined:
+<!-- The "action" element describes an ActionMapping object that is to be used
+ to process a request for a specific module-relative URI. The following
+ attributes are defined:
attribute Name of the request-scope or session-scope attribute
under which our form bean is accessed, if it is other
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
