Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<table class="confluenceTable"><tbody><tr><th class="confluenceTh"><p>Motivation:</p></th><td class="confluenceTd"><p>FeatureCollection is not a java.util.Collection</p></td></tr><tr><th class="confluenceTh"><p>Contact:</p></th><td class="confluenceTd"><p><a class="confluence-link confluence-userlink" data-username="jive" href="/display/~jive" data-linked-resource-id="1159" data-linked-resource-type="userinfo" username="jive" data-linked-resource-default-alias="Jody Garnett" data-base-url="http://docs.codehaus.org">Jody Garnett</a>,<a class="confluence-link confluence-userlink" data-username="mbedward" href="/display/~mbedward" data-linked-resource-id="75366465" data-linked-resource-type="userinfo" username="mbedward" data-linked-resource-default-alias="Michael Bedward" data-base-url="http://docs.codehaus.org">Michael Bedward</a>,<a class="confluence-link confluence-userlink" data-username="aaime" href="/display/~aaime" data-linked-resource-id="787" data-linked-resource-type="userinfo" username="aaime" data-linked-resource-default-alias="Andrea Aime" data-base-url="http://docs.codehaus.org">Andrea Aime</a></p></td></tr><tr><th class="confluenceTh"><p>Tracker:</p></th><td class="confluenceTd"><p><a href="https://jira.codehaus.org/browse/GEOT-4181">https://jira.codehaus.org/browse/GEOT-4181</a></p></td></tr><tr><th class="confluenceTh"><p>Tagline:</p></th><td class="confluenceTd"><p><table class="wysiwyg-macro" data-macro-name="excerpt" data-macro-parameters="atlassian-macro-output-type=INLINE" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2V4Y2VycHQ6YXRsYXNzaWFuLW1hY3JvLW91dHB1dC10eXBlPUlOTElORX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>remove methods that assume in-memory model</p></td></tr></table></p></td></tr></tbody></table><p>This page represents the <strong>current</strong> plan; for discussion please check the tracker link above.</p><table class="wysiwyg-macro" data-macro-name="section" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3NlY3Rpb259&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><table class="wysiwyg-macro" data-macro-name="column" data-macro-parameters="width=70%" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvbHVtbjp3aWR0aD03MCV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e3RvY30&amp;locale=en_GB&amp;version=2" data-macro-name="toc"></td></tr></table><table class="wysiwyg-macro" data-macro-name="column" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvbHVtbn0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>Children:</p><img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e2NoaWxkcmVufQ&amp;locale=en_GB&amp;version=2" data-macro-name="children"></td></tr></table></td></tr></table><h1>History and Motivation</h1><p>FeatureCollection needs to lighten up to be happy; the original FeatureCollection implementation was a java.util.Collection offering iterator based access to features stored in memory. When the data access layer was rewritten for DataStore the concept of a FeatureResults was introduced wich could be thought of as a &quot;prepared statement&quot; (able to fetch results each time it was asked). This is a nice light weight &quot;streaming&quot; model for data access that does not force us to load the data into memory.</p><p>The intension was to treat it a bit more like a Java ResultSet (so several iterators could be open against the same paged results). But the road to hell is paved with good intensions.</p><p>And the FeatureResults interface was in for some hell: <a class="confluence-link" href="/display/GEOTOOLS/2.1.x" data-linked-resource-id="19136" data-linked-resource-type="page" data-linked-resource-default-alias="2.1.x" data-base-url="http://docs.codehaus.org">2.1.x</a> <a class="confluence-link" href="/display/GEOTOOLS/Bring+Back+FeatureCollection" data-linked-resource-id="13862" data-linked-resource-type="page" data-linked-resource-default-alias="Bring Back FeatureCollection" data-base-url="http://docs.codehaus.org">Bring Back FeatureCollection</a> was a last ditch community lead request to bring back the FeatureCollection api and allow iterators to be used (thus not existing current code). The compromise that was reached was to ask users to FeatureCollection.close( Iterator ) each iterator after use; so that we could still offer a nice streaming based approach to data access.</p><p>For GeoTools 2.5.x we made the migration to Java 5 and we could no longer allow FeatureCollection to implement java.util.Collection because of the new &quot;for each&quot; syntax did not offer a callback for us to close our iterators. Justin started <a class="confluence-link" href="/display/GEOTOOLS/Focus+FeatureSource+around+FeatureReader+and+FeatureWriter" data-linked-resource-id="65208355" data-linked-resource-type="page" data-linked-resource-default-alias="Focus FeatureSource around FeatureReader and FeatureWriter" data-base-url="http://docs.codehaus.org">Focus FeatureSource around FeatureReader and FeatureWriter</a>, however all we had time for was the bare minimum to make Java 5 not a fatal opportunity for client code to leak memory.</p><h1>Bring back FeatureResult</h1><p>In the spirit of <a class="confluence-link" href="/display/GEOTOOLS/Bring+Back+FeatureCollection" data-linked-resource-id="13862" data-linked-resource-type="page" data-linked-resource-default-alias="Bring Back FeatureCollection" data-base-url="http://docs.codehaus.org">Bring Back FeatureCollection</a> here is our last minuet 2.7.x request to complete the journey; formally recognise that FeatureCollection is not a java.util.Collection and turf Iterator access (and other concepts that mirror in memory storage).</p><h2>Remove the CollectionListener</h2><p>First up is the add/remove listeners; a recent code review shows that they are only implemented by the new JDBCNG FeatureCollection (because justin is apparently very responsible). Due to everyone else not being responsible we can safely remove these since no client code could of depended on being sent an event.</p><table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p><span style="text-decoration: line-through;">addListener(CollectionListener)</span><br /><span style="text-decoration: line-through;">removeListener(CollectionListener)</span></p></td></tr></table><p style="margin-left: 0.0px;">Note: These listeners have been deprecated as part of  <a href="http://docs.codehaus.org/display/GEOTOOLS/Clean+up+FeatureEvents">Clean up FeatureEvents</a> since this proposal was written.</p><h2>DefaultFeatureCollection</h2><p><strong>FeatureCollections.newCollection</strong></p><p>Currently FeatureCollections.newCollection returns a SimpleFeatureCollection. Many code examples populate this feature collection using the add method.</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>SimpleFeatureCollection collection = FeatureCollections.newCollection();
collection.add( feature ); // &lt;-- WILL NOT WORK!</pre></td></tr></table><p>The most expidient fix is to create a new DefaultFeatureCollection directly (this is the implementation returned by newCollection() above).</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>DefaultFeatureCollection collection = new DefaultFeatureCollection();
collection.add( feature );</pre></td></tr></table><p>DefaultFeatureCollection is a FeatureCollection that implements java.util.Collection . This is the current migration path for those wishing to have an in memory collection.</p><p><strong>DataUtilities.collection</strong></p><p>Asking for your feature collection to be &quot;loaded&quot; into a FeatureCollection is the currently documented way of avoiding all this streaming nonsense and loading your data into memory.</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>SimpleFeatureCollection collection = DataUtilities.collection( featureCollection );
</pre></td></tr></table><p>If we find a lot of users go on to call <strong>add</strong> we can change the DataUtilities.collection methods to explicitly return a DefaultFeatureCollectionOption.</p><p><strong>Alternatives</strong></p><p>We may also wish to consider a different implementation for DefaultFeatureCollection:</p><ul class="alternate"><li>MemoryFeatureCollection and TreeSetFeatureCollection are copies of DefaultFeatureCollection</li><li>ListFeatureCollection - is newer and does not protect against duplicates, but may be faster in day to day use?</li><li>SpatialIndexFeatureCollection - cannot be modified once made; not a suitable replacement</li></ul><h2>Remove Iterator Methods</h2><p>The following methods cover the care and feeding of Iterators:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>  void close(FeatureIterator&lt;SimpleFeature>)
  Iterator&lt;SimpleFeature> iterator()
  void close(Iterator&lt;SimpleFeature>);
  void purge()
</pre></td></tr></table><p>We are removing the close(FeatureIterator) method as well as it already has a serviceable FeatureIterator.close() method (the method was only provided to ease transition to FeatureIterator).</p><h2>Remove Collection Methods</h2><p>The following methods are used to update and modify the contents of an in memory Collection and do not fit with the &quot;Prepaired Statement&quot; model of a FeatureCollection.</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>  // modification of in memory feature collections
  // (recommend using featuresource instead)
  boolean add(SimpleFeature)
  boolean addAll(Collection&lt;? extends SimpleFeature>)
  boolean addAll(FeatureCollection&lt;? extends SimpleFeatureType, ? extends SimpleFeature>)
  boolean clear()
  boolean remove(Object)
  boolean removeAll(Collection&lt;?>)
  boolean retainAll(Collection&lt;?>)</pre></td></tr></table><h2>getSchema and getDescriptor()</h2><p>This is a long standing hole in the API, proposal written in response to questions from Ben: <a class="confluence-link" href="/display/GEOTOOLS/FeatureCollection+Descriptor+for+FeatureMembers" data-linked-resource-id="117901145" data-linked-resource-type="page" data-linked-resource-default-alias="FeatureCollection Descriptor for FeatureMembers" data-base-url="http://docs.codehaus.org">FeatureCollection Descriptor for FeatureMembers</a></p><p>It sounds like this is just an additional method:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>   AttributeDescriptor getDescriptor();
   FeatureType getSchema();
</pre></td></tr></table><p>Consider making the API consistent with a getType() method? Does not seem worth the bother.</p><p>Tasks:</p><ul><li>Added in GeoTools 9.0.x</li></ul><h2>FeatureCollection</h2><p>Here is what SimpleFeatureCollection looks like after the change:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>public interface SimpleFeatureCollection extends FeatureCollection&lt;SimpleFeatureType,SimpleFeature> {
  // feature access - close when done!
  SimpleFeatureIterator features();

// feature access with out the loop
  void accepts(FeatureVisitor, ProgressListener);

// metadata
  String getID();
  SimpleFeatureType getSchema();
  AttributeDescriptor getDescriptor(); // pending prosal

// sub query
  SimpleFeatureCollection subCollection(Filter);
  SimpleFeatureCollection sort(SortBy);
  boolean contains(Object);
  boolean containsAll(Collection&lt;?>);

// summary information
  ReferencedEnvelope getBounds();
  boolean isEmpty();
  int size();

// convert to array
  Object[] toArray();
  &lt;O> O[] toArray(O[]);
}
</pre></td></tr></table><p>Points raised during discussion:</p><ul class="alternate"><li>toArray methods are there on the off chance the implementation can provide a quick implementation? Is this another good intension? Probably. Could be replaced with a DataUtilities method</li><li>subCollection &amp; sort functionality have been covered by Query these days; and could be removed.<br />Alternative: subCollection( Query ) would be more useful. </li><li>contains and containsAll are interesting; would almost expect look up by FeatureId instead</li><li>getID() is left from a time when FeatureCollection implemented Feature; it is still used when encoding</li><li>getDescriptor is technically accurate; however we are used to working with FeatureType</li><li>isEmpty() earns its keep; size() == 0 is not a replacement as you need to count the whole set</li><li>with that in mind containsAll falls into the same idea; how to prevent a multi pass operation</li><li>accepts earns its keep for <a class="confluence-link confluence-userlink" data-username="jive" href="/display/~jive" data-linked-resource-id="1159" data-linked-resource-type="userinfo" username="jive" data-linked-resource-default-alias="Jody Garnett" data-base-url="http://docs.codehaus.org">Jody Garnett</a>,<br /><a class="confluence-link confluence-userlink" data-username="aaime" href="/display/~aaime" data-linked-resource-id="787" data-linked-resource-type="userinfo" username="aaime" data-linked-resource-default-alias="Andrea Aime" data-base-url="http://docs.codehaus.org">Andrea Aime</a> wants the javadocs cleaned up so it is obvious that the feature being visited is a Flyweight (ie the same object with just the values changing inside each time)</li><li>Minimal baseline: minimum that is functional (if we want more we need to justify it):</li></ul><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>public interface SimpleFeatureCollection extends FeatureCollection&lt;SimpleFeatureType,SimpleFeature> {
  SimpleFeatureIterator features();
  String getID();
  SimpleFeatureType getSchema();
  ReferencedEnvelope getBounds();
  boolean isEmpty();
  int size();
}
</pre></td></tr></table><h2>DataUtilities </h2><p>During the review process many additional utility methods were added to DataUtilities in order to ensure all FeatureCollections handled things in a similar fashion.</p><p>Specific changes to functionality:</p><ul><li>visit( FeatureVisitor, Progress ) now throws an IOException in the case of problems, rather then just reporting via the supplied progress</li></ul><div>Here are the new DataUtilities methods:</div><div><p> </p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>DataUtilities.visit( FeatureCollection, FeatureVisitor, ProgerssListener )
DataUtilities.bounds( FeatureCollection ) &lt;-- already existed
DataUtilities.bounds( FeatureIterator ) 
DataUtilities.count( FeatureCollection ) 
DataUtilities.count( FeatureIterator ) 
DataUtilities.close( Iterator )
DataUtilities.first( SimpleFeatureCollection ): SimpleFeature
DataUtilities.first( FeatureCollection&lt;?,F> ): F
DataUtilities.list( FeatureCollection&lt;?,F> ): List&lt;F>  // Already existed 
DataUtilities.list( FeatureCollection&lt;?,F>, int ): List&lt;F>
DataUtilities.iterator( FeatureIterator ): Iterator // also Closable 
DataUtilities.collectionCast( FeatureCollection ): Collection </pre></td></tr></table><h2>FeatureCollection Implementations</h2><p>Base FeatureCollection classes available for extending:</p><ul><li><strong>AbstractFeatureCollection</strong> - requires an <strong>openIterator</strong> method and attempts to track all the outstanding iterators and clean up after them with a <strong>purge</strong> method.</li><li><strong>BaseFeatureCollection / BaseSimpleFeatureCollection</strong> - requires a <strong>features() </strong>method, all other methods are implemented by calling features(), recommend supply <strong>size()</strong> and <strong>bounds()</strong> methods.<br /><ul><li><strong><strong>ProcessingCollection / SimpleProcessingCollection </strong></strong>- requires<strong><strong> </strong>features()</strong>, <strong>getBounds()</strong>, <strong>size()</strong>, and <strong>buildTargetFeatureType()</strong><strong><br /></strong></li></ul></li><li><strong>DecoratingFeatureCollection</strong> / <strong>DecoratingSimpleFeatureCollection </strong>- each method calls through to an internal delegate FeatureCollection</li><li><strong>AdaptorFeatureCollection - </strong> copy of AbstractFeatureCollection used as a base class by uDig (should replace with BaseFeatureCollection )</li><li><strong>DataFeatureCollection</strong> - requires a <strong>reader()</strong> method and implementation of <strong>FeatureReader</strong>, also <strong>getSchema()</strong>,<strong> getBounds()</strong>,<strong> getCount() </strong>and<strong> collection()</strong></li></ul><p>Working FetaureCollection implementations for day to day use in your own code:</p><ul><li><strong><strong>DefaultFeatureCollection</strong></strong> - uses a TreeSet sorted by FeatureId internally </li><li><strong>ListFeatureCollection</strong></li><li><strong>SpatialIndexFeatureCollection</strong></li><li><strong>TreeSetFeatureCollection</strong></li></ul><p>Implementation specific FeatureCollection classes:</p><ul><li><strong>MemoryFeatureCollection</strong> - used internally by MemoryDataStore storing Features in a TreeSet sorted by FeatureId</li><li><strong>SubFeatureCollection </strong>- uses a Filter to reduce the number of features returned<br /><ul><li><strong>SubFeatureList - </strong>tries to implement SortBy using a List&lt;FeatureId&gt; with determined order</li></ul></li><li><strong>ContentFeatureCollection - </strong>delegates most work to ContentFeatureSource for the win</li><li><strong>DefaultVersionedFeatureCollection </strong>- does not appear complete</li><li><strong>SimpleFeatureCollectionBridge </strong>- wraps a FeatureCollection&lt;SimpleFeatureType,SimpleFeature&gt; up as a SimpleFeatureCollection</li></ul></div><h1>Status</h1><p>This proposal is the subject of a grass roots revolution on the geotools-devel list; indeed the revolution is on going and will not be televised.</p><p>Voting has not started yet:</p><ul><li><a class="confluence-link confluence-userlink" data-username="aaime" href="/display/~aaime" data-linked-resource-id="787" data-linked-resource-type="userinfo" username="aaime" data-linked-resource-default-alias="Andrea Aime" data-base-url="http://docs.codehaus.org">Andrea Aime</a> +0</li><li><a class="confluence-link confluence-userlink" data-username="bencaradocdavies" href="/display/~bencaradocdavies" data-linked-resource-id="60850191" data-linked-resource-type="userinfo" username="bencaradocdavies" data-linked-resource-default-alias="Ben Caradoc-Davies" data-base-url="http://docs.codehaus.org">Ben Caradoc-Davies</a> +0</li><li><a class="confluence-link confluence-userlink" data-username="christian.mueller@nvoe.at" href="/display/~christian.mueller@nvoe.at" data-linked-resource-id="75366406" data-linked-resource-type="userinfo" username="christian.mueller@nvoe.at" data-linked-resource-default-alias="Christian Mueller" data-base-url="http://docs.codehaus.org">Christian Mueller</a> +0</li><li><a class="confluence-link confluence-userlink" data-username="ianturton" href="/display/~ianturton" data-linked-resource-id="800" data-linked-resource-type="userinfo" username="ianturton" data-linked-resource-default-alias="Ian Turton" data-base-url="http://docs.codehaus.org">Ian Turton</a> +0</li><li><a class="confluence-link confluence-userlink" data-username="jdeolive" href="/display/~jdeolive" data-linked-resource-id="14894" data-linked-resource-type="userinfo" username="jdeolive" data-linked-resource-default-alias="Justin Deoliveira" data-base-url="http://docs.codehaus.org">Justin Deoliveira</a> +1</li><li><a class="confluence-link confluence-userlink" data-username="jive" href="/display/~jive" data-linked-resource-id="1159" data-linked-resource-type="userinfo" username="jive" data-linked-resource-default-alias="Jody Garnett" data-base-url="http://docs.codehaus.org">Jody Garnett</a> +1</li><li><a class="confluence-link confluence-userlink" data-username="mbedward" href="/display/~mbedward" data-linked-resource-id="75366465" data-linked-resource-type="userinfo" username="mbedward" data-linked-resource-default-alias="Michael Bedward" data-base-url="http://docs.codehaus.org">Michael Bedward</a> +0</li><li><a class="confluence-link confluence-userlink" data-username="simboss" href="/display/~simboss" data-linked-resource-id="10743" data-linked-resource-type="userinfo" username="simboss" data-linked-resource-default-alias="Simone Giannecchini" data-base-url="http://docs.codehaus.org">Simone Giannecchini</a> +0</li></ul><h2>Tasks</h2><ol><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> JG: Deprecate methods for 8.0 release<br /><ul><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> FeatureCollection Deprecate Collection methods</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> FeatureCollection Deprecate CollectionListener (and methods)</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> FeatureCollection Deprecate FeatureCollection Iterator methods</li></ul></li><li>JG: Changes for 9.0 master<br /><ul><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> FeatureCollection Remove Collection methods</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> FeatureCollection Remove CollectionListener (and methods)</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> FeatureCollection Remove FeatureCollection Iterator methods</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> Deprecate FeatureCollections factory</li></ul></li><li>Fix support classes (<img class="emoticon emoticon-warning" data-emoticon-name="warning" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/warning.png" alt="(warning)" title="(warning)" /> used to mark anything that did not go smoothly)<br /><ul><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> DataFeatureCollection remains based on FeatureReader</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> AbstractFeatureCollection will remain based on iteartor()<br /><ul><li>ForceCoordinateSystemFeatureResults</li><li>MemoryFeatureCollection</li><li>ReprojectFeatureResults</li><li>TransformFeatureCollection</li></ul></li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> BaseFeatureCollection created to be based on features()<br /><ul><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> SubCollection migrated to BaseFeatureCollection</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> SortFeatureList migrated to BaseFeatureCollection</li></ul></li><li>AdaptorFeatureCollection - base class used by uDig</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" />ContentFeatureCollection</li><li>DecoratingSimpleFeatureCollection<br /><ul><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" />FilteringSimpleFeatureCollection: migrated to FilteringFeatureIterator (from FilteringIterator)</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" />MaxSimpleFeatureCollection: migrated to MaxFeaturesSimpleFeatureIterator (from MaxFeaturesIterator)</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> ReprojectingFeatureCollection: migrated to ReprojectingFeatureIterator (from ReprojectingIterator)</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> ReTypingFeatureCollection: migrated to ReTypingFeatureIterator (from ReTypingIterator)</li></ul></li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" />DefaultFeatureCollection - remains based on TreeSet<br /><ul><li>GMLFeatureCollection: subclass of DefaultFeatureCollection</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> MemoryFeatureCollection: copy of DefaultFeatureCollection</li><li><img class="emoticon emoticon-warning" data-emoticon-name="warning" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/warning.png" alt="(warning)" title="(warning)" /> TreeSetFeatureCollection: copy of DefaultFeatureCollection changed to no longer implement Collection</li></ul></li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> DefaultVersionedFeatureCollection: add is now protected and use during init to populate the collection</li><li><img class="emoticon emoticon-warning" data-emoticon-name="warning" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/warning.png" alt="(warning)" title="(warning)" /> <span style="color: rgb(0,0,0);">PropertyValueCollection - this is not a FeatureCollection it was being used to return Collection&lt;Attribute&gt; I have changed it to return a Feature (containing the expected Attribute) but cannot untangle the Encoder well enough to make the test pass.</span></li></ul></li><li>Fix geotools modules (notes on any thing interesting, also check commit logs)<br /><ul><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> In general pretty smooth transition</li><li><img class="emoticon emoticon-warning" data-emoticon-name="warning" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/warning.png" alt="(warning)" title="(warning)" /> app-schema makes &quot;dangerous&quot; use of feature collection support classes (that internally assume SimpleFeature)</li><li><img class="emoticon emoticon-warning" data-emoticon-name="warning" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/warning.png" alt="(warning)" title="(warning)" /> StreamingRenderer required code duplication to handle Collection.iterator() and FeatureCollection.features()</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> Many cases where try/finally was used to ensure featureIterator.close() was called</li><li><img class="emoticon emoticon-warning" data-emoticon-name="warning" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/warning.png" alt="(warning)" title="(warning)" /> PropertyValueCollection and ValueCollectionTypeBindingTest is broken as is conflicted between FeatureCollection and Collection&lt;Attribute&gt;<br /><ul><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> Thanks to Justin for redoing the EMF bindings to support a Collection&lt;Attribute&gt; so this could be handled</li></ul></li></ul></li><li>Documentation - see Documentation Changes below </li><li>Integration party<br /><ol><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> JG: Stage work on branch: <a href="https://github.com/geotools/geotools/tree/featurecollection_cleanup">https://github.com/geotools/geotools/tree/featurecollection_cleanup</a></li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> JG: Submit pull request: <a href="https://github.com/geotools/geotools/pull/44">https://github.com/geotools/geotools/pull/44</a></li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> JG: deploy 9.0-M0-SNAPSHOT as a migration target</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> JD: GeoServer pull request: <a href="https://github.com/geoserver/geoserver/pull/61">https://github.com/geoserver/geoserver/pull/61</a></li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> JG: uDig pull request: <a href="https://github.com/uDig/udig-platform/pull/161">https://github.com/uDig/udig-platform/pull/161</a></li></ol></li></ol><h2>Documentation Changes</h2><p>The following documentation needs to be updated:</p><ul class="alternate"><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> Fix up the <a href="http://docs.geotools.org/latest/userguide/welcome/upgrade.html">upgrade</a> instructions</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> Update <a href="http://docs.geotools.org/latest/userguide/tutorial/feature/csv2shp.html">feature tutorial</a> to use ListFeatureCollection (to preserve order)</li><li><img class="emoticon emoticon-tick" data-emoticon-name="tick" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/check.png" alt="(tick)" title="(tick)" /> Update <a href="http://docs.geotools.org/latest/userguide/library/main/collection.html#performance-options">feature collection examples</a></li></ul><h2>Upgrade Instructions</h2><div>These examples are taken from <a href="http://docs.geotools.org/latest/userguide/welcome/upgrade.html">upgrade.rst</a> (included in the pull request).</div><div><ol><li>add( Feature )<br /><ul><li>Use DefaultFeatureCollection so Collection.add( feature ) is visible</li><li>Change FeatureCollections.newCollection() → new DefaultFeatureCollection() </li></ul></li><li>FeatureCollection.close( Iterator )<br /><ul><li>Preferred: use FeatureIterator.close()</li><li>Use: ((Closeable)iterator).close()</li></ul></li><li>Handy FeatureCollections that implement java.util.Collection<br /><ul><li>ListFeatureCollection (delegates to List)</li><li>DefaultFeatureCollection (the original based on a TreeSet sorted by FeatureId)<br /><ul><li>MemoryFeatureCollection (a copy of DefaultFeatureCollection for use by MemoryDataStore)</li></ul></li></ul></li></ol></div><div class="section"><h3>FeatureCollection Add</h3><p>With the FeatureCollection.add method being removed, you will need to use an explicit instance that supports adding content.</p><p>BEFORE:</p><div class="highlight-python"><p> </p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>SimpleFeatureCollection features = FeatureCollections.newCollection();

for( SimpleFeature feature : list ){
   features.add( feature );
}</pre></td></tr></table><p> </p></div><p>AFTER:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>DefaultFeatureCollection features = new DefaultFeatureCollection();
for( SimpleFeature feature : list ){
   features.add( feature );
}</pre></td></tr></table><p>ALTERNATE (will throw exception if FeatureColleciton does not implement java.util.Collection )</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>Collection&lt;SimpleFeature> collection = DataUtilities.collectionCast( featureCollection );
collection.addAll( list );</pre></td></tr></table><p>ALTERNATE DETAIL:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>SimpleFeatureCollection features = FeatureCollections.newCollection();
if( features instanceof Collection ){
    Collection&lt;SimpleFeature> collection = (Collection) features;
    collection.addAll( list );
}
else {
    throw new IllegalStateException("FeatureCollections configured with immutbale implementation");
}</pre></td></tr></table><p> </p></div><div class="section"><h3>FeatureCollection Iterator</h3><p>The deprecated FeatureCollection.iterator() method is no longer available, please use FeatureCollection.features() as shown below.</p><p>BEFORE:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>Iterator i=featureCollection.iterator();
try {
    while( i.hasNext(); ){
       SimpleFeature feature = i.next();
       ...
    }
}
finally {
    featureCollection.close( i );
}</pre></td></tr></table><p>AFTER:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>FeatureIterator i=featureCollection.features();
try {
     while( i.hasNext(); ){
         SimpleFeature feature = i.next();
         ...
     }
}
finally {
     i.close();
}</pre></td></tr></table><p>JAVA7 (using try-with-resource):</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>try ( FeatureIterator i=featureCollection.features()){
    while( i.hasNext() ){
         SimpleFeature feature = i.next();
         ...
    }
}</pre></td></tr></table><p> </p></div><div class="section"><h3>FeatureCollection close method</h3><p>We have made FeatureCollection implement closable (for Java 7 try-with-resource compatibility). This also provides an excellent replacement for FeatureCollection.close( Iterator ).</p><p>For other code that relied on FeatureCollection.close( Iterator ) to clean up after things, please make sure your Iterator implements <strong>Closeable</strong>.</p><p>BEFORE:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>Iterator iterator = collection.iterator();
try {
   ...
} finally {
    if (collection instanceof SimpleFeatureCollection) {
        ((SimpleFeatureCollection) collection).close(iterator);
    }
}</pre></td></tr></table><p>AFTER:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>Iterator iterator = collection.iterator();
try {
   ...
} finally {
   DataUtilities.close( iterator, collection );
}</pre></td></tr></table><p>DETAIL:</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>Iterator iterator = collection.iterator();
try {
   ...
} finally {
    if (iterator instanceof Closeable) {
        try {
           ((Closeable)iterator).close();
        }
        catch( IOException e){
            Logger log = Logger.getLogger( collection.getClass().getPackage().toString() );
            log.log(Level.FINE, e.getMessage(), e );
        }
    }
}</pre></td></tr></table><p>JAVA7: using try-with-resource syntax for iterators that implement Closeable</p><table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>try ( FeatureIterator i=featureCollection.features()){
    ...
}</pre></td></tr></table></div>