Application: gvSIG desktop » Library: org.gvsig.tools

package org.gvsig.tools.dynobject;

import java.util.List;

import org.gvsig.tools.dataTypes.CoercionException;

import org.gvsig.tools.dynobject.exception.DynFieldIsNotAContainerException;

import org.gvsig.tools.dynobject.exception.DynFieldValidateException;

/**

 * A field of a {@link DynObject}.

 * <p>

 * A field will be persisted only if it is set as persistent (@see

 * {@link DynField#isPersistent()}, which is the default value.

 * </p>

 * 

 * @author <a href="mailto:jjdelcerro@gvsig.org">Joaqu�n Jos� del Cerro</a>

 */

public interface DynField {

        /**

         * If the field value can be any possible value, for its type.

         * 

         * @deprecated now autodetect the mode of use

         */

        static final int ANY = 1;

        /**

         * If the field value must be one of a list of posible values.

         * 

         * @deprecated usado automaticamente al asignar AvailableValues 

         */

    static final int CHOICE = 2;

        /**

         * If the field value must pertain to a range of possible values.

         * 

         * @deprecated usado automaticamente al asignar minValue/maxValue

         */

    static final int RANGE = 3;

        String getName();

        int getType();

        String getSubtype();

        String getDescription();

        Object getDefaultValue();

        boolean isMandatory();

        String getGroup();

        int getOder();

        /**

         * Returns if the field is persistent or volatile. The meaning of being

         * persistent depends on how is persisted, but any persistence mechanism

         * must avoid persisting this field value.

         * @return if the field is to be persisted or not

         */

        boolean isPersistent();

        boolean isHidden();

        /**

         * @deprecated don't use, check minValue/maxValue and getAvailableValues instead 

         */

        int getTheTypeOfAvailableValues(); // SINGLE, CHOICE o RANGE

        DynObjectValueItem[] getAvailableValues();

        Object getMinValue();

        Object getMaxValue();

        Class getClassOfValue();

        DynField setDescription(String description);

        DynField setType(int type);

        DynField setSubtype(String subtype);

        DynField setDefaultDynValue(Object defaultValue);

        DynField setMandatory(boolean mandatory);

        DynField setGroup(String groupName);

        DynField setHidden(boolean hidden);

        DynField setOrder(int order);

        /**

         * Sets if the field must be persisted or not.

         * @see #isPersistent()

         * @param persistent if the field must be persisted or not

         * @return this same {@link DynField} object

         */

        DynField setPersistent(boolean persistent);

        /**

         * @deprecated don't use, set minValue/maxValue and availableValues instead 

         */

        DynField setTheTypeOfAvailableValues(int type);

        DynField setAvailableValues(DynObjectValueItem[] values);

        DynField setAvailableValues(List values);

        DynField setMinValue(Object minValue);

        DynField setMaxValue(Object maxValue);

        /**

         * When a field is type object, this is the class of the object.

         * If field type is List, Set or Map, this class is the class of items.

         * 

         * @param theClass

         * @return this same {@link DynField} object

         * @throws DynFieldIsNotAContainerException

         */

        DynField setClassOfValue(Class theClass) throws DynFieldIsNotAContainerException;

        /**

         * Validate that the value match the properties of the field.

         * 

         * @param value

         * @throws DynFieldValidateException

         */

        void validate(Object value) throws DynFieldValidateException;

        /**

         * Force the type of value to the type of the field.

         * 

         * @param value

         * @return new value

         * @throws CoercionException 

         */

        Object coerce(Object value) throws CoercionException;

        /**

         * When a field is of type container, this method return a DynClass

         * that define the type of elements. 

          * When the type is DYNOBJECT return the DynClass associated

          * to this.

         * 

         * Return null if the type not is a container.

         * 

         * @return DynClass that define the type of elements.

         */

        public DynStruct getElementsType();

        /**

          * Set the type of items when the field is a container.

          * When the type is DYNOBJECT is the DynClass associated

          * to this.

          * 

         * @param definition

         * @return this same {@link DynField} object

         * @throws DynFieldIsNotAContainerException

         */

        public DynField setElementsType(DynStruct definition) throws DynFieldIsNotAContainerException ;

        /**

         * Create a DynClass and asociate to the elements of this

         * container field and return the unique field defined in this

         * DynClass.

         *  

         *  This method is a utility method for define the type

         *  of elements of a container when this elements are

         *  basic types and not compound objects.

         *  

         *  The name of the DynField and DynClass created are

         *  the same as this field.

         *  

         * @return DynField that define the type of elements.

         * @throws DynFieldIsNotAContainerException

         */

        public DynField addElementsType() throws DynFieldIsNotAContainerException ;

}