My Ingres Blog

classes with similar purpose in DB2 example are in bold. It seems that to implement data access for Ingres, these common classes should be implemented.

For test cases to write, see the info in the google wave post

A natural question: how to configure which database to use?

In org.geotools.data.oracle

1.OracleDateConverterFactory

Implements ConverterFactory

2.OracleDialect

extends PreparedStatementSQLDialect, which in turn implements SQLDialect

3.OracleFilterToSQL

Oracle specific filter encoder, extends PreparedFilterToSQL

OracleNGDataStoreFactory
OracleNGJNDIDataStoreFactory
OracleNGOCIDataStoreFactory
SDO11OracleDialect
SDOOracleDialect
OracleConnectionFactory
OracleDataStore
OracleDataStoreFactory
OracleFeatureLocking
OracleFeatureSource
OracleFeatureStore
OracleFeatureWriter
OracleOCIDataStoreFactory

In org.geotools.data.oracle.attributeio

SDOAttributeIO

In org.geotools.data.oracle.sdo

GeometryConverter

In org.geotools.referencing.factory.epsg

1. FactoryUsingOracleSQL
2. OracleDialectEpsgMediator
3. ThreadedOracleEpsgFactory

I just copy information about code and plan from wave and sum them up a bit

1. UML designed is updated

2. Test

basic plan:Example geospatial data, loaded into Ingres, feeding it to GeoServer (leveraging Geotools with support for Ingres).

run pre existing tests in http://svn.osgeo.org/geotools/branches/2.6.x/modules/library/jdbc/src/test/java/org/geotools/jdbc as well as create our own tests in http://svn.osgeo.org/geotools/branches/2.6.x/modules/unsupported/jdbc/jdbc-ingres/src/test/java/org/geotools/data/ingres (at least one per class).

——

3.

look into OpenGeo http://opengeo.org/community/suite/download/
in particular the GeoServer workshop here: http://workshops.opengeo.org/stack-intro/
diagram in workshop shows GeoServer interacting directly with database. In this diagram geotools would be part of the GeoServer component as GeoServer is built on the geotoolslibary
had trouble installing QGIS, potentially looking into uDig as an alternative for putting data into postgis

Search for types with “DB2″ in their names. I assume that is all database-specific classes we need to implement for Ingres

Data access architecture: http://docs.codehaus.org/display/GEOT/8.4+Data+Access

package org.geotools.data.db2;

1.DB2ConnectionFactory:

deprecated Use {@link DataSource}, {@link DataSourceUtil} and {@link DataSourceFinder} instead

2.DB2DataStore:

DataStore is central in data access

Instances of this class should only be obtained via DB2DataStoreFactory.createDataStore or DataStoreFinder.getDataStore.

3.DB2DataStoreFactory

Implements the DataStoreFactorySpi interface to create an instance of a DB2DataStore.

4.DB2FeatureLocking (extends DB2FeatureStore)

FeatureLocking is used in writing to database.

5.DB2FeatureSource (extends JDBCFeatureSource)

FeatureSource is central in data access.

DB2 Feature Source implementation. Overrides functionality in JDBCFeatureSource to provide more efficient or more appropriate DB2-specific implementation.

6.DB2FeatureStore (extends JDBCFeatureStore)

FeatureStore is used in database wrting.

DB2 FeatureStore implementation. Overrides functionality in JDBCFeatureStore to provide more efficient or more appropriate DB2-specific implementation.

7.DB2FeatureTypeHandler (extends FeatureTypeHandler)

Override methods from FeatureTypeHandler for DB2-specific handling.

(need to research how it is used)

8.DB2FeatureWriter (extends JDBCTextFeatureWriter)

used in writing to DB

9.DB2FIDMapperFactory (extends DefaultFIDMapperFactory)

* Overrides DefaultFIDMapperFactory methods for DB2-specific handling.

(need to research how it is used)

10.DB2GeometryColumn

Hold information about a DB2 geometry column and provide access.

(need to research how it is used)

11.DB2SpatialCatalog

(need to research how it is used)

Manage the DB2 Spatial Extender spatial catalog information in memory to improve performance.

This class is not intended to be used outside the DB2 plug-in package.

Currently, a different catalog is managed for each DB2 database and schema specified in the creation of a DB2DataStore.  Multiple data stores created for the same database and schema can share the same catalog.

All schema, table and column names are case sensitive.

Convenience methods provided for access to various types of catalog information like type names, srid, etc.

* <b>Note: the ‘srid’ value in DB2 is different from the srid value referenced
* in OGC documents.  The OGC srid corresponds more closely to the DB2 ‘csid’
* value. This makes life quite confusing because the DB2 ‘srid’ is needed to
* construct geometries in the database.  GeoTools needs the ‘csid’ which
* generally corresponds to an EPSG coordinate system identifier in order to
* create an OGC coordinate system reference. </b>

* <b> We also assume that there is a single ‘srid’ associated with all the
* geometries in a particular geometry column.  This is not required by DB2.

* Do we need to consider freeing this up at some point as the HashMap of
* catalogs is stored in a class variable?
* </p>

12.DB2SQLBuilder (extends GeoAPISQLBuilder)

A DB2-specific subclass of DefaultSQLBuilder, which supports DB2 Spatial Extender geometry datatypes.

13.DB2NGDataStoreFactory (extends JDBCDataStoreFactory)

DataStoreFactory for DB2 database.

(Notice there are several DataStoreFactory, need to know the difference)

14.DB2NGJNDIDataStoreFactory (extends JDBCJNDIDataStoreFactory)

DataStoreFactory for DB2 database.

15.DB2SQLDialect (extends SQLDialect)

16.DB2SQLDialectBasic (extends BasicSQLDialect)

17.DB2SQLDialectPrepared (extends PreparedStatementSQLDialect)

18.DB2WKBReader

Version of JTS WKB Reader adjusted for DB2

19.DB2WKBWriter

Version of JTS WKB Writer adjusted for DB2

SQLDialect

/**
* The driver used by JDBCDataStore to directly communicate with the database.
* <p>
* This class encapsulates all the database specific operations that JDBCDataStore
* needs to function. It is implemented on a per-database basis.
* </p>
* <p>
*  <h3>Type Mapping</h3>
* One of the jobs of a dialect is to map sql types to java types and vice
* versa. This abstract implementation provides default mappings for “primitive”
* java types. The following mappings are provided. A ‘*’ denotes that the
* mapping is the default java to sql mapping as well.
* <ul>
*   <li>VARCHAR -> String *
*   <li>CHAR -> String
*   <li>LONGVARCHAR -> String
*   <li>BIT -> Boolean
*   <li>BOOLEAN -> Boolean *
*   <li>SMALLINT -> Short *
*   <li>TINYINT -> Short
*   <li>INTEGER -> Integer *
*   <li>BIGINT -> Long *
*   <li>REAL -> Float *
*   <li>DOUBLE -> Double *
*   <li>FLOAT -> Double
*   <li>NUMERIC -> BigDecimal *
*   <li>DECIMAL -> BigDecimal
*   <li>DATE -> java.sql.Date *
*   <li>TIME -> java.sql.Time *
*   <li>TIMESTAMP -> java.sql.Timestmap *
* </ul>
* Subclasses should <b>extend</b> (not override) the following methods to
* configure the mappings:
* <ul>
*   <li>{@link #registerSqlTypeToClassMappings(Map)}
*   <li>{@link #registerSqlTypeNameToClassMappings(Map)}
*   <li>{@link #registerClassToSqlMappings(Map)}
* </ul>
* </p>
* <p>
*
* </p>
* <p>
* This class is intended to be stateless, therefore subclasses should not
* maintain any internal state. If for some reason a subclass must keep some
* state around (not recommended), it must ensure that the state is accessed in
* a thread safe manner.
* </p>

Hierachy:

->BasicSQLDialect->DB2,H2, MySQL,PostGIS,SpatialLite,SQLServer

->DB2SQLDialect

->H2Dialect

->My SQL Dialect

->PreparedStatementSQLDialect->DB2,H2,MySQL, Oracle, PostGIS

* <p>
* A datastore contains a set of entries ({@link ContentEntry}). Each entry
* corresponds to a “real world dataset”. For instance, a shapefile datastore
* would contain a single entry which would represent the shapefile on disk. A
* postgis datastore could contain many entries, one for each table in the database.
* </p>
* <p>
* Each entry is identified by a name ({@link Name}). The name can be qualified
* with a namespace uri, or unqualified (in which the namespace uri is null). An
* example of a datastore that might use qualified names is WFS, where in each
* entry corresponds to a WFS “Feature Type”, which have namespace qualified name.
* Other datastores (such as databases) use unqualified names.
* </p>
* <p>
* When entry names of a datastore are unqualified, a default namespace uri can
* be set “globally” on the datastore itself, see {@link #setNamespaceURI(String)}.
* When this value is set, unqualified entry names are implicitly qualified with
* the global namespace uri.
* </p>
* <h3>Subclasses</h3>
* <p>
* At a minimum subclasses must implement the following methods:
* <ul>
*   <li>{@link #createTypeNames()}
*   <li>{@link #createFeatureSource(ContentEntry)}
* </ul>
* The following methods may also be overriden:
* <ul>
*   <li>{@link #createContentState(ContentEntry)}
* </ul>
* The following methods may be overriden but <b>only</b> to narrow the return
* type to a specific subclass of {@link ContentFeatureSource}.
* <ul>
*   <li>{@link #getFeatureSource(String)}
*   <li>{@link #getFeatureSource(String, Transaction)}
*   <li>{@link #getFeatureSource(Name, Transaction)}
* </ul>
* </p>

Hierachy:DataStore->ConnectionDataStore->JDBCDataStore

Core: the module/main makes up the core geotools library, this library is the required baseline containing:

• Geotools Interfaces (like Feature, DataStore, MapLayer,…)
• Default implementations (like DefaultFeature, MemoryDataStore, …)
• “Helper” classes designed to aid Client code, and plugin writers (like AbstractDataStore, DataUtilites, …)

Plugins: these modules plugin (or aid and abet) the functionality of the core Geotools library

• plugin modules contain a META-INF/services entry describing what the plugin does (plugins can do more then one thing)
• plugin modules may require other plugins inorder to function, as example the plugin/wms requires plugin/epsg inorder to function

Extentions: these modules build on top of Geotools providing new and interesting functionality.

• ext modules do not plugin to Geotools (they don’t contain a META-INF/services entry)
• ext modules build ontop of Geotools just like a regular client application

———

Data Access

DataStore is the Geotools API for data source access. It is used to access both file and Service information. Wide ranges of data sources are supported from simple Shapefile access through to Database and Web Feature Services.

DataStore operates on an OGC FeaModel notable in its use of XPATH queries to access nested attribute type information. Creation of everything from FeatureTypes to Filter Expression is controlled by the use of Facto

org.geotools.data.datastore

As the above diagram illustrates, there are two APIs for access to spatial information:

• FeatureReader: an iterator of Features (sequential access), basically an iterator that is allowed to throw IOExceptions

• FeatureSource: provides getBounds, getCount and getFeatures operations. For most DataStore implementations these are optimized to make use of the native functionality of the underlying service.

Note: In addition to the API above many DataStores implement Catalog to provide access to Metadata based FeatureType queries. In this case the CatalogEntry.getResource() returns the FeatureSource associated with the FeatureType.

FeatureSource is very similar to the geotools FeatureCollection, the difference is:

• FeatureCollection – represents an in memory collection of features, FeatureIterator does not throw Exceptions
• FeatureSource – represents an external source of Features, FeatureReader throws IOExceptions
• FeatureSource provides the read-only representation of an external source of Features, complete with event notification (events changes by BBox and

DataStore offers a comprehensive writing API with support for Transactions and optimized updates.

This time there are four classes to consider:

• Transaction: offers workflow control and rollback. Can be used with several DataStores at once.
• FeatureWriter: an iterator of Features supporting modification.
• FeatureStore: provides add, update and remove as high level requests that are optimized for most DataStores.
• FeatureLocking: offers locking for the duration of a Transaction and WFS Style Long Term Transaction support.

As promised, even DataStore creation is controlled by use of a Factory.

DataAccessFactory provides access to both (complex) Feature and SimpleFeature capable content providers. DataStore specializes in serving SimpleFeature.

The map used to create a DataStore is described by:

• A legacy getParametersInfo() method
• ParameterValueGroup adapted for general use by GeoAPI

There are several difficulties with this approach:

• A Map is not optimal ? for drag and drop support we would like to use a File or URL directly
• The ParameterValueGroup is difficult to understand
• ISO 19119 is designed to describe Services

The plug-in system FactorySPI is used to ?discover? the appropriate DataStoreFactory based on a Map of parameters. In practice many DataStoreFactory implementations require a ?magic? key be entered in Map to support this functionality.

It is likely that DataStore will be simplified over the coming weeks to take these factors into consideration.

(http://docs.codehaus.org/display/GEOT/5.1.1+Coding+Conventions)

We follow:

• Sun’s coding convention: http://java.sun.com/docs/codeconv/
• but allow for 100 characters in width
• developers should use spaces for indentations, not tabulations

The header for all core GeoTools code is:

/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 *
 *    (C) 2004-2009, Open Source Geospatial Foundation (OSGeo)
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */

The header for all demo code is:

/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 *
 *    (C) 2004-2009, Open Source Geospatial Foundation (OSGeo)
 *
 *    This file is hereby placed into the Public Domain. This means anyone is
 *    free to do whatever they wish with this file. Use it well and enjoy!
 */

Get it right the first time - seriously. You cannot expect to go in and reformat your code later in time - because that would make applying fixes between branches of GeoTools impossible.

So if you are going to take the time to use one of these tools - do so on the first commit. And before every commit. After the code is branched you are stuck.

And settings for eclipse

-------------------------
(http://docs.codehaus.org/display/GEOT/5.1.2+Do+not+return+null)
Stop returning null! It sounds easy - and it is. Use one of the many "NullObjects" available to you as a stand in. You are expecting the person calling you to do something when you retuned null right? A NullObject is set up to capture exactly what you expect them to do.

Stop eating exceptions!! Exceptions contains valuable informations about what may have gone wrong. Eating all exceptions is especially bad. Catch only the most specific exceptions you are expecting.

In the bad example above, the exception should at least be logged as below:



Log the exception




try {
    do_some_stuff();
}
catch (SomeSpecificException e){
    LOG.warning("Could not do some stuff: " + e);
    return SOME_EMPTY_OBJECT;
}



An alternative is to invokes some convenience unexpectedException method from the org.geotools.util.Logging class. The examples below use the latest approach.

How to return a "null" List

try {
    return a_set;
}
catch (SomeSpecificException e){
    Logging.unexpectedException(LOG, e);
    return Collections.EMPTY_LIST;
}




How to return a "null" Expression

try {
    return a_expression;
}
catch (SomeSpecificException e){
    Logging.unexpectedException(LOG, e);
    return Expression.NULL;
}




How to return a "null" Filter (negative)

// Often used if it a programmer error encountering a limitation (say SQL encoding)
try {
    return a_filter;
}
catch (SomeSpecificException e){
    Logging.unexpectedException(LOG, e);
    return Expression.EXCLUDES;
}




How to return a "null" Filter (positive)

// Often used if it is a "data problem", return too much data rather then none
try {
    return a_filter;
}
catch (SomeSpecificException e){
    Logging.unexpectedException(LOG, e);
    return Expression.INCLUDES;
}



If you need additional "NullObjects" email the devel list and we will make them happen. We probably should have a NullDataStore and a NullFeatureSource for example ... or throw an Exception.
Drop
Drop the pretense that everything is okay, if you are in a situtation where you are returning null chances are there is a real problem around ... so throw some kind of Exception. This should be used when you have defined your limitations in the javadocs, and the programmer has neglected to read them.

This may require use of runtime exceptions, or the interface you are implementing may already provide a checked exception for you to throw.

Programming Error

try {
    do_some_stuff();
} catch (SomeSpecificException e) {
    return (IOException) new IOException("Could not do some stuff (did you read the javadocs?): "+e).initCause(e);
}



Roll
As a last possible effort; Roll with the flow (but be sure to "log the cause" so client code can notice something is wrong):

Log the Cause

try {
    do_some_stuff();
} catch (SomeSpecificException e) {
    Logging.unexpectedException(LOG, e);
    return null;
}



Be sure to use the warning level (we are still making an assumption) - and client code should know about it). And do not worry about filling up the test case results with garbage; testing code that expected to produce warnings happens all the time (the test case code can change the logging level to "Info" and then set it back).

(http://docs.codehaus.org/display/GEOT/2.5.3+Building+an+individual+module)

Provided you have done at least one complete build you should be able to build individual modules.

1. Change to the modules home directory
   cd $GEOTOOLS_HOME/gt/modules/library/main
2. Use maven to compile
   mvn compile
   It should do a complete build.
3. Use maven to update the registry
   mvn install
   It should run the test cases and install the jar in the registry for other modules (or applications).

You may also notice that running the tests takes a fair wack of time. While these tests need to be run before you commit for the day, you may want to forgo the wait while experimenting.

The following will build the tests – but not run them:

mvn -DskipTests install

This is useful for installing the postgis module test jar; which is used by the postgis-version module as a dependency.

The following will not even build the tests:

mvn -Dmaven.test.skip=true install

----------------------
http://docs.codehaus.org/display/GEOT/2.5.7+Testing+with+Maven - Testing with Maven
http://docs.codehaus.org/display/GEOT/2.5.8+Maven+Eclipse+Plugin+Goals - Maven Eclipse Plugin

————-

(http://docs.codehaus.org/display/GEOT/2.3+Source+Code)

trunk code repository:

http://svn.osgeo.org/geotools/trunk

modules and projects:

• build – java projects that help with our build process
• demo – example code and demos
• modules/library – the core library allowing your application to be spatial
• modules/extentions – extentions built on top of the library that do useful things
• modules/plugins – plugins that work with the core library to support additional formats
• modules/unsupported – code that is not ready yet, but you may find interesting
• spike – a scratch space for ideas and experiments

———————-

(http://docs.codehaus.org/display/GEOT/2.5.1+Build+All+Modules)

Let’s start by going to where you have the source code.

• cd C:\java\geotools\trunk

Make sure you are connected to the internet

Let’s try your first build

• C:\java\geotools\trunk>mvn install

GeoTools plays host to a number of experiment “unsupported” modules; if you would like to help out on any of these modules (or get a preview of new features).

mvn install -Dall

The “-Dall” acts as a switch to part engages several profiles; you can also do this by hand with -P