org.opengis.feature.Association 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 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.
 *
 * The notion of an "association" is similar to that of an association in UML and is used to
 * model a relationship between entities. Examples of such a relationship could be:
 *
 * 

 *   aggregation: An attribute may contain another attribute
 *   
spatial: A feature is spatial related to another (touches, intersects, etc..)
 *   
temporal: An is a previous version of another attribute in a versioning system
 * 
 *
 * Example
 *
 * The value of an association is an {@link Attribute}. As an example consider the following xml
 * complex type definitions:
 *
 * 
 *   <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"/>
 * 
 *
 * In the above, "fooType" is an identifiable type. Now consider the following section of an xml
 * instance document:
 *
 *  *   <foo id="someId">
 *     ...
 *   </foo>
 *   ...
 *   <bar>
 *     <intAttribute>1</intAttribute>
 *     <stringAttribute>one</stringAttribute>
 *     <fooAssociation>someId</fooAssociation>
 *   </bar>
 * 
 *
 * Realizing this as objects with attributes and associations we get:
 *
 *  *   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();
 * 
 *
 * @author Jody Garnett, Refractions Research
 * @author Justin Deoliveira, The Open Planning Project
 */
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.
     *
     * 
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 newValue should
     * be an instance of {@link Attribute}.
     *
     * @throws IllegalArgumentException If newValue is not an attribute.
     */
    void setValue(Object newValue) throws IllegalArgumentException;

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