001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2006-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.feature;
033
034 import org.opengis.feature.type.AssociationDescriptor;
035 import org.opengis.feature.type.AssociationType;
036 import org.opengis.feature.type.AttributeType;
037
038 /**
039 * Extension of Property to represent an Association, or relationship, between two attributes.
040 * <p>
041 * The notion of an "association" is similar to that of an association in UML
042 * and is used to model a relationship between entities.
043 * </p>
044 * Examples of such a relationship could be:
045 * <ul>
046 * <li>aggregation: An attribute may contain another attribute
047 * <li>spatial: A feature is spatial related to another (touches, intersects, etc..)
048 * <li>temporal: An is a previous version of another attribute in a versioning system
049 * </ul>
050 * </p>
051 * <h2>Example</h2>
052 * <p>
053 * The value of an association is an {@link Attribute}. As an example consider
054 * the following xml complex type definitions:
055 * <pre>
056 * <complexType name="fooType">
057 * ...
058 * </complexType>
059 * <element name="foo" type="fooType"/>
060 *
061 * <complexType name="barType">
062 * <sequence>
063 * <element name="intAttribute" type="xs:int"/>
064 * <element name="stringAttribute" type="xs:string"/>
065 * <element name="fooAssociation" type="xlink:href"/>
066 * </sequence>
067 * </complexType>
068 * <element name="bar" type="barType"/>
069 * </pre>
070 * In the above, "fooType" is an identifiable type. Now consider the following
071 * section of an xml instance document:
072 * <pre>
073 * <foo id="someId">
074 * ...
075 * </foo>
076 * ...
077 * <bar>
078 * <intAttribute>1</intAttribute>
079 * <stringAttribute>one</stringAttribute>
080 * <fooAssociation>someId</fooAssociation>
081 * </bar>
082 * </pre>
083 * Realizing this as objects with attributes and associations we get:
084 * <pre>
085 * ComplexAttribute bar = ...;
086 *
087 * //intAttribute
088 * Attribute intAttribute = (Attribute) bar.getProperty( "intAttribute" );
089 * intAttribute.getValue() == 1
090 *
091 * //stringAttribute
092 * Attribute stringAttribute = (Attribute) bar.getProperty( "stringAttribute" );
093 * stringAttribute.getValue() == "one"
094 *
095 * //fooAssociation
096 * Association fooAssociation = (Association) bar.getProperty( "fooAssociation" );
097 * Attribute foo = fooAssociation.getValue();
098 * </pre>
099 * </p>
100 *
101 * @author Jody Garnett, Refractions Research
102 * @author Justin Deoliveira, The Open Planning Project
103 */
104 public interface Association extends Property {
105
106 /**
107 * Description of the relationship between two attributes.
108 *
109 * Override of {@link Property#getDescriptor()} which type narrows to
110 * {@link AssociationDescriptor}.
111 *
112 * @see Property#getDescriptor()
113 * @return AssociationDescriptor used to describe the relationship between two attributes; because
114 * two attributes are required the descriptor should not be null.
115 */
116 AssociationDescriptor getDescriptor();
117
118 /**
119 * Type of association represented.
120 * <p>
121 *
122 * Override of {@link Property#getType()} which type narrows to
123 * {@link AssociationType}.
124 *
125 * @see Property#getType()
126 */
127 AssociationType getType();
128
129 /**
130 * Override of {@link Property#getValue()} which type narrows to
131 * {@link Attribute}.
132 *
133 * @see Property#getValue()
134 */
135 Attribute getValue();
136
137 /**
138 * Override of {@link Property#setValue(Object)} which specifies that
139 * <tt>newValue</tt> should be an instance of {@link Attribute}.
140 *
141 * @throws IllegalArgumentException If <tt>newValue</tt> is not an attribute.
142 */
143 void setValue(Object newValue) throws IllegalArgumentException;
144
145 /**
146 * Returns the type of the associated attribute.
147 * <p>
148 * This method is a convenience for:
149 * <pre>
150 * getType().getRelatedType()
151 * </pre>
152 * <p>
153 *
154 * @return type of the attribute of the association.
155 */
156 AttributeType getRelatedType();
157 }