001    //$HeadURL: svn+ssh://jwilden@svn.wald.intevation.org/deegree/base/branches/2.5_testing/src/org/deegree/model/feature/Feature.java $
002    /*----------------------------------------------------------------------------
003     This file is part of deegree, http://deegree.org/
004     Copyright (C) 2001-2009 by:
005       Department of Geography, University of Bonn
006     and
007       lat/lon GmbH
008    
009     This library is free software; you can redistribute it and/or modify it under
010     the terms of the GNU Lesser General Public License as published by the Free
011     Software Foundation; either version 2.1 of the License, or (at your option)
012     any later version.
013     This library is distributed in the hope that it will be useful, but WITHOUT
014     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
015     FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
016     details.
017     You should have received a copy of the GNU Lesser General Public License
018     along with this library; if not, write to the Free Software Foundation, Inc.,
019     59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
020    
021     Contact information:
022    
023     lat/lon GmbH
024     Aennchenstr. 19, 53177 Bonn
025     Germany
026     http://lat-lon.de/
027    
028     Department of Geography, University of Bonn
029     Prof. Dr. Klaus Greve
030     Postfach 1147, 53001 Bonn
031     Germany
032     http://www.geographie.uni-bonn.de/deegree/
033    
034     e-mail: info@deegree.org
035    ----------------------------------------------------------------------------*/
036    
037    package org.deegree.model.feature;
038    
039    import java.util.Map;
040    
041    import org.deegree.datatypes.QualifiedName;
042    import org.deegree.io.datastore.PropertyPathResolvingException;
043    import org.deegree.model.feature.schema.FeatureType;
044    import org.deegree.model.spatialschema.Envelope;
045    import org.deegree.model.spatialschema.Geometry;
046    import org.deegree.model.spatialschema.GeometryException;
047    import org.deegree.ogcbase.PropertyPath;
048    
049    /**
050     * Features are, according to the Abstract Specification, digital representations of real world
051     * entities. Feature Identity thus refers to mechanisms to identify such representations: not to
052     * identify the real world entities that are the subject of a representation. Thus two different
053     * representations of a real world entity (say the Mississippi River) will be two different features
054     * with distinct identities. Real world identification systems, such as title numbers, while
055     * possibly forming a sound basis for an implementation of a feature identity mechanism, are not of
056     * themselves such a mechanism.
057     *
058     * @author <a href="mailto:poth@lat-lon.de">Andreas Poth</a>
059     * @author <a href="mailto:mschneider@lat-lon.de">Markus Schneider</a>
060     * @version $Revision: 18195 $ $Date: 2009-06-18 17:55:39 +0200 (Do, 18 Jun 2009) $
061     */
062    public interface Feature {
063    
064        /**
065         * Returns the qualified name of the feature.
066         *
067         * @return the qualified name of the feature
068         */
069        QualifiedName getName();
070    
071        /**
072         * Returns the description of the feature.
073         *
074         * @return the description of the feature.
075         */
076        String getDescription();
077    
078        /**
079         * Returns the id of the feature.
080         *
081         * @return the id of the feature
082         */
083        String getId();
084    
085        /**
086         * Sets the id of the feature.
087         *
088         * @param fid
089         *            the id of the feature to be set
090         */
091        void setId( String fid );
092    
093        /**
094         * Returns the feature type of this feature.
095         *
096         * @return the feature type of this feature
097         */
098        FeatureType getFeatureType();
099    
100        /**
101         * Sets the feature type of this feature.
102         *
103         * @param ft
104         *            feature type to set
105         */
106        void setFeatureType( FeatureType ft );
107    
108        /**
109         * Returns all properties of the feature in their original order.
110         *
111         * @return all properties of the feature
112         */
113        FeatureProperty[] getProperties();
114    
115        /**
116         * Returns the first property of the feature with the given name.
117         *
118         * @param name
119         *            name of the property to look up
120         * @return the first property of the feature with the given name or null if the feature has no
121         *         such property
122         */
123        FeatureProperty getDefaultProperty( QualifiedName name );
124    
125        /**
126         * Returns the property of the feature identified by the given {@link PropertyPath}.
127         *
128         * NOTE: Current implementation does not handle multiple properties (on the path) or index
129         * addressing in the path.
130         *
131         * @param path
132         *            the path of the property to look up
133         * @return the property of the feature identified by the given PropertyPath
134         * @throws PropertyPathResolvingException
135         *
136         * @see PropertyPath
137         */
138        FeatureProperty getDefaultProperty( PropertyPath path )
139                                throws PropertyPathResolvingException;
140    
141        /**
142         * Returns the properties of the feature with the given name in their original order.
143         *
144         * @param name
145         *            name of the properties to look up
146         * @return the properties of the feature with the given name or null if the feature has no
147         *         property with that name
148         */
149        FeatureProperty[] getProperties( QualifiedName name );
150    
151        /**
152         * Returns the properties of the feature at the submitted index of the feature type definition.
153         *
154         * @param index
155         *            index of the properties to look up
156         * @return the properties of the feature at the submitted index
157         * @deprecated
158         */
159        @Deprecated
160        FeatureProperty[] getProperties( int index );
161    
162        /**
163         * Returns the values of all geometry properties of the feature.
164         *
165         * @return the values of all geometry properties of the feature, or a zero-length array if the
166         *         feature has no geometry properties
167         */
168        Geometry[] getGeometryPropertyValues();
169    
170        /**
171         * Returns the value of the default geometry property of the feature. If the feature has no
172         * geometry property, this is a Point at the coordinates (0,0).
173         *
174         * @return default geometry or Point at (0,0) if feature has no geometry
175         */
176        Geometry getDefaultGeometryPropertyValue();
177    
178        /**
179         * Sets the value for the given property. The index is needed to specify the occurences of the
180         * property that is to be replaced. Set to 0 for properties that may only occur once.
181         *
182         * @param property
183         *            property name and the property's new value
184         * @param index
185         *            position of the property that is to be replaced
186         */
187        void setProperty( FeatureProperty property, int index );
188    
189        /**
190         * Adds the given property to the feature's properties. The position of the property is
191         * determined by the feature type. If the feature already has a property with this name, it is
192         * inserted behind it.
193         *
194         * @param property
195         *            property to insert
196         */
197        void addProperty( FeatureProperty property );
198    
199        /**
200         * Removes the properties with the given name.
201         *
202         * @param propertyName
203         *            name of the properties to remove
204         */
205        void removeProperty( QualifiedName propertyName );
206    
207        /**
208         * Replaces the given property with a new one.
209         *
210         * @param oldProperty
211         *            property to be replaced
212         * @param newProperty
213         *            new property
214         */
215        void replaceProperty( FeatureProperty oldProperty, FeatureProperty newProperty );
216    
217        /**
218         * Returns the envelope / bounding box of the feature.
219         *
220         * @return the envelope / bounding box of the feature
221         * @throws GeometryException
222         */
223        Envelope getBoundedBy()
224                                throws GeometryException;
225    
226        /**
227         * Returns the owner of the feature. This is the feature property that has this feature as value
228         * or null if this feature is a root feature.
229         *
230         * @return the owner of the feature, or null if the feature does not belong to a feature
231         *         property
232         */
233        FeatureProperty getOwner();
234    
235        /**
236         * Returns the attribute value of the attribute with the specified name.
237         *
238         * @param name
239         *            name of the attribute
240         * @return the attribute value
241         */
242        String getAttribute( String name );
243    
244        /**
245         * Returns all attributes of the feature.
246         *
247         * @return all attributes, keys are names, values are attribute values
248         */
249        Map<String, String> getAttributes();
250    
251        /**
252         * Sets the value of the attribute with the given name.
253         *
254         * @param name
255         *            name of the attribute
256         * @param value
257         *            value to set
258         */
259        void setAttribute( String name, String value );
260    
261        /**
262         * Signals that the envelopes of the geometry properties have been updated.
263         */
264        public void setEnvelopesUpdated();
265    
266        /**
267         * @return a shallow clone of a feature. Property values will not be cloned except for
268         *         properties that are features (DefaultFeature) or feature collections
269         *         (DefaultFeatureCollection)
270         */
271        public Object clone() throws CloneNotSupportedException;
272    
273        /**
274         * @return a deep clone of a feature. All not simple properties (incl. geometries) will be cloned
275         */
276        public Feature cloneDeep() throws CloneNotSupportedException;
277    
278    }