org.opengis.feature.ComplexAttribute 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.Collection;
import org.opengis.feature.type.ComplexType;
import org.opengis.feature.type.Name;
import org.opengis.filter.expression.Expression;

/**
 * An instance of {@link ComplexType} which is composed of other properties.
 *
 * A complex attribute is a container for other properties (attributes + associations). The value
 * of a complex attribute is a collection of those contained properties. 

 *
 * 

 *
 * 
Property Access
 *
 * The {@link #getValue()} method returns a collection of the properties contained by the complex
 * attribute.
 *
 *  *    ComplexAttribute attribute = ...;
 *
 *    //loop through all the properties
 *    for (Property p : attribute.getValue(); ) {
 *        // do something with the property
 *    }
 * 
 *
 * 

 * Contained properties can also be fetched by name by {@link Name} with the {@link
 * #getProperties(Name)} and {@link #getProperties(String)} methods.
 *
 *  *    ComplexAttribute attribute = ...;
 *
 *    //loop through all the "foo" attributes
 *    for ( Property p : attribute.getProperties( "foo" ) ) {
 *        p.getName().getLocalPart() == "foo";
 *    }
 * 
 *
 * 

 * Often it is known in advance that a single instance of a particular property exists. When this is
 * the case the {@link #getProperty(Name)} and {@link #getProperty(String)} methods can be used to
 * get direct access to the property.
 *
 *  *    ComplexAttribute attribute = ...;
 *
 *    //get the single foo attribute
 *    Property foo = attribute.getProperty( "foo" );
 * 
 *
 * 

 *
 * 
 *
 * 
Xpath and Query Language Access
 *
 * The above property access methods perform an exact match on property name against the name passed
 * in. However, often it is necesary to access properties via a query language such as xpath. 

 *
 * For instance.the expression "//foo" should return all the properties named "foo".
 * Or the expression "foo/bar" should return the "bar" property nested inside of the
 * "foo" property. In these cases, an {@link Expression} must be used:
 *
 * 
 *   ComplexAttribute attribute = ...;
 *
 *   //get the 'foo/bar' property
 *   FilterFactory factory = ...;
 *   PropertyName xpath = factory.property( "foo/bar" );
 *   Property bar = xpath.evaluate( attribute );
 * 
 *
 * @author Jody Garnett, Refractions Research
 * @author Gabriel Roldan, Axios Engineering
 * @author Justin Deoliveira, The Open Planning Project
 */
public interface ComplexAttribute extends Attribute {

    /**
     * Override of {@link Attribute#getType()} which type narrows to {@link ComplexType}.
     *
     * @see Attribute#getType()
     */
    ComplexType getType();

    /**
     * Sets the contained properties of the complex attribute.
     *
     * The values should match the structure defined by getDescriptor().
     */
    void setValue(Collection values);

    /**
     * Override of {@link Property#getValue()} which returns the collection of {@link Property}
     * which make up the value of the complex attribute.
     */
    Collection getValue();

    /**
     * Returns a subset of the properties of the complex attribute which match the specified name.
     *
     * 
The name parameter is matched against each contained {@link Property#getName()},
     * those that are equal are returned.
     *
     * @param name The name of the properties to return.
     * @return The collection of properties which match the specified name, or an empty collection
     *     if no such properties match.
     */
    Collection getProperties(Name name);

    /**
     * Returns single property of the complex attribute which matches the specified name.
     *
     * 
Note: This method is a convenience and care should be taken when calling it if more then a
     * single property matches name. In such a case the first encountered property in which
     * {@link Property#getName()} is equal to name is returned, and no order is guaranteed.
     *
     * 
This method is a safe convenience for: getProperties(name).iterator().next().
     *
     * 
In the event that no property matches the specified name null is returned.
     *
     * @param name The name of the property to return.
     * @return The property matching the specified name, or null.
     */
    Property getProperty(Name name);

    /**
     * Returns a subset of the properties of the complex attribute which match the specified name.
     *
     * 
This method is a convenience for {@link #getProperties(Name)} in which {@link
     * Name#getNamespaceURI()} is null.
     *
     * 
Note: Special care should be taken when using this method in the case that two properties
     * with the same local name but different namespace uri exist. For this reason using {@link
     * #getProperties(Name)} is safer.
     *
     * @param name The local name of the properties to return.
     * @return The collection of properties which match the specified name, or an empty collection
     *     if no such properties match.
     * @see #getProperties(Name)
     */
    Collection getProperties(String name);

    /**
     * Complete collection of properties.
     *
     * 
This method is a convenience method for calling (Collection) getValue().
     *
     * @return The complete collection of properties.
     */
    Collection getProperties();

    /**
     * Returns single property of the complex attribute which matches the specified name.
     *
     * 
This method is a convenience for {@link #getProperty(Name)} in which {@link
     * Name#getNamespaceURI()} is null.
     *
     * 
Note: This method is a convenience and care should be taken when calling it if more then a
     * single property matches name. In such a case the first encountered property in which
     * {@link Property#getName()} is matches name is returned, and no order is guaranteed.
     *
     * 
Note: Special care should be taken when using this method in the case that two properties
     * with the same local name but different namespace uri exist. For this reason using {@link
     * #getProperties(Name)} is safer.
     *
     * @param name The local name of the property to return.
     * @return The property matching the specified name, or null.
     */
    Property getProperty(String name);

    /**
     * Check the properties against the constraints provided by their AttributeDescriptors.
     *
     * Please note this method checks minOccurs and maxOccurs information; and calls each
     * Attribute.validate on each entry in turn (in order to check isNillable, binding and
     * restrictions).
     *
     * @throws IllegalAttributeException If any attribute fails validation
     */
    void validate() throws IllegalAttributeException;
}