KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > woody > datatype > 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.woody.datatype;
17
18 import org.outerj.expression.ExpressionContext;
19 import org.apache.cocoon.woody.datatype.convertor.Convertor;
20
21 import java.util.Locale JavaDoc;
22
23 /**
24  * A Datatype encapsulates the functionality for working with specific
25  * kinds of data like integers, deciamals or dates.
26  *
27  * <p>I provides:
28  * <ul>
29  * <li>Methods for converting between String and Object representation of the data
30  * <li>For validating the data (usually against a set of validation rules)
31  * <li>optionally a selection list
32  * </ul>
33  *
34  * <p>Each datatype can be marked as an "arraytype". Currently, this only has an
35  * influence on the {@link #validate(Object, ExpressionContext)} method, which should in that case be passed
36  * an array of objects. See also {@link #isArrayType()}.
37  *
38  * @version $Id: Datatype.java 30932 2004-07-29 17:35:38Z vgritsenko $
39  */

40 public interface Datatype {
41     /**
42      * Converts a string to an object of this datatype. Returns null if this
43      * fails. This method uses the same {@link Convertor} as returned by the
44      * {@link #getConvertor()} method.
45      */

46     Object JavaDoc convertFromString(String JavaDoc value, Locale JavaDoc locale);
47
48     /**
49      * Converts an object of this datatype to a string representation.
50      * This method uses the same {@link Convertor} as returned by the
51      * {@link #getConvertor()} method.
52      */

53     String JavaDoc convertToString(Object JavaDoc value, Locale JavaDoc locale);
54
55     /**
56      * Returns null if validation is successful, otherwise returns a
57      * {@link ValidationError} instance.
58      *
59      * @param value an Object of the correct type for this datatype (see
60      * {@link #getTypeClass()}, or if {@link #isArrayType()}
61      * returns true, an array of objects of that type.
62      */

63     ValidationError validate(Object JavaDoc value, ExpressionContext expressionContext);
64
65     /**
66      * Gets the class object for the type represented by this datatype. E.g. Long, String, ...
67      * The objects returned from the convertFromString* methods are of this type, and the object
68      * passed to the convertToString* or validate methods should be of this type.
69      */

70     Class JavaDoc getTypeClass();
71
72     /**
73      * Returns a descriptive name for the base type of this datatype,
74      * i.e. something like 'string', 'long', 'decimal', ...
75      */

76     String JavaDoc getDescriptiveName();
77
78     /**
79      * Indicates wether this datatype represents an array type. This approach has been
80      * chosen instead of creating a seperate ArrayDatatype interface (and corresponding
81      * implementations), since almost all functionality is the same between the scalar
82      * and array types. The main difference is that the validate() method will be passed
83      * arrays instead of single values, and hence different validation rules will be
84      * required.
85      */

86     boolean isArrayType();
87
88     /**
89      * Returns the convertor used by this datatype.
90      */

91     Convertor getConvertor();
92
93     /**
94      * Returns the "plain convertor". This is convertor that should have a locale-independent
95      * string encoding, and guarantees perfect roundtripping. It is used if a value of this
96      * datatype needs to be stored but not displayed to the user.
97      */

98     Convertor getPlainConvertor();
99
100     /**
101      * Returns the factory that built this datatype.
102      */

103     DatatypeBuilder getBuilder();
104 }
105
Popular Tags