struts-bean.tld

structs源码

<?xml version="1.0" encoding="UTF-8"?>
<!--
    $Id: struts-bean.tld 481833 2006-12-03 17:32:52Z niallp $

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
   
         http://www.apache.org/licenses/LICENSE-2.0
   
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<!DOCTYPE taglib
        PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN"
        "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
<taglib>
    <tlib-version>1.3</tlib-version>
    <jsp-version>1.2</jsp-version>
    <short-name>bean</short-name>
    <uri>http://struts.apache.org/tags-bean</uri>
    <description>
        <![CDATA[
  <p><strong>Note:  Some of the features in this taglib are also
  available in the <a href="http://java.sun.com/products/jsp/jstl/">JavaServer Pages Standard Tag Library (JSTL)</a>.
  The Struts team encourages the use of the standard tags over the Struts
  specific tags when possible.</strong></p>

  <p>This tag library contains tags useful in accessing beans and their
  properties, as well as defining new beans (based on these accesses)
  that are accessible to the remainder of the page via scripting variables
  and page scope attributes.  Convenient mechanisms to create new beans
  based on the value of request cookies, headers, and parameters are also
  provided.</p>

  <p>Many of the tags in this tag library will throw a
  <code>JspException</code> at runtime when they are utilized incorrectly
  (such as when you specify an invalid combination of tag attributes).  JSP
  allows you to declare an "error page" in the <code>&lt;%@ page %&gt;</code>
  directive.  If you wish to process the actual exception that caused the
  problem, it is passed to the error page as a request attribute under key
  <code>org.apache.struts.action.EXCEPTION</code>.</p>

  ]]>
    </description>
    <tag>
        <name>cookie</name>
        <tag-class>org.apache.struts.taglib.bean.CookieTag</tag-class>
        <tei-class>org.apache.struts.taglib.bean.CookieTei</tei-class>
        <body-content>empty</body-content>
        <description>
            <![CDATA[
            <p><strong>
    Define a scripting variable based on the value(s) of the specified
    request cookie.
    </strong></p>
          
    <p>Retrieve the value of the specified request cookie (as a single
    value or multiple values, depending on the <code>multiple</code> attribute),
    and define the result as a page scope attribute of type <code>Cookie</code>
    (if <code>multiple</code> is not specified) or <code>Cookie[]</code>
    (if <code>multiple</code> is specified).</p>

    <p>If no cookie with the specified name can be located, and no default
    value is specified, a request time exception will be thrown.</p>
    ]]>
        </description>
        <attribute>
            <name>id</name>
            <required>true</required>
            <rtexprvalue>false</rtexprvalue>
            <description>
                <![CDATA[
      <p>Specifies the name of the scripting variable (and associated page
      scope attribute) that will be made available with the value of the
      specified request cookie.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>multiple</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
      <p>If any arbitrary value for this attribute is specified, causes all
      matching cookies to be accumulated and stored into a bean of type
      <code>Cookie[]</code>.  If not specified, the first value for the
      specified cookie will be retrieved as a value of type
      <code>Cookie</code>.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>name</name>
            <required>true</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
      <p>Specifies the name of the request cookie whose value, or values,
      is to be retrieved.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>value</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
      <p>The default cookie value to return if no cookie with the
      specified name was included in this request.</p>
      ]]>
            </description>
        </attribute>
    </tag>
    <tag>
        <name>define</name>
        <tag-class>org.apache.struts.taglib.bean.DefineTag</tag-class>
        <tei-class>org.apache.struts.taglib.bean.DefineTei</tei-class>
        <body-content>JSP</body-content>
        <description>
            <![CDATA[
            <p><strong>
    Define a scripting variable based on the value(s) of the specified
    bean property.
    </strong></p>
          
    <p>Create a new attribute (in the scope specified by the
    <code>toScope</code> property, if any), and a corresponding scripting
    variable, both of which are named by the value of the <code>id</code>
    attribute.  The corresponding value to which this new attribute (and
    scripting variable) is set are specified via use of exactly one of the
    following approaches (trying to use more than one will result in a
    JspException being thrown):</p>
    <ul>
    <li>Specify a <code>name</code> attribute (plus optional
        <code>property</code> and <code>scope</code> attributes) -
        The created attribute and scripting variable will be of the type of the
        retrieved JavaBean property, unless it is a Java primitive type,
        in which case it will be wrapped in the appropriate wrapper class
        (i.e. int is wrapped by java.lang.Integer).</li>
    <li>Specify a <code>value</code> attribute - The created attribute and
        scripting variable will be of type <code>java.lang.String</code>,
        set to the value of this attribute.</li>
    <li>Specify nested body content - The created attribute and scripting
        variable will be of type <code>java.lang.String</code>, set to
        the value of the nested body content.</li>
    </ul>

    <p>If a problem occurs while retrieving the specified bean property, a
    request time exception will be thrown.</p>

    <p>The <code>&lt;bean:define&gt;</code> tag differs from
    <code>&lt;jsp:useBean&gt;</code> in several ways, including:</p>
    <ul>
    <li>Unconditionally creates (or replaces) a bean under the
        specified identifier.</li>
    <li>Can create a bean with the value returned by a property getter
        of a different bean (including properties referenced with a
        nested and/or indexed property name).</li>
    <li>Can create a bean whose contents is a literal string (or the result
        of a runtime expression) specified by the <code>value</code>
        attribute.</li>
    <li>Does not support nested content (such as
        <code>&lt;jsp:setProperty&gt;</code> tags) that are only executed
        if a bean was actually created.</li>
    </ul>

    <p><strong>USAGE NOTE</strong> - There is a restriction in the JSP 1.1
    Specification that disallows using the same value for an <code>id</code>
    attribute more than once in a single JSP page.  Therefore, you will not
    be able to use <code>&lt;bean:define&gt;</code> for the same bean
    name more than once in a single page.</p>

    <p><strong>USAGE NOTE</strong> - If you use another tag to create the
    body content (e.g. bean:write), that tag must return a non-empty String.
    An empty String equates to an empty body or a null String, and a new
    scripting variable cannot be defined as null. Your bean must return a
    non-empty String, or the define tag must be wrapped within a logic tag
    to test for an empty or null value.</p>

    <p><strong>USAGE NOTE</strong> - You cannot use bean:define to <strong>instantiate</strong>
    a DynaActionForm (type="org.apache.struts.action.DynaActionForm") with
    the properties specified in the struts-config. The mechanics of creating
    the dyna-properties is complex and cannot be handled by a no-argument
    constructor. If you need to create an ActionForm this way, you must use
    a conventional ActionForm.
    </p>

    <p>See the Bean Developer's Guide section on
    <a href="../api/org/apache/struts/taglib/bean/package-summary.html#doc.Creation">
    bean creation</a> for more information about these differences, as well
    as alternative approaches to introducing beans into a JSP page.</p>
    ]]>
        </description>
        <attribute>
            <name>id</name>
            <required>true</required>
            <rtexprvalue>false</rtexprvalue>
            <description>
                <![CDATA[
      <p>Specifies the name of the scripting variable (and associated page
      scope attribute) that will be made available with the value of the
      specified property.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>name</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
      <p>Specifies the attribute name of the bean whose property is accessed
      to define a new page scope attribute (if <code>property</code> is also
      specified) or the attribute name of the bean that is duplicated with
      the new reference created by this tag (if <code>property</code> is not
      also specified).  This attribute is required unless you specify
      a <code>value</code> attribute or nested body content.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>property</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
      <p>Specifies the name of the property to be accessed on the bean
      specified by <code>name</code>.  This value may be a simple, indexed,
      or nested property reference expression.  If not specified, the bean
      identified by <code>name</code> is given a new reference identified by
      <code>id</code>.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>scope</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
      <p>Specifies the variable scope searched to retrieve the bean specified
      by <code>name</code>.  If not specified, the default rules applied by
      <code>PageContext.findAttribute()</code> are applied.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>toScope</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
      <p>Specifies the variable scope into which the newly defined bean will
      be created.  If not specified, the bean will be created in
      <code>page</code> scope.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>type</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
        <p>Specifies the fully qualified class name of the value to be exposed
        as the <code>id</code> attribute.</p>
      ]]>
            </description>
        </attribute>
        <attribute>
            <name>value</name>
            <required>false</required>
            <rtexprvalue>true</rtexprvalue>
            <description>
                <![CDATA[
      <p>The <code>java.lang.String</code> value to which the exposed bean
      should be set.  This attribute is required unless you specify the
      <code>name</code> attribute or nested body content.</p>
      ]]>
            </description>