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.forms.datatype;
018:
019: import org.outerj.expression.ExpressionContext;
020: import org.apache.cocoon.forms.datatype.convertor.Convertor;
021: import org.apache.cocoon.forms.datatype.convertor.ConversionResult;
022: import org.apache.cocoon.forms.validation.ValidationError;
023: import org.xml.sax.SAXException;
024: import org.xml.sax.ContentHandler;
025:
026: import java.util.Locale;
027:
028: /**
029: * A Datatype encapsulates the functionality for working with specific
030: * kinds of data like integers, decimals or dates.
031: *
032: * <p>It provides:
033: * <ul>
034: * <li>Methods for converting between String and Object representation of the data
035: * <li>For validating the data (usually against a set of validation rules)
036: * <li>optionally a selection list
037: * </ul>
038: *
039: * <p>Each datatype can be marked as an "arraytype". Currently, this only has an
040: * influence on the {@link #validate(Object, ExpressionContext)} method, which should in that case be passed
041: * an array of objects. See also {@link #isArrayType()}.
042: *
043: * @version $Id: Datatype.java 449149 2006-09-23 03:58:05Z crossley $
044: */
045: public interface Datatype {
046: /**
047: * Converts a string to an object of this datatype. This method uses the
048: * same {@link Convertor} as returned by the {@link #getConvertor()} method.
049: */
050: ConversionResult convertFromString(String value, Locale locale);
051:
052: /**
053: * Converts an object of this datatype to a string representation.
054: * This method uses the same {@link Convertor} as returned by the
055: * {@link #getConvertor()} method.
056: */
057: String convertToString(Object value, Locale locale);
058:
059: /**
060: * Returns null if validation is successful, otherwise returns a
061: * {@link ValidationError} instance.
062: *
063: * @param value an Object of the correct type for this datatype (see
064: * {@link #getTypeClass()}, or if {@link #isArrayType()}
065: * returns true, an array of objects of that type.
066: */
067: ValidationError validate(Object value,
068: ExpressionContext expressionContext);
069:
070: /**
071: * Gets the class object for the type represented by this datatype. E.g. Long, String, ...
072: * The objects returned from the convertFromString* methods are of this type, and the object
073: * passed to the convertToString* or validate methods should be of this type.
074: */
075: Class getTypeClass();
076:
077: /**
078: * Returns a descriptive name for the base type of this datatype,
079: * i.e. something like 'string', 'long', 'decimal', ...
080: */
081: String getDescriptiveName();
082:
083: /**
084: * Indicates wether this datatype represents an array type. This approach has been
085: * chosen instead of creating a seperate ArrayDatatype interface (and corresponding
086: * implementations), since almost all functionality is the same between the scalar
087: * and array types. The main difference is that the validate() method will be passed
088: * arrays instead of single values, and hence different validation rules will be
089: * required.
090: */
091: boolean isArrayType();
092:
093: /**
094: * Returns the convertor used by this datatype.
095: */
096: Convertor getConvertor();
097:
098: /**
099: * Returns the "plain convertor". This is convertor that should have a locale-independent
100: * string encoding, and guarantees perfect roundtripping. It is used if a value of this
101: * datatype needs to be stored but not displayed to the user.
102: */
103: Convertor getPlainConvertor();
104:
105: /**
106: * Returns the factory that built this datatype.
107: */
108: DatatypeBuilder getBuilder();
109:
110: /**
111: * Generates a bit of information about this datatype.
112: */
113: void generateSaxFragment(ContentHandler contentHandler,
114: Locale locale) throws SAXException;
115: }
|