Added by jgarnett, last edited by jgarnett on Aug 14, 2007

Labels

 
(None)

What API Should I Use?

Ultimately, you will know best what code you need to call to get your application working according to the time frame and maintenance requirements which you have. You have access to all of the code so use it in any way you desire.

However, GeoTools offers a clean approach, which is currently incomplete, but which should cause the least amount of disruption to your code during library upgrades as GeoTools matures.

GeoTools attempts to cleanly separate out several groups of application programming interfaces (API) from the internals of the library. These interfaces are implementations of relevant ISO and OGC standards, as explained in the Use of Standards page. If you write your code against these API, they should remain stable as the library upgrades or, if the library needs to change these interfaces, we guarantee to keep interfaces which will be removed in a functional but deprecated state for a full release cycle to give you time to modify your code.

Interfaces for Concepts and Ideas

Formally these interfaces come from three locations:

  • GeoAPI
  • JTS
  • The API module

Informally there are a few additions:

  • The Referencing Module - is holding the definition of MapContext right now

Ideally, GeoAPI as an OGC project, would be all that was needed. However the project is not currently complete, and lags behind the latest specifications as it depends on volunteer effort. GeoAPI does provide some of the fundamental interfaces (such as all the interfaces involved in the use of Coordinate Referencing System) and is the best game in town. The GeoTools project uses a particular branch of the GeoAPI project which is newer than the last official release but which conforms to Java 1.4 in not using any Java generics.

The JTS Topology System is a de facto standard implementation of the Simple Features for SQL (SFSQL) OGC standard. GeoTools uses this library directly in places to represent Geometry. In the particular case of Geometry, GeoAPI has a set of geometry interfaces to which GeoTools plans to transition to as time permits.

You can make use of these interfaces to represent concepts and data in your application:

  • These interfaces are suitable for use in your method signatures

For more information:

Classes for Coding

In places where we need to do something just to get the job done the GeoTools project does not providing an interface. The GeoTools project has several modules that are stable, and contribute code - interfaces provided by Main, Data, XML, JBDC, and CQL modules are around to get the job done.

Public classes are provided for the purpose of:

  • Helping you glue all the bits together, an example is the various "FactoryFinders" classs
  • GeoTools Extentions provide their own classes

You can make use of public classes in these modules directly, in all cases they are utilities to get the job done.

  • These classes are suitable for use in your import section
  • There is no need to use these classes in your method signatures

Factories for Creation

Interfaces, in the Java language, are unfortunately not enough since one cannot instantiate any objects using only interface methods; some other languages allow constructors in the interfaces. Geotools therefore provides Factory classes which enable users to create the various objects used by the library such as Features, Styles, Filters, CoordinateReferencingSystems, DataStores. While users could find and use each of the various Factory implementations directly, Geotools also provides a FactoryFinder system which automatically locates the appropriate factory implementation available on the classpath and the user code can use that implementation based on the interface definition.

The use of each Factory reflects the objects being instantiated so the Factories are explained in the documentation section appropriate to the module of the objects being built.

Please review the page How to Create Something which outlines how to locate an appropriate implementation at runtime.