[Geotools-commits] svn - r38477 - in trunk: docs/user/library/api modules/library/api/src/main/java/org/geotools/data

[<svn...@os...>]

Author: jive
Date: 2012-01-11 20:06:03 -0800 (Wed, 11 Jan 2012)
New Revision: 38477

Modified:
   trunk/docs/user/library/api/datastore.rst
   trunk/modules/library/api/src/main/java/org/geotools/data/FeatureSource.java
Log:
fix javadoc for FeatureSource getCount and add an example to the docs

Modified: trunk/docs/user/library/api/datastore.rst
===================================================================
--- trunk/docs/user/library/api/datastore.rst	2012-01-11 15:14:01 UTC (rev 38476)
+++ trunk/docs/user/library/api/datastore.rst	2012-01-12 04:06:03 UTC (rev 38477)
@@ -13,7 +13,11 @@
 References:
 
 * :doc:`gt-data <../data/datastore>` DataStore Code Examples
+* javadoc: `DataStore <http://docs.geotools.org/latest/javadocs/org/geotools/data/DataStore.html>`_
+* javadoc: `FeatureSource <http://docs.geotools.org/latest/javadocs/org/geotools/data/FeatureSource.html>`_
+* javadoc: `SimpleFeatureSource <http://docs.geotools.org/latest/javadocs/org/geotools/data/simple/SimpleFeatureSource.html>`_
 
+
 DataAccess
 ^^^^^^^^^^
 
@@ -128,7 +132,6 @@
 
 A FeatureSource is used to provide access to the contents of a DataStore.
 
-
 .. image:: /images/FeatureSource.PNG
 
 **Approach**
@@ -169,13 +172,12 @@
       // locking supported
   }
 
-  
 SimpleFeatureSource
 '''''''''''''''''''
 
-SimpleFeatueSource is the extension of FeatureSource returned by DataStore to explicitly work with SimpleFeature and SimpleFeatureCollection.
+SimpleFeatueSource is the extension of FeatureSource returned by DataStore to explicitly work with
+SimpleFeature and SimpleFeatureCollection.
 
-
 .. image:: /images/SimpleFeatureSource.PNG
 
 Access to basic name and schema information:
@@ -210,7 +212,14 @@
 
 * FeatureSource.getBounds()
 * FeatureSource.getBounds(Query)
+  
+  May return null if the bounds are unknown or too costly to calculate.
+
 * FeatureSource.getCount(Query)
+  
+  May return -1 if the information is not readily avaialble. Formats such as shapefile 
+  keep this information avaialble in the header for handy reference. WFS does not provide
+  any way to ask for this information and thus always returns -1.
 
 Where a request is captured by a **Query**:
 
@@ -304,6 +313,29 @@
       
       query.setHints( new Hints( Query.INCLUDE_MANDITORY_PROPS, Boolean.TRUE ) );
 
+Examples:
+
+* How to count the number of features.
+  
+  Because the getCount method just checks the file or database header information it is designed
+  to be very fast. Not all implementations have access to this information making it a bit tricky
+  to count the number of avaialble features.
+  
+  The following code shows how to quickly count all the feautres available::
+    
+    int count = featureSource.getCount( Query.ALL );
+    if( count == -1 ){
+        count = featureSource.getFeatures().size();
+    }
+  
+  You can modify this to use your own Query::
+  
+    Query query = new Query( CQL.toFilter("REGION = 3") );
+    int count = featureSource.getCount( query );
+    if( count == -1 ){
+        count = featureSource.getFeatures( query ).size();
+    }
+  
 SimpleFeatureStore
 ''''''''''''''''''
 

Modified: trunk/modules/library/api/src/main/java/org/geotools/data/FeatureSource.java
===================================================================
--- trunk/modules/library/api/src/main/java/org/geotools/data/FeatureSource.java	2012-01-11 15:14:01 UTC (rev 38476)
+++ trunk/modules/library/api/src/main/java/org/geotools/data/FeatureSource.java	2012-01-12 04:06:03 UTC (rev 38477)
@@ -217,8 +217,13 @@
      * <p>
      * It is possible that this method will return {@code -1} if the calculation
      * of number of features is judged to be too costly by the implementing class.
-     * In this case, you might call <code>getFeatures(query).getBounds()</code>
+     * In this case, you might call <code>getFeatures(query).size()</code>
      * instead.
+     * <p>
+     * Example use:<pre><code> int count = featureSource.getCount();
+     * if( count == -1 ){
+     *    count = featureSource.getFeatures( count ).size();
+     * }
      *
      * @param query the query to select features
      *