Association.java example

Explorer
geotools-old-master
/*
 *    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 org.opengis.feature.type.AssociationDescriptor;
import org.opengis.feature.type.AssociationType;
import org.opengis.feature.type.AttributeType;

/**
 * Extension of Property to represent an Association, or relationship, between two attributes.
 * <p>
 * The notion of an "association" is similar to that of an association in UML
 * and is used to model a relationship between entities.
 * </p>
 * Examples of such a relationship could be:
 * <ul>
 * <li>aggregation: An attribute may contain another attribute
 * <li>spatial: A feature is spatial related to another (touches, intersects, etc..)
 * <li>temporal: An is a previous version of another attribute in a versioning system
 * </ul>
 * </p>
 * <h2>Example</h2>
 * <p>
 * The value of an association is an {@link Attribute}. As an example consider
 * the following xml complex type definitions:
 * <pre>
 *   <complexType name="fooType">
 *     ...
 *   </complexType>
 *   <element name="foo" type="fooType"/>
 *
 *   <complexType name="barType">
 *     <sequence>
 *       <element name="intAttribute" type="xs:int"/>
 *       <element name="stringAttribute" type="xs:string"/>
 *       <element name="fooAssociation" type="xlink:href"/>
 *     </sequence>
 *   </complexType>
 *   <element name="bar" type="barType"/>
 * </pre>
 * In the above, "fooType" is an identifiable type. Now consider the following
 * section of an xml instance document:
 * <pre>
 *   <foo id="someId">
 *     ...
 *   </foo>
 *   ...
 *   <bar>
 *     <intAttribute>1</intAttribute>
 *     <stringAttribute>one</stringAttribute>
 *     <fooAssociation>someId</fooAssociation>
 *   </bar>
 * </pre>
 * Realizing this as objects with attributes and associations we get:
 * <pre>
 *   ComplexAttribute bar = ...;
 *
 *   //intAttribute
 *   Attribute intAttribute = (Attribute) bar.getProperty( "intAttribute" );
 *   intAttribute.getValue() == 1
 *
 *   //stringAttribute
 *   Attribute stringAttribute = (Attribute) bar.getProperty( "stringAttribute" );
 *   stringAttribute.getValue() == "one"
 *
 *   //fooAssociation
 *   Association fooAssociation = (Association) bar.getProperty( "fooAssociation" );
 *   Attribute foo =  fooAssociation.getValue();
 * </pre>
 * </p>
 * 
 * @author Jody Garnett, Refractions Research
 * @author Justin Deoliveira, The Open Planning Project
 *
 * @source $URL: http://svn.osgeo.org/geotools/trunk/modules/library/opengis/src/main/java/org/opengis/feature/Association.java $
 */
public interface Association extends Property {

    /**
     * Description of the relationship between two attributes.
     * 
     * Override of {@link Property#getDescriptor()} which type narrows to
     * {@link AssociationDescriptor}.
     *
     * @see Property#getDescriptor()
     * @return AssociationDescriptor used to describe the relationship between two attributes; because
     *         two attributes are required the descriptor should not be null.
     */
    AssociationDescriptor getDescriptor();

     /**
      * Type of association represented.
      * <p>
      * 
     * Override of {@link Property#getType()} which type narrows to
     * {@link AssociationType}.
     *
     * @see Property#getType()
     */
    AssociationType getType();

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

    /**
     * Override of {@link Property#setValue(Object)} which specifies that
     * <tt>newValue</tt> should be an instance of {@link Attribute}.
     *
     * @throws IllegalArgumentException If <tt>newValue</tt> is not an attribute.
     */
    void setValue(Object newValue) throws IllegalArgumentException;

    /**
     * Returns the type of the associated attribute.
     * <p>
     * This method is a convenience for:
     * <pre>
     * getType().getRelatedType()
     * </pre>
     * <p>
     *
     * @return type of the attribute of the association.
     */
    AttributeType getRelatedType();
}