001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-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.geometry.complex;
033
034 import java.util.Collection;
035 import org.opengis.geometry.Geometry;
036 import org.opengis.geometry.primitive.Point; // For javadoc
037 import org.opengis.geometry.primitive.Primitive; // For javadoc
038 import org.opengis.annotation.UML;
039
040 import static org.opengis.annotation.Obligation.*;
041 import static org.opengis.annotation.Specification.*;
042
043
044 /**
045 * A collection of geometrically disjoint, simple {@linkplain Primitive primitives}. If a
046 * {@linkplain Primitive primitive} (other than a {@linkplain Point point} is in a particular
047 * {@code Complex}, then there exists a set of primitives of lower dimension in the same complex
048 * that form the boundary of this primitive.
049 * <p>
050 * A geometric complex can be thought of as a set in two distinct ways. First, it is a finite set
051 * of objects (via delegation to its elements member) and, second, it is an infinite set of point
052 * values as a subtype of geometric object. The dual use of delegation and subtyping is to
053 * disambiguate the two types of set interface. To determine if a {@linkplain Primitive primitive}
054 * <var>P</var> is an element of a {@code Complex} <var>C</var>,
055 * call: {@code C.element().contains(P)}.
056 * <p>
057 * The "{@linkplain #getElements elements}" attribute allows {@code Complex} to inherit the
058 * behavior of {@link Set Set<Primitive>} without confusing the same sort of behavior
059 * inherited from {@link org.opengis.geometry.TransfiniteSet TransfiniteSet<DirectPosition>}
060 * inherited through {@link Geometry}. Complexes shall be used in application schemas where
061 * the sharing of geometry is important, such as in the use of computational topology. In a
062 * complex, primitives may be aggregated many-to-many into composites for use as attributes
063 * of features.
064 *
065 * @version <A HREF="http://www.opengeospatial.org/standards/as">ISO 19107</A>
066 * @author Martin Desruisseaux (IRD)
067 * @since GeoAPI 1.0
068 *
069 * @todo Some associations are commented out for now.
070 */
071 @UML(identifier="GM_Complex", specification=ISO_19107)
072 public interface Complex extends Geometry {
073 /**
074 * Returns {@code true} if and only if this {@code Complex} is maximal.
075 * A complex is maximal if it is a subcomplex of no larger complex.
076 *
077 * @return {@code true} if this complex is maximal.
078 */
079 @UML(identifier="isMaximal", obligation=MANDATORY, specification=ISO_19107)
080 boolean isMaximal();
081
082 /**
083 * Returns a superset of primitives that is also a complex.
084 *
085 * @return The supercomplexes, or an empty array if none.
086 *
087 * @todo Consider using a Collection return type instead.
088 */
089 @UML(identifier="superComplex", obligation=MANDATORY, specification=ISO_19107)
090 Complex[] getSuperComplexes();
091
092 /**
093 * Returns a subset of the primitives of that complex
094 * that is, in its own right, a geometric complex.
095 *
096 * @return The subcomplexes, or an empty array if none.
097 *
098 * @todo Consider using a Collection return type instead.
099 */
100 @UML(identifier="subComplex", obligation=MANDATORY, specification=ISO_19107)
101 Complex[] getSubComplexes();
102
103 /**
104 * Returns the collection of primitives contained in this complex.
105 *
106 * @return The collection of primitives for this complex.
107 */
108 @UML(identifier="element", obligation=MANDATORY, specification=ISO_19107)
109 Collection<? extends Primitive> getElements();
110
111 // public org.opengis.topology.complex.TP_Complex topology[];
112 }