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.type;
033
034 import java.util.Map;
035
036 import org.opengis.feature.ComplexAttribute;
037
038 /**
039 * Describes a Property, and how it relates to its containing entity, which is
040 * often a {@link ComplexAttribute}.
041 * <br>
042 * <p>
043 * A property descriptor defines the following about the property:
044 * <ul>
045 * <li>type of the property
046 * <li>the name of the property
047 * <li>number of allowable occurrences of the property
048 * <li>nilability of the property
049 * </ul>
050 * </p>
051 * <br>
052 * <p>
053 * The concept of a descriptor is similar to that of a element declaration in
054 * xml. Consider the following xml schema definition:
055 * <pre>
056 * <complexType name="someComplexType">
057 * <sequence>
058 * <element name="foo" minOccurs="2" maxOccurs="4" type="xs:string" nillable="false"/>
059 * <sequence>
060 * <complexType>
061 * </pre>
062 * <br>
063 * In the above, the element declaration named "foo" maps to a property descriptor.
064 * From the above schema, the following property descriptor would result:
065 * <pre>
066 * //the complex type
067 * ComplexType complexType = ...;
068 *
069 * //get the descriptor
070 * PropertyDescriptor descriptor = complexType.getProperty( "foo" );
071 *
072 * //make the following assertions
073 * descriptor.getName().getLocalPart().equals( "foo" );
074 *
075 * descriptor.getType().getName().getNamespaceURI().equals( "http://www.w3.org/2001/XMLSchema" )
076 * descriptor.getType().getName().getLocalPart().equals( "string" );
077 * descriptor.getMinOccurs() == 2;
078 * descriptor.getMaxOccurs() == 4;
079 * descriptor.isNillable() == true;
080 *
081 * //the complex attribute
082 * ComplexAttribute complexAttribute = ...
083 * complexAttribute.getType() == complexType;
084 *
085 * //get the properties
086 * Collection properties = complexAttribute.getProperties( "foo" );
087 *
088 * //make assertions about properties
089 * properties.size() >= 2; //minOccurs = 2
090 * properties.size() <= 4; //maxOccurs = 4
091 *
092 * for ( Property p : properties ) {
093 * p.getDescriptor() == descriptor
094 *
095 * p.getValue() != null; //nilable = false
096 * p.getType().getBinding() == String.class; //type = xs:string
097 * p.getValue() instanceof String; //type = xs:string
098 * }
099 * </pre>
100 * <p>
101 *
102 * @author Jody Garnett, Refractions Research
103 * @author Justin Deoliveira, The Open Planning Project
104 */
105 public interface PropertyDescriptor {
106 /**
107 * The type of the property defined by the descriptor.
108 * <p>
109 * This value should never be <code>null</code>. The type contains information
110 * about the value of the property such as its java class.
111 * </p>
112 */
113 PropertyType getType();
114
115 /**
116 * The name of the property defined by the descriptor, with respect to its
117 * containing type or entity..
118 * <p>
119 * This value may be <code>null</code> in some instances. Also note that this
120 * is not the same name as <code>getType().getName()</code>. The former is
121 * the name of the instance, the latter is the name of the type of the
122 * instance.
123 * </p>
124 */
125 Name getName();
126
127 /**
128 * The minimum number of occurrences of the property within its containing
129 * entity.
130 * <p>
131 * This value is always an integer greater than or equal to zero.
132 * </p>
133 * @return An integer >= 0
134 */
135 int getMinOccurs();
136
137 /**
138 * The maximum number of occurrences of the property within its containing
139 * entity.
140 * <p>
141 * This value is a positive integer. A value of <code>-1</code> means that
142 * the max number of occurrences is unbounded.
143 * </p>
144 * @return An integer >= 0, or -1.
145 */
146 int getMaxOccurs();
147
148 /**
149 * Flag indicating if <code>null</code> is an allowable value for the
150 * property.
151 *
152 * @return <code>true</code> if the property is allowed to be <code>null</code>,
153 * otherwise <code>false</code>.
154 */
155 boolean isNillable();
156
157 /**
158 * A map of "user data" which enables applications to store "application-specific"
159 * information against a property descriptor.
160 *
161 * @return A map of user data.
162 */
163 Map<Object,Object> getUserData();
164 }