struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hus...@apache.org
Subject cvs commit: jakarta-struts/conf/share struts-config_1_1.dtd
Date Sun, 07 Jul 2002 19:00:14 GMT
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:struts-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:struts-dev-help@jakarta.apache.org>


Mime
View raw message