[Apache-Fulcrum-Intake]表示层和业务层的数据传递组件

Intake Service

Intake uses an xml specification to perform web form input validation and mapping input data to a bean's properties. In other words, Intake will allow a web application to take web form input, validate it and then map the data to an object. Tools like the Torque help provide mapping of Objects to the database and Intake helps map web form data to Objects. Intake can be used standalone by any application that supports Avalon components. However it has extensive integration with the Turbine application server. This howto focuses on using it with Turbine.

The visual picture of where Intake fits into a Turbine web application looks something like this:

------------------
   

    HTML Form
   

------------------
   

     Intake
   

------------------
   

 Business Objects  <- Torque Generated
   

------------------
   

      Peers        <- Torque Generated
   

------------------
   

      RDBMS
   

------------------
   

There are several advantages to using Intake. First off, it provides for a centralized management system for dealing with form data. All of the configuration of Intake is done through a single XML file. Next, Intake is good for validating the form data. Intake provides the ability to do regular expression matching in order to make sure that form fields contain the data that they should contain. For example, if someone should only enter a number into a form field, it can be validated with a regular expression. Lastly, Intake can provides a centralized source for error messages. If the validation fails, the error message defined in the XML file can be shown to the user.

  使用Intake有若干优势。首先，Intake提供了一个处理表单数据的集中管理系统。所有Intake的配置都在一个专门的XML文件中完成。其次，Intake便于验证表单数据。Intake能够进行表达式匹配以便保证表单域中包含合法的数据。比如说，如果某人应当在一个表单域中填入数字，填入内容可以用一个合格的表达式进行验证。最后，Intake能够把错误信息集中到一起。如果验证失败，定义在XML文件中的错误信息将被显示给用户。

Usage

Intake is implemented as a Avalon component. Access to it is provided by a Turbine Pull Tool. An XML specification is parsed during the service initialization and used by the pull tool while processing request data and generating the response.

Intake is made available in the Velocity context with the default value of $intake. The name of the variable that is used is what is configured for the tool. For example, the current configuration is "tool.request.intake". To change the name of the variable to "foo", it would be "tool.request.foo".

Intake is made available in Java code by adding the following imports to the top of a .java file:

import org.apache.fulcrum.intake.model.*;
   

import org.apache.turbine.services.intake.IntakeTool;
   

Xml File

The following example come from Scarab. These are a couple of groups from Scarab's intake.xml:

<input-data basePackage="org.tigris.scarab.">
  

<group name="AttributeValue" key="attv"
  

            mapToObject="om.AttributeValue">
  

    <field name="Value" key="val" type="String">
  

        <rule name="maxLength" value="255">Value length cannot be &gt; 255</rule>
  

        <required-message>This module requires data for this
  

                          attribute.
  

        </required-message>
  

    </field>
  

    <field name="Url" key="url" type="String" mapToProperty="Value">
  

        <rule name="maxLength" value="255">Url length cannot be &gt; 255</rule>
  

        <rule name="mask" value="^$|http.+">Please enter an url starting with "http"</rule>
  

        <required-message>This module requires a valid url.</required-message>
  

    </field>
  

    <field name="OptionId" key="optionid" type="NumberKey">
  

        <rule name="mask" value="^$|[0-9]+">Please select a valid choice</rule>
  

        <required-message>This module requires that you select an option
  

                          for this attribute.
  

        </required-message>
  

    </field>
  

</group>
  

<group name="Login" key="login">
  

    <field name="Username" key="u" type="String">
  

        <rule name="minLength" value="1">Please enter an email address</rule>
  

        <rule name="mask" value=".+@.+/..+">Please enter a valid email address</rule>
  

    </field>
  

    <field name="Password" key="p" type="String">
  

        <rule name="minLength" value="1">Please enter a password</rule>
  

    </field>
  

</group>
  

</input-data>
  

A group is a set of fields that have been aligned so that they form a logical unit. The first group includes some of the properties from a om.AttributeValue business object (BO). This object is a Java Bean object with get/set methods for each of the properties in the object. In this case, the object has been auto-generated by Torque from Scarab's SQL schema.

The group tag has a class attribute which is the name that will be used within templates and java code to refer to the group. It also contains a key attribute which will be used in the query parameters. The key is not referenced in any code, so it can be a short name (even 1 character) as long as it is uniquely identifies the group from the rest.

An object that the group's fields will map can also be specified. This will be a default; the individual fields within a group can map to different objects.

Fields have attributes: name and key which serve similar function to the group's class and key attributes. It has mapToObject and mapToProperty fields that can be used to associate a business object to the field for prepopulating the field as well as assigning the field data to the bean after successful validation. The field must have a type, which can be simple types such as String and Integer. It is planned that more complex types, such as Email, Url, or Date, will be added that will add functionality that is difficult or not possible with a simple regex mask.

The field can define rule elements. The basic fields include rules for minimum and maximum, lengths and values, as well as a regex mask.