Datatype


1   /*
2    * Copyright 1999-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.cocoon.forms.datatype;
17  
18  import org.outerj.expression.ExpressionContext;
19  import org.apache.cocoon.forms.datatype.convertor.Convertor;
20  import org.apache.cocoon.forms.datatype.convertor.ConversionResult;
21  import org.apache.cocoon.forms.validation.ValidationError;
22  import org.xml.sax.SAXException  ;
23  import org.xml.sax.ContentHandler  ;
24  
25  import java.util.Locale  ;
26  
27  /**
28   * A Datatype encapsulates the functionality for working with specific
29   * kinds of data like integers, decimals or dates.
30   *
31   * <p>It provides:
32   * <ul>
33   *  <li>Methods for converting between String and Object representation of the data
34   *  <li>For validating the data (usually against a set of validation rules)
35   *  <li>optionally a selection list
36   * </ul>
37   *
38   * <p>Each datatype can be marked as an "arraytype". Currently, this only has an
39   * influence on the {@link #validate(Object, ExpressionContext)} method, which should in that case be passed
40   * an array of objects. See also {@link #isArrayType()}.
41   * 
42   * @version $Id: Datatype.java 178749 2005-05-27 05:18:23Z antonio $
43   */
44  public interface Datatype {
45      /**
46       * Converts a string to an object of this datatype. This method uses the
47       * same {@link Convertor} as returned by the {@link #getConvertor()} method.
48       */
49      ConversionResult convertFromString(String   value, Locale   locale);
50  
51      /**
52       * Converts an object of this datatype to a string representation.
53       * This method uses the same {@link Convertor} as returned by the
54       * {@link #getConvertor()} method.
55       */
56      String   convertToString(Object   value, Locale   locale);
57  
58      /**
59       * Returns null if validation is successful, otherwise returns a
60       * {@link ValidationError} instance.
61       *
62       * @param value  an Object of the correct type for this datatype (see
63       *               {@link #getTypeClass()}, or if {@link #isArrayType()}
64       *               returns true, an array of objects of that type.
65       */
66      ValidationError validate(Object   value, ExpressionContext expressionContext);
67  
68      /**
69       * Gets the class object for the type represented by this datatype. E.g. Long, String, ...
70       * The objects returned from the convertFromString* methods are of this type, and the object
71       * passed to the convertToString* or validate methods should be of this type.
72       */
73      Class   getTypeClass();
74  
75      /**
76       * Returns a descriptive name for the base type of this datatype,
77       * i.e. something like 'string', 'long', 'decimal', ...
78       */
79      String   getDescriptiveName();
80  
81      /**
82       * Indicates wether this datatype represents an array type. This approach has been
83       * chosen instead of creating a seperate ArrayDatatype interface (and corresponding
84       * implementations), since almost all functionality is the same between the scalar
85       * and array types. The main difference is that the validate() method will be passed
86       * arrays instead of single values, and hence different validation rules will be
87       * required.
88       */
89      boolean isArrayType();
90  
91      /**
92       * Returns the convertor used by this datatype.
93       */
94      Convertor getConvertor();
95  
96      /**
97       * Returns the "plain convertor". This is convertor that should have a locale-independent
98       * string encoding, and guarantees perfect roundtripping. It is used if a value of this
99       * datatype needs to be stored but not displayed to the user.
100      */
101     Convertor getPlainConvertor();
102 
103     /**
104      * Returns the factory that built this datatype.
105      */
106     DatatypeBuilder getBuilder();
107 
108     /**
109      * Generates a bit of information about this datatype.
110      */
111     void generateSaxFragment(ContentHandler   contentHandler, Locale   locale) throws SAXException  ;
112 }
113
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags