/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.cocoon.forms.datatype;

import org.outerj.expression.ExpressionContext;
import org.apache.cocoon.forms.datatype.convertor.Convertor;
import org.apache.cocoon.forms.datatype.convertor.ConversionResult;
import org.apache.cocoon.forms.validation.ValidationError;
import org.xml.sax.SAXException;
import org.xml.sax.ContentHandler;

import java.util.Locale;

/**
 * A Datatype encapsulates the functionality for working with specific
 * kinds of data like integers, decimals or dates.
 *
 * <p>It provides:
 * <ul>
 *  <li>Methods for converting between String and Object representation of the data
 *  <li>For validating the data (usually against a set of validation rules)
 *  <li>optionally a selection list
 * </ul>
 *
 * <p>Each datatype can be marked as an "arraytype". Currently, this only has an
 * influence on the {@link #validate(Object, ExpressionContext)} method, which should in that case be passed
 * an array of objects. See also {@link #isArrayType()}.
 * 
 * @version $Id$
 */
public interface Datatype {
    /**
     * Converts a string to an object of this datatype. This method uses the
     * same {@link Convertor} as returned by the {@link #getConvertor()} method.
     */
    ConversionResult convertFromString(String value, Locale locale);

    /**
     * Converts an object of this datatype to a string representation.
     * This method uses the same {@link Convertor} as returned by the
     * {@link #getConvertor()} method.
     */
    String convertToString(Object value, Locale locale);

    /**
     * Returns null if validation is successful, otherwise returns a
     * {@link ValidationError} instance.
     *
     * @param value  an Object of the correct type for this datatype (see
     *               {@link #getTypeClass()}, or if {@link #isArrayType()}
     *               returns true, an array of objects of that type.
     */
    ValidationError validate(Object value, ExpressionContext expressionContext);

    /**
     * Gets the class object for the type represented by this datatype. E.g. Long, String, ...
     * The objects returned from the convertFromString* methods are of this type, and the object
     * passed to the convertToString* or validate methods should be of this type.
     */
    Class getTypeClass();

    /**
     * Returns a descriptive name for the base type of this datatype,
     * i.e. something like 'string', 'long', 'decimal', ...
     */
    String getDescriptiveName();

    /**
     * Indicates wether this datatype represents an array type. This approach has been
     * chosen instead of creating a seperate ArrayDatatype interface (and corresponding
     * implementations), since almost all functionality is the same between the scalar
     * and array types. The main difference is that the validate() method will be passed
     * arrays instead of single values, and hence different validation rules will be
     * required.
     */
    boolean isArrayType();

    /**
     * Returns the convertor used by this datatype.
     */
    Convertor getConvertor();

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

    /**
     * Returns the factory that built this datatype.
     */
    DatatypeBuilder getBuilder();

    /**
     * Generates a bit of information about this datatype.
     */
    void generateSaxFragment(ContentHandler contentHandler, Locale locale) throws SAXException;
}