org.opengis.feature.Property Maven / Gradle / Ivy

/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 *
 *    (C) 2011, Open Source Geospatial Foundation (OSGeo)
 *    (C) 2004-2007 Open Geospatial Consortium Inc.
 *
 *    All Rights Reserved. http://www.opengis.org/legal/
 */
package org.opengis.feature;

import java.util.Map;
import org.opengis.feature.type.Name;
import org.opengis.feature.type.PropertyDescriptor;
import org.opengis.feature.type.PropertyType;

/**
 * An instance of a {@link PropertyType} relised as a {@link Attribute} or {@link Association}.
 *
 * A property is a wrapper around an arbitrary object or value. The value is available via the
 * {@link #getValue()} and {@link #setValue(Object)}.
 *
 * 
 *  Property property = ...;
 *
 *  //set the value
 *  property.setValue( "foo" );
 *
 *  //get the value
 *  String value = (String) property.getValue();
 * 
 *
 * Every property has a type. This {@link PropertyType} defines information about the property.
 * This includes which java class the value of the property is an instance of, any restrictions on
 * the value, etc... The type is available via the {@link #getType()} method.
 *
 * 
 *   Property property = ...;
 *
 *   //get the type
 *   PropertyType type = property.getType();
 *
 *   //get the class of the value
 *   Class<String> valueClass = (Class<String>)type.getBinding();
 *
 * 
 *
 * A property can often be part of another entity such as a {@link Feature} or {@link
 * ComplexAttribute}. When this is the case, the relationship between the property and its
 * "container" is described by a {@link PropertyDescriptor}. The descriptor of a property defines
 * things like nilablility, multiplicity, etc... See the javadoc of {@link PropertyDescriptor} for
 * more details. The descriptor is available via the {@link #getDescriptor()} method.
 *
 * 
 *   Property property = ...;
 *
 *   //get the descriptor
 *   PropertyDescriptor descriptor = property.getDescriptor()l
 *
 *   //is the value allowed to be null?
 *   descriptor.isNillable();
 *
 *   //how many instances of this property are allowed?
 *   descriptor.getMaxOccurs();
 * 
 *
 * @author Jody Garnett (Refractions Research)
 * @author Justin Deoliveira (The Open Planning Project)
 */
public interface Property {

    /**
     * The value or content of the property.
     *
     * The class of this object is defined by getType().getBinding().
     *
     * 
This value may be null. In this case getDescriptor().isNillable()
     *  would be true.
     *
     * @return The value of the property.
     */
    Object getValue();

    /**
     * Sets the value or content of the property.
     *
     * 
The class of newValue should be the same as or a subclass of 
     * getType().getBinding().
     *
     * 
newValue may be null if getDescriptor().isNillable() is
     * true.
     *
     * @param newValue The new value of the property.
     */
    void setValue(Object newValue);

    /**
     * The type of the property.
     *
     * 
The type contains information about the value or content of the property such as its java
     * class.
     *
     * 
This value is also available via getDescriptor().getType().
     *
     * @return The property type.
     */
    PropertyType getType();

    /**
     * The {@link PropertyDscriptor} of the property, null if this is a top-level value.
     *
     * 
The descriptor provides information about the property with respect to its containing
     * entity (more often then not a {@link Feature} or {@link ComplexAttribute}.
     *
     * @return The property descriptor, null if this is a top-level value.
     * @see ComplexAttribute
     */
    PropertyDescriptor getDescriptor();

    /**
     * The name of the property with respect to its descriptor.
     *
     * 
This method is convenience for getDescriptor().getName().
     *
     * @return name of the property.
     */
    Name getName();

    /**
     * Flag indicating if null is an acceptable value for the property.
     *
     * 
This method is convenience for getDescriptor().isNillable().
     *
     * @return true if the value of the property is allowed to be null,
     *     otherwise false.
     */
    boolean isNillable();

    /**
     * A map of "user data" which enables applications to store "application-specific" information
     * against a property.
     *
     * 
An example of information that may wish to be stored along with an attribute could be its
     * srs information (in the case of a geometric attribute ).
     *
     * 
     * 
     *  GeometryAttribute attribute = ...;
     *
     *  //set the crs
     *  CoordinateReferenceSystem crs = CRS.decode("EPSG:4326");
     *  attribute.setCRS( crs );
     *
     *  //set the srs
     *  attribute.getUserData().put( "srs", "EPSG:4326" );
     * 
     * 
     *
     * @return A map of user data.
     */
    Map getUserData();

    /**
     * Returns true if the property has a user data map. Can be used to avoid instantiation of Map
     * object in cases where the main code paths won't have any.
     *
     * @return True if there is any user data, false otherwise
     */
    default boolean hasUserData() {
        return !getUserData().isEmpty();
    }
}