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.AttributeDescriptor;
035 import org.opengis.feature.type.AttributeType;
036 import org.opengis.filter.identity.Identifier;
037
038 /**
039 * An extension of Property for an attribute, or data.
040 * <p>
041 * The notion of an "attribute" is similar to that of an attribute in UML.
042 * </p>
043 * <p>
044 * This interface is capable of modelling "primitive data", things like strings,
045 * numerics, dates, etc... However for "complex data" (that is non-primitive
046 * data types which are made up other primitive data types), a specific
047 * sub-interface is used, see {@link ComplexAttribute}.
048 * </p>
049 * <p>
050 * An analogy for an attribute is a "field" in a java object. A field also
051 * brings together a field name, value and type.
052 * </p>
053 *
054 * <p>
055 * <h3>Identifiable</h3>
056 *
057 * When an attribute is identifiable the {@link #getID()} method returns a
058 * unique identifier for the attribute. The type of the attribute is used to
059 * determine identifiability.
060 *
061 * <pre>
062 * Attribute attribute = ...;
063 * if ( attribute.getType().isIdentified() ) {
064 * String id = attribute.getID();
065 * }
066 * </pre>
067 * </p>
068 * <h3>Validation</h3>
069 *
070 * An attribute may hold any value at runtime; checking that the value meets the constraints
071 * supplied by the AttributeType is the work of the validate() method.
072 *
073 * @see Property
074 *
075 * @author Jody Garnett (Refractions Research)
076 * @author Justin Deoliveira (The Open Planning Project)
077 */
078 public interface Attribute extends Property {
079
080 /**
081 * Override of {@link Property#getDescriptor()} which type narrows to
082 * {@link AttributeDescriptor}.
083 *
084 * @see Property#getDescriptor()
085 * @return The attribute descriptor, may be null if this is a top level type
086 */
087 AttributeDescriptor getDescriptor();
088
089 /**
090 * Override of {@link Property#getType()} which type narrows to
091 * {@link AttributeType}.
092 *
093 * @see Property#getType()
094 * @return The attribute type.
095 */
096 AttributeType getType();
097
098 /**
099 * Unique Identifier for the attribute.
100 * <p>
101 * This value is non-null in the case that
102 * <code>getType().isIdentifiable()</code> is <code>true</code>.
103 * </p>
104 *
105 * @return A unique identifier for the attribute, or <code>null</code> if
106 * the attribute is non-identifiable.
107 */
108 Identifier getIdentifier();
109
110 /**
111 * Check the attribute value against the constraints provided by the AttributeDescriptor.
112 * <p>
113 * Please note this method checks the value only - it should have the correct java binding,
114 * it should only be null if isNillable is true; and if a value is provided it should
115 * satisfy all of the restrictions provided.
116 * <p>
117 * To check the the number of times an attribute is used (minOccurs and maxOccurs) please
118 * use ComplexAttribute.validate().
119 *
120 * @thorws IllegalAttributeException If value fails validation
121 */
122 void validate() throws IllegalAttributeException;
123 }