[Geotools-devel] Experimental Features, 1 week.

[Chris H. <ch...@op...>]

Ian has been making daily reports on our progress, but I thought I'd send out 
an email of our overall changes before the IRC.  Ian, feel free to add 
anything that I've missed.  As you can see, this is more of an evolutionary, 
code clean-up change - getting rid of methods that were not used or not named 
well, moving stuff to factories and having FeatureCollection fit in the 
Collections framework.  We still both have things we'd like to see added, 
such as Ian's FeatureDocument idea, and when I start actually using complex 
features I'll probably have to add a few things.  But we hope that what we've 
done thus far makes using geotools cleaner and easier, and allows for less 
painful expansion in the future.  


Interface Updates 
------------------------
Feature:
 - getSchema renamed to getFeatureType
 - getId renamde to getID
 - moved Object[] getAttributes() to Object[] getAttributes(Object[])
 - removed FeatureVisitor - it wasn't used, FeatureCollectionIterator 
replaces it.
 - added Object get/setAttribute(int index) for faster access (allows
"compiled queries" better access times)
 - added getBounds ( or something equivelent ) to allow access to the
Features total bounding envelope
- added getNumberOfAttributes() as convenience method for 
getFeatureType().getAttributeCount()
 - changed getAttributes() to getAttributes(Object[] attributes), to not waste
    as much time on array creation in that method.
 - added a NULL_ATTRIBUTE to follow the null pattern

IllegalFeatureException renamed to IllegalFeatureException

AttributeType:
 - Removed all setter methods, so it doesn't even appear immutable.
 - removed getOccurances - this method was never used, there is a need
   for it, but it needs to be rethought.
 - removed getPosition - FeatureType has all information as to where its 
attributes are.  This also allows AttributeTypes to be reused.
 - added validate(Object obj) method, which tells if the object can serve as 
the attribute for this AttributeType.  This allows complex AttributeTypes, 
such as FeatureTypes, more validation then just a class check.  Throws 
IllegalArgumentException with a message of why the validation failed if it 
does not successfully validate.  This allows validation to occur in the 
attributeTypes themselves, instead of in the Feature itself, as it was before.
 - added parse(Object value), which gives the AttributeType to turn the 
object into it's preferred storage type.  An example is a string 
representation of a double, the parse method would turn it into a Double, 
which would pass the validate method.
 - New AttributeTypeFactory, so attributes fit into Factory approach.  It's 
very simple and easy to use.


FeatureType:
 - now extends FeatureFactory, in addition to AttributeType, so that feature 
creation takes place here - schema.create(Object[] attributes)
 - All set methods removed, functionality now in FeatureTypeFactory, a 
mutable factory.  
 - attributeTotal() replaced by getAttributeCount() for clarity.
 - added find(AttributeType type) which gives the index of the AttributeType.
 - removed getAllAttributeTypes, as it was confusing and never really used.
 - getAttributeType(String xpath) no longer throws SchemaException, just 
returns null if the type is not found.

FeatureTypeFactory: 
 - new class, mutation and creation of FeatureTypes takes place here.
 - static method newFeatureType(AttributeType[] types, (optional) String 
name) provides the old functionality
 - Lots of new functionality, check the docs/source to see how it works.  
 
FeatureCollection:
 - extends Collection interface, so working with it should be pretty 
intuitive for all java users - add, addAll, remove, iterator, size, contains, 
toArray().
 - getBounds(), addListener, removeListener, and features() are the only 
additional methods.
 - features() returns a FeatureIterator, a new convenience class.  It doesn't 
not implement Iterator, but looks similar, with hasNext() and next(), but 
next() returns a Feature() instead of an Object that needs to be cast.
 - IndexedFeatureCollection is a new class that extends FeatureCollection, 
allowing indexing.
 - removed all datasource refernces.  Implementations of FeatureCollection 
that are tied to a datasource are still possible, and in fact encouraged.  
I'm going to do a postgis one when I have time.  But there is no longer any 
reference in the interface, and DefaultFeatureCollection does not reference a 
datasource.
 - Extents stuff completely deprecated - datasource.extents no longer exists.
 - Feature[] getFeatures() removed - use iterator (preferred) or (Feature 
[])collection.toArray(Feature[] features)
 - removeFeatures(Feature[]), remove(Extent), and add(Feature[]) removed.  
Use collection methods instead - add, remove, ect.
 - We are working on a FeatureDocument of typed collections, and on filling 
out featureCollections with more options, and more implementations/extensions 
of FeatureCollection, but for now we have a more solid base to work from, as 
we are in the Collection framework.

Factories
-------------
Ian did some excellent work here, which he can elaborate on further, but 
basically most everything is constructed from factories now.  We are no 
longer using sun.misc classes, but Feature and Datasource factories should be 
pluggable.  And there are some nice Abstract factories for those making new 
Factories, that just need to be extending.  There is also a new factories 
package in core, that contains interfaces for the factories.

DefaultCore
-----------------
 - Renamed all main classes to Default(interface name) - 
DefaultAttributeType, DefaultFeatureType, DefaultFeature, 
DefaultFeatureCollection.
 - Added MultiAttributeType, a first stab at the occurances problem, 
Attributes that occur more than once.  This needs to be fleshed out more, and 
as I explore complex features more I'll probably come with more questions, 
but I think this is a good start.
 - All implement the new interfaces.  All compile and the tests have all been 
modified.  

Other Modules
------------------
The following modules are compiling and successfully passing tests.  The 
migrations have been fairly painless.  

postgis
shapefile
gml
mapinfo
filter
sldstyling
java2DRenderer
oraclespatial
mysql


If people like the changes, we can figure out today when to do the merge, and 
who is handling what on the remaining modules.  Also, if people are 
interested we can come up with a howto email on using the new stuff, what 
replaces what, but hopefully it should be pretty self-explanatory by looking 
at the code and test cases we've already redone.


	Chris