The goals of WKB4J are:
There is many geographical toolkits out there, each one modeling the very same things, in slightly different ways: points, lines, polygons... Due to their personal history, some are very close to the WKB format (JTS for example), while some are further away (OpenMap). The goal of WKB4J is to allows the author of each toolkit to integrate easily WKB4J into their own toolkit while maintaining strong performance.
This was accomplished by splitting the driver into three parts: , WKBReader, WKBParser and WKBFactories.
The WKBReader retrieves raw data from a data source. The data is then passed to the WKBParser. Right now the only possible datasource is a PostgreSQL database, but it is trivial to fetch data from files or other databases.
The WKBParser sequentially process the WKB stream and emits calls as it encounter items in the data stream.
Those calls are performed on a WKBFactory provided by the user. This architecture draws from both the Strategy pattern (the WKBFactory is provided by the user so it can really be anything) and the SAX API (an evenmential-base API for XML processing). A WKBFactory is free to answer to calls as it see fit, including ignoring calls. This allows th e author of each WKBFactory to implement the most efficient processing code for its own toolkit. For example, some toolkits handles only immutable objects, while some other allows for object to be constructed incremmentally.
In order to simplify the job of the implementor of a custom factory, several default implementations are provided:
Currently, there is no support for height information in the Simple Features Specification , but it seems that many projects (including PostGIS) implements the Two-and-a-half-D extensions for Simple Features proposal. One important point : it is possible to mix 2D geometries with 3D geometries in "container" geometries (GeometryCollection, MultiPolygon, MultiLineString, MultiPoint) but you can't mix 2D points with 3D points in the same geometries since list of points are actually arrays of doubles without any boundary.
Since it isn't standard, it isn't implemented in the normal WKBFactories and WKBParser. Instead, it is specified in the WKBFactories3D interfaces and the WKBParser3D. Factories that wish to support this specification should implements the WKBFactories3D interface. JTSFactories and PostGISFactory do but OpenMapFactory doesn't since by default, OpenMap doesn't support height information. If your data contains 3D points, you should use the WKBParser3D instead of WKBParser.
The implementation was straightforward, but it did required some modifications to the WKBParser to make it more generic.
Some design decisions are up to grabs.
How do the driver decides that it has seen all the data for a given geometry and that it should move to another geometry.
We can either let the WKBFactory decides for itself by keeping depth counter, or we can have the driver performs calls to signal when geometries begin and where they end. Depth counter adds comparaison everywhere, so they put more burden on the developer of the Factory. Additionnals calls, well, the developers have to implement them, so it isn't much better. I picked the solution of additionnal calls because they actually represent the stream of WKB data while depth counters only predict what should come next.
SRIDs aren't actually part of the WKB format. Nevertheless some toolkits might require their objects to be created with one (JTS).