Java Doc for FeatureCollection.java in  » GIS » GeoTools-2.4.1 » org » geotools » feature » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Implementations (and client code) should adhere to the rules set forth by java.util.Collection. That is, some methods are optional to implement, and may throw an UnsupportedOperationException.

FeatureCollection house rules:

• FeatureCollection.close( iterator ) must be called (see example below)
• Features are not specifically ordered within the FeatureCollection (see FeatureList)
• Two instances cannot exist with the same Feature ID (Feature contract)
• (unsure) the same Instance can be in the collection more then once

Life Cycle of Iterator

We have also adopted an additional constraint on the use of iterator. You must call FeatureCollection.close( iterator ) to allow FeatureCollection to clean up any operating system resources used to acces information.

Example (safe) use:

 Iterator iterator = collection.iterator();
 try {
 for( Iterator i=collection.iterator(); i.hasNext();){
 Feature feature = (Feature) i.hasNext();
 System.out.println( feature.getID() );
 }
 }
 finally {
 collection.close( iterator );
 }
 

Handy Tip: Although many resource backed collections will choose to release resources at when the iterator has reached the end of its contents this is not something you should rely on.

Notes for FeatureCollection Implementors

Many users will be treating this as a straight forward Collection, there code will break often enough due to latency - try and close up resources for them when you can detect that an Iterator is not useful anymore.

Collections are used in two fashions, basically as you see them, and also as "range" for common opperations. You can see this with List.subCollection( Filter ). Existing RnD effort is going towards supporting this kind of use at the FeatureCollection level.

The implementation of Collection must adhere to the rules of fail-fast concurrent modification.

There is a difference between getFeatureType() and getSchema()represents the LCD FeatureType that best represents the contents of this collection.

• The degenerate case returns the "_Feature" FeatureType, where the onlything known is that the contents are Features.
• For a collection backed by a shapefiles (or database tables) the FeatureType returned by getSchema() will complete describe each and every child in the collection.
• For mixed content FeatureCollections you will need to check the FeatureType of each Feature as it is retrived from the collection

The method getSchema() is named for compatability with the geotools 2.0 API.

The contents of the returned FeatureCollection are determined by applying the provider Filter to the entire contents of this FeatureCollection.

Note: When performing aggregate calculations please consider using the Filter/Expression/Function API as it may be optimized.

When this collection is backed by live data the event notification will follow the guidelines outlined by FeatureListner.

You must be sure to allow null values, this is because in a try/finally block client code may not be sure if they have actualy succeed in assign a value to an iterator they wish to ensure is closed. By permiting null as an api we prevent a null check in lots of finally statements.

Note: Because of FeatureReader using an interator internally, there is only one implementation of this method that makes any sense:

 public void close( FeatureIterator iterator) {
 if( iterator != null ) iterator.close();
 }
 

 Iterator iterator = collection.iterator();
 try {
 for( Iterator i=collection.iterator(); i.hasNext();){
 Feature feature = (Feature) i.hasNext();
 System.out.println( feature.getID() );
 }
 }
 finally {
 collection.close( iterator );
 }
 

The implementation of Collection must adhere to the rules of fail-fast concurrent modification. In addition (to allow for resource backed collections, the close( Iterator ) method must be called.

This is almost equivalent to:

• a Type-Safe call to: getAttribute(getFeatureType().getAttributeType(0).getName()).iterator();.
• A Java 5:Iterator<Feature>

 FeatureIterator iterator=collection.features();
 try {
 while( iterator.hasNext()  ){
 Feature feature = iterator.next();
 System.out.println( feature.getID() );
 }
 }
 finally {
 collection.close( iterator );
 }
 

GML Note: The contents of this iterator are considered to be defined by featureMember tags (and/or the single allowed FeatureMembers tag). Please see getFeatureType for more details.

There are several limitations on the use of FeatureType with respect to a FeatureCollection.

GML 3.x: all FeatureCollections decend from gml:AbstractFeatureCollectionType:

• featureMember 0..* allows _Feature or xlink:ref
• featureMembers 0..1 contents treated as _Feature

GML 3.x: gml:AbstractFeatureCollectionType decends from gml:BoundedFeatureType:

• metaDataProperty 0..*
• description 0..1
• name 0..*
• boundedBy 1..1 (required)
• location 0..1

Implementation Notes

There is a difference between getFeatureType() and getSchema(), getSchema is named for historical reasons and reprensets the LCD FeatureType that best represents the contents of this collection.

• The degenerate case returns the "_Feature" FeatureType, where the onlything known is that the contents are Features.
• For a collection backed by a shapefiles (or database tables) the FeatureType returned by getSchema() will complete describe each and every child in the collection.
• For mixed content FeatureCollections you will need to check the FeatureType of each Feature as it is retrived from the collection

There is a difference between getFeatureType() and getSchema()represents the LCD FeatureType that best represents the contents of this collection.

• The degenerate case returns the "_Feature" FeatureType, where the onlything known is that the contents are Features.
• For a collection backed by a shapefiles (or database tables) the FeatureType returned by getSchema() will complete describe each and every child in the collection.
• For mixed content FeatureCollections you will need to check the FeatureType of each Feature as it is retrived from the collection

The method getSchema() is named for compatability with the geotools 2.0 API. In the Geotools 2.2 time frame we should be able to replace this method with a careful check of getFeatureType() and its attributes.

The contents of the returned FeatureCollection are determined by applying the provider Filter to the entire contents of this FeatureCollection. The result is "live" and modifications will be shared.

This method is used cut down on the number of filter based methods required for a useful FeatureCollection construct. The FeatureCollections returned really should be considered as a temporary "view" used to control the range of a removeAll, or modify operation.

Example Use:

 collection.subCollection( filter ).clear();
 

The results of subCollection:

• are to be considered unordered
• may be an ordered FeatureList if requested when sortBy is indicated