001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.woody.datatype;
018:
019: import org.outerj.expression.ExpressionContext;
020: import org.apache.cocoon.woody.datatype.convertor.Convertor;
021:
022: import java.util.Locale;
023:
024: /**
025: * A Datatype encapsulates the functionality for working with specific
026: * kinds of data like integers, deciamals or dates.
027: *
028: * <p>I provides:
029: * <ul>
030: * <li>Methods for converting between String and Object representation of the data
031: * <li>For validating the data (usually against a set of validation rules)
032: * <li>optionally a selection list
033: * </ul>
034: *
035: * <p>Each datatype can be marked as an "arraytype". Currently, this only has an
036: * influence on the {@link #validate(Object, ExpressionContext)} method, which should in that case be passed
037: * an array of objects. See also {@link #isArrayType()}.
038: *
039: * @version $Id: Datatype.java 433543 2006-08-22 06:22:54Z crossley $
040: */
041: public interface Datatype {
042: /**
043: * Converts a string to an object of this datatype. Returns null if this
044: * fails. This method uses the same {@link Convertor} as returned by the
045: * {@link #getConvertor()} method.
046: */
047: Object convertFromString(String value, Locale locale);
048:
049: /**
050: * Converts an object of this datatype to a string representation.
051: * This method uses the same {@link Convertor} as returned by the
052: * {@link #getConvertor()} method.
053: */
054: String convertToString(Object value, Locale locale);
055:
056: /**
057: * Returns null if validation is successful, otherwise returns a
058: * {@link ValidationError} instance.
059: *
060: * @param value an Object of the correct type for this datatype (see
061: * {@link #getTypeClass()}, or if {@link #isArrayType()}
062: * returns true, an array of objects of that type.
063: */
064: ValidationError validate(Object value,
065: ExpressionContext expressionContext);
066:
067: /**
068: * Gets the class object for the type represented by this datatype. E.g. Long, String, ...
069: * The objects returned from the convertFromString* methods are of this type, and the object
070: * passed to the convertToString* or validate methods should be of this type.
071: */
072: Class getTypeClass();
073:
074: /**
075: * Returns a descriptive name for the base type of this datatype,
076: * i.e. something like 'string', 'long', 'decimal', ...
077: */
078: String getDescriptiveName();
079:
080: /**
081: * Indicates wether this datatype represents an array type. This approach has been
082: * chosen instead of creating a seperate ArrayDatatype interface (and corresponding
083: * implementations), since almost all functionality is the same between the scalar
084: * and array types. The main difference is that the validate() method will be passed
085: * arrays instead of single values, and hence different validation rules will be
086: * required.
087: */
088: boolean isArrayType();
089:
090: /**
091: * Returns the convertor used by this datatype.
092: */
093: Convertor getConvertor();
094:
095: /**
096: * Returns the "plain convertor". This is convertor that should have a locale-independent
097: * string encoding, and guarantees perfect roundtripping. It is used if a value of this
098: * datatype needs to be stored but not displayed to the user.
099: */
100: Convertor getPlainConvertor();
101:
102: /**
103: * Returns the factory that built this datatype.
104: */
105: DatatypeBuilder getBuilder();
106: }
|