This implementation is based on the ESRI's ArcSDE Java API. This API is based on a single jar file wich maven downloads automatically and a couple of platform specific libraries (.dll or .so). So we have made an effort in order to this DataStore implementation not being dependant of those native libraries.

The feature set of the ArcSDEDataStore includes feature write support but is actually limited to the inprocess locking manager. Native locking should be developed and will be higly appreciated, so volunteers are wellcome.

Sometime, remote sensing data are not contained in a single file. For example it is common to find sample values in a raw binary file (a flat matrix), and metadata informations in a separated text file. There is a wide variety of formats for such text file, and supporting them is not always straightforward. {@link org.geotools.coverage.io.MetadataBuilder} is a helper class for making easier to parse the header file. The content (the actual pixel values) can be parsed using the {@link org.geotools.image.io} package.

If the operation to apply is know at compile time, then the easiest way to use this package is to use the {@link org.geotools.coverage.processing.Operations} convenience class. For example a {@linkplain org.opengis.coverage.grid.GridCoverage grid coverage} can be resampled to a different {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference system} using the following code:

Coverage reprojected = Operations.DEFAULT.{@linkplain org.geotools.coverage.processing.Operations#resample resample}(myCoverage, newCRS);

If the operation to apply is unknow at compile time (for example because it is selected at runtime by the user in some widget), or if the operation is not listed in the {@code Operations} convenience class, then the generic way is to invoke the {@link org.geotools.coverage.processing.DefaultProcessor#doOperation doOperation} method on the {@linkplain org.geotools.coverage.processing.AbstractProcessor#getInstance default processor instance}. Available operations are listed in the {@linkplain org.geotools.coverage.processing.operation operation package}.

Supported operations

• Convolve
• GradientMagnitude
• Invert
• LaplaceType1Filter
• LaplaceType2Filter
• MaxFilter
• MedianFilter
• MinFilter
• Recolor
• Threshold

Convolve

Computes each output sample by multiplying elements of a kernel with the samples surrounding a particular source sample.

Name: "Convolve"
JAI operator: "{@linkplain javax.media.jai.operator.ConvolveDescriptor Convolve}"
Parameters:

Back to summary

LaplaceType1Filter

Perform a laplacian filter operation on a grid coverage. This is a high pass filter which highlights the edges having positive and negative brightness slopes. This filter mulitples the co-efficients in the tabe below with the corresponding grid data value in the kernel window. The new grid value will be calculated as the sum of (grid value * co-efficient) for each kernel cell divised by 9.

Name: "LaplaceType1Filter"
JAI operator: "{@linkplain javax.media.jai.operator.ConvolveDescriptor Convolve}"
Parameters:

Back to summary

LaplaceType2Filter

Perform a laplacian filter operation on a grid coverage. This is a high pass filter which highlights the edges having positive and negative brightness slopes. This filter mulitples the co-efficients in the tabe below with the corresponding grid data value in the kernel window. The new grid value will be calculated as the sum of (grid value * co-efficient) for each kernel cell divised by 9.

Name: "LaplaceType1Filter"
JAI operator: "{@linkplain javax.media.jai.operator.ConvolveDescriptor Convolve}"
Parameters:

Back to summary

MaxFilter

Non-linear filter which is useful for removing isolated lines or pixels while preserving the overall appearance of an image. The filter is implemented by moving a mask over the image. For each position of the mask, the center pixel is replaced by the max of the pixel values covered by the mask. There are several shapes possible for the mask, which are enumerated in the {@linkplain javax.media.jai.operator.MaxFilterDescriptor JAI documentation}.

Name: "MaxFilter"
JAI operator: "{@linkplain javax.media.jai.operator.MaxFilterDescriptor MaxFilter}"
Parameters:

Note: In current implementation, Xsize and Ysize must have the same value (i.e. rectangular shapes are not supported).

Back to summary

MedianFilter

Non-linear filter which is useful for removing isolated lines or pixels while preserving the overall appearance of an image. The filter is implemented by moving a mask over the image. For each position of the mask, the center pixel is replaced by the median of the pixel values covered by the mask. This filter results in a smoothing of the image values. There are several shapes possible for the mask, which are enumerated in the {@linkplain javax.media.jai.operator.MedianFilterDescriptor JAI documentation}.

Name: "MedianFilter"
JAI operator: "{@linkplain javax.media.jai.operator.MedianFilterDescriptor MedianFilter}"
Parameters:

Note: In current implementation, Xsize and Ysize must have the same value (i.e. rectangular shapes are not supported).

Back to summary

MinFilter

Non-linear filter which is useful for removing isolated lines or pixels while preserving the overall appearance of an image. The filter is implemented by moving a mask over the image. For each position of the mask, the center pixel is replaced by the min of the pixel values covered by the mask. There are several shapes possible for the mask, which are enumerated in the {@linkplain javax.media.jai.operator.MinFilterDescriptor JAI documentation}.

Name: "MinFilter"
JAI operator: "{@linkplain javax.media.jai.operator.MinFilterDescriptor MinFilter}"
Parameters:

Note: In current implementation, Xsize and Ysize must have the same value (i.e. rectangular shapes are not supported).

Back to summary

Recolor

Changes the colors associated to arbitrary {@linkplain org.geotools.coverage.Category categories} in arbitrary bands. The ColorMaps arguments must be an array of {@link java.util.Map}s with a minimal length of 1. The Map in array element 0 is used for band 0; the Map in array element 1 is used for band 1, etc. If there is more bands than array elements in ColorMaps, then the last Map is reused for all remaining bands.

For each {@link java.util.Map} in ColorMaps, the keys are category names as {@link java.lang.String} and the values are colors as an array of type {@linkplain java.awt.Color}[]. All categories with a name matching a key in the Map will be {@linkplain org.geotools.coverage.Category#recolor recolored} with the associated colors. All categories with no corresponding entries in the Map will be left unchanged. The null key is a special value meaning "any quantitative category". For example in order to repaint forest in green, river in blue and lets other categories unchanged, one can write:

    Map map = new HashMap();
    map.put("Forest", new Color[]{Color.GREEN});
    map.put("River",  new Color[]{Color.BLUE });
    Map[] colorMaps = new Map[] {
        map  // Use for all bands
    }
    

Name: "Recolor"
JAI operator: N/A
Parameters:

Back to summary

Threshold

A gray scale threshold classifies the grid coverage values into a boolean value. The sample dimensions will be modified into a boolean value and the dimension type of the source sample dimension will be represented as 1 bit.

Name: "Threshold"
JAI operator: "{@linkplain javax.media.jai.operator.BinarizeDescriptor Binarize}"
Parameters:

Back to summary

All DataStores (e.g. PostGIS, Shapefile(tm), GML...) must provide implementations of the DataStore interface and the DataStoreFactorySpi interface. These interfaces allow new types of datastore to be plugged into applications which use geotools without the need to modify any code.

Example:

FeatureStore postgis = new PostGisDataStore( ... );
Query all = Query.ALL;
FeatureType roadType = postgis.getFeatureType( "roads" );

// reader 1 streams over all roads
FeatureReader reader1 = postgis.getFeatureReader( roadsType, all, Transaction.AUTO_COMMIT );

// allRoads = featureResults is a prepaired query of all roads
FeatureSource roads = postgis.getFeatureSource( "roads" );
FeatureResults allRoads = roads.getFeatures( all );

// reader 2 & 3 streams over all roads in the same manner as reader 1
FeatureReader reader2 = allRoads.reader();
FeatureReader reader3 = allRoads.reader();

// bounds1 returns the bounding box of roads, may be null depending on expense
Envelope bounds1 = roads.getBounds( all );

// bounds2 returns the bounding box of roads, may actually calculate by going over the entire dataset
Envelope bounds 2 = allRoads.getBounds(); 

This package contains the implementation of a ComplexDataStore,

Author note: though this "Complex" datastore has born to provide complex features out of a simple features data source, it may be better called a DerivativeDataStore or something like that, you'll see why later.

This DataStore implementation acts as a wrapper over one or more DataStores, from now on, the surrogate DataStores, and allows to specify a series of mappings between the properties of surrogate FeatureTypes and output schemas. This mappings, in turn, allows to specify properties of the target FeatureTypes as being derivated by the evaluation of an org.geotools.filter.Expression defined against the surrogate FeautreType.

So, what is this useful for? Suppose you have a database of feature types you need to serve out of your office or organization. Furthermore, suppose you need to serve that data in an externally defined schema (like one defined by INSPIRE or any other organization). Obviously you don't want to rearchitect your database to conform to that schema! And indeed you probably even can't do that without the assistance of some kind of object-relational mapping layer. Now you can better figure out what this ComplexDataStore is about if you think on it as a kind of object-relational mapping layer, but targeted to GIS data. Though not exact, this pseudo definition can help you understand it if its your first time reading this document.

Of course it has nothing to do with relational databases directly, but with mapping an existing GeoTools FeatureType from your internal storage schema to an externally defined one, which we're getting used to call "community schemas".

How does ComplexDataStore achieves that?
You need:

• An output (community) schema. This schema exists independently of your actual data structures, so it will be loaded from a GML schema file, defined in XML Schema language.
• An input FeatureType. GeoTools FeatureTypes are exposed by GeoTools DataStores, so you need a way to specify the DataStore's connection parameters and the source FeatureType name.
• The attribute and attribute id mapping definitions. They consists of a series of couples of XPath and OGC Filter 1.0 Expressions. The former addresses the output schema properties and the later defines how the value of that properties are derived from the source Feature instances.

To persist this information, use a XML file which contains this definitions, and whose location in the form of an URL must be used to create a DataStore instance through the GeoTools DataStoreFinder lookup system.

The AbstractGridFormat class is a helper class to make implementing GridFormats simpler.

This package provides the base interfaces needed to support the concept of a {@linkplain org.opengis.catalog.Catalog catalog} of {@linkplain org.opengis.catalog.CatalogEntry catalog entries}. Catalog access is granted by both an iterator, and a query method. The query language is not specified by this api, although the specification expects it to perform similarly to the Simple Feature.

NOTE:
The specification Catalog Services 1.1.1 does not specify the methods of the {@link org.opengis.catalog.CatalogEntry} interface. The methods in this interface were inferred from reading the abstract catalog specification: Catalog Services section 3.1.2.

Representation of Metadata

We could not decide on a unified approach for the representation of Metadata. The choices were between ISO 19115, ISO 19119 and the Dublin core. Our feedback for implementing ISO 19115 is described in the {@link org.opengis.metadata} package.

Our insight came when examining the Catalog Services 1.1.1 document - in the abstract catalog specification: CatalogServices section 3.1.2. By making real classes out of these definitions we have been able to programatically declare the api used by catalog services {@link org.opengis.catalog.QueryDefinition} to access metadata without being tied to a specific Metadata standard.

Specifically the following definitions:

• 4.6 Metadata dataset - Metadata describing a specific dataset [ISO 19101]
• 4.7 Metadata entity - Group of metadata elements and other metadata entities describing the same aspect of data.
  • NOTE 1: A metadata entity may contain one or more metadata entities.
  • NOTE 2: A metadata is equivalent to a class in UML terminology [ISO 19101].
• 4.8 Metadata schema - Conceptual schema describing metadata.
  • NOTE ISO 19115 describes a standard for a metadata schema [ISO 19101]

From these definitions we have formalized the following:

• {@link org.opengis.catalog.MetadataEntity}
• {@link org.opengis.catalog.MetadataEntity.EntityType}
• {@link org.opengis.catalog.MetadataEntity.Element}

This abstraction allows our implementation of ISO 19115 ({@link org.opengis.metadata}) to exist independently of {@link org.opengis.catalog.Catalog}, {@link org.opengis.catalog.CatalogEntry}, {@link org.opengis.catalog.QueryDefinition} and {@link org.opengis.catalog.QueryResult}.

Package Specification

This package is based on the following specifications:

• Topic 13 - Catalog Services version: 4 (Abstract Specification)
• OpenGIS® Catalogue Services Specification version: 1.1.1 (Implementation Specification)

• OpenGIS® Catalogue Services Specification version: 2.0 (Implementation Specification)

Q: Is practice of creating objects for MetadataEntity, Element and EntityType not in the spirit of the specification, if so can they recommend an alternative? One alternative would be to port the CORBA IDL from v2. Problem is InsertMetadata/UpdateMetadata using "any payload".

Q: Does the Catalog v2 section 10: HTTP protocol binding replace the Web Registry Service draft document? Or should we expect any progress on that front?

Related Documentation

• {@link org.opengis.metadata} - ISO 19115 (TC211) Metadata specification
• {@link org.opengis.filter} - defines a query language similar in scope to QueryDefinition

Directory DataStore

Overview

This package represents the functionality required to chain datastores, ie. to represents a directory of mixed file types as a single datastore. Inlcuded are the required interfaces and default implementations for datastores which wish to support single file reading, and as such be included as a datatype for the directory datastore.

Extensions

Addition formats may be included simply by having the dataStore extend AbstractFileDataStore and the DataStore Factory extending FileDataStoreFactorySpi. You will also have to fill in the META_INF directory in similar to a generic dataStore.

Example Use:

Package Specification

The current implementation is targeted towards the 1.3.0 OGC WMS Implementation Specification. There are plans to generalize this support for previous revisions.

• http://www.opengis.org/specs/ and search for wms

Related Documentation

• http://docs.codehaus.org/display/GEOTOOLS/Grid+Coverage+tutorial

Several of the GeoTools objects are produced in reference to specifications, in particular XML based specifications. Often we try and match the same abstractions present in a specification like SLD or Filter. But rather then make use of pure Java Beans, and make user interface code responsible for managing a host of listeners we are providing a single set of listeners located at the object matching the document base.

For more Details:

• This design is similar to EMF, or JFace use (aka borrow code examples)
• Not specific to Documents (just nesting), the Catalog api will use these events
• We do try and match the document structure perfectly for Feature/FeatureCollection/GML (so that the same XPath expressions can be respected). FeatureCollection and Feature have their own well explored structure and issues and will not be using this event system. Given the size of FeatureCollections it is not practicle for each child to "know" its parent.

References

• Eclipse Modeling Framework
• JFace

Because Geotools core API consists almost exclusively of interfaces (including GeoAPI), factories play a role in how developers use the API. Although the interfaces that are declared in GeoAPI are implemented in various Geotools packages you should not use those classes directly. Instead you should use factories.

J2SE's {@link javax.imageio.spi.ServiceRegistry} provides a general way (even if it is defined in a {@code javax.imageio} subpackage) to instantiate and manage factories (also called providers). Each factory implementation should be declared in {@code META-INF/services} directory, usually bundled in every JAR file. For example if a JAR file provides one or more {@link org.opengis.referencing.datum.DatumFactory} implementations, then it must provide the following file:

META-INF/services/org.opengis.referencing.datum.DatumFactory

with a content similar to the one below:

com.mycompany.MyDatumFactory1
com.mycompany.MyDatumFactory2
com.mycompany.MyDatumFactory3

The ordering is initially unspecified. Users can {@linkplain javax.imageio.spi.ServiceRegistry#setOrdering set an ordering} explicitly themselves, or implementations can do that automatically {@linkplain javax.imageio.spi.RegisterableService#onRegistration on registration}. The {@link org.geotools.factory.AbstractFactory} class provides a simple way to setup ordering on registration on the basis of a {@linkplain org.geotools.factory.AbstractFactory#priority priority} number.

If a user wants a specific implementation, he can {@linkplain javax.imageio.spi.ServiceRegistry#getServiceProviders iterates through registered ones} and pickup the desired implementation himself. An alternative is to bundle the criterions in a {@linkplain org.geotools.factory.Hints map of hints} and lets the registry selects an implementation accordingly. This later functionality is not provided by the standard {@link javax.imageio.spi.ServiceRegistry}, but is provided by Geotools's {@link org.geotools.factory.FactoryRegistry} extension. This class extends the service registry API with the following functionalities:

• A {@link org.geotools.factory.FactoryRegistry#scanForPlugins() scanForPlugins()} method that scans for plugins in the {@linkplain java.lang.Class#getClassLoader registry class loader}, the {@linkplain java.lang.Thread#getContextClassLoader thread context class loader} and the {@linkplain java.lang.ClassLoader#getSystemClassLoader system class loader}. Additionally, {@code scanForPlugins()} looks for any implementation specified as {@linkplain java.lang.System#getProperty(String) system property}.

• Filters out automatically {@linkplain org.geotools.factory.OptionalFactory optional factories} when they are not {@linkplain org.geotools.factory.OptionalFactory#isAvailable available}.

• When more than one implementation is available for the same {@link org.geotools.factory.Factory} subinterface, an optional set of {@linkplain org.geotools.factory.Hints hints} can specifies the criterions that the desired implementation must meets. If a factory implementation depends on other factories, the dependencies hints are checked recursively.

• Optionally, if no factory matches the given hints, a new instance can be {@linkplain org.geotools.factory.FactoryCreator#createServiceProvider automatically created}. However, those new instances are not registered. If creation of new instances at every {@link org.geotools.factory.FactoryRegistry#getServiceProvider getServiceProvider(...)} method invocation is undesired, an implementation matching the expected {@linkplain org.geotools.factory.Hints hints} should be registered in the {@code META-INF/services} directory, as explained above.

Note that the {@linkplain org.geotools.factory.Hints hints}, if provided, don't need to apply directly to the requested factory category. They may apply indirectly through some dependency. A typical example is a request for any {@link com.vividsolutions.jts.geom.GeometryFactory} instance, providing that this instance uses a particular {@link com.vividsolutions.jts.geom.CoordinateSequenceFactory} implementation.

References

• Simple Features for SQL

Meaning of FeatureCollections

FeatureCollections can be grouped into the following categories:

• FeatureCollection - providing access to a set of Features, both bounds and count are supported (although you are warned that both may be O(N))
• RandomFeatureAccess - provides access to Feature by ID
• FeatureList - provides access to sorted set of Features

• Explicit: FeatureCollection.sort( SortBy ) returns a FeatureList
• Explict: FeatureCollection.filter( Filter ) returns a FeatureCollection
• Implicit: FeatureList.filter( Filter ) returns a FeatureCollection, impled that this instance also is an instnaceof FeatureList

Use of SortBy and Filter

  FeatureList list = featureCollection.filter( filter ).sort( sort );  
  

In addition to working directly with a "view" you can often use this technique to stage an opperation such as addAll or remove.

  collection.addAll( list.filter( filter ) );
  list.filter( filter ).remove();
  

Seperation Of Concerns

By using the sub collection opperations such as sort and filter you can carefully define set of data you wish to query against. This seperation of concerns can be maintained by ensuring the use of Expression when accessing content, and not acceing content directly.

This seperation of concerns is manditory for geotools library code, and is strongly recommended for client code.

Choosing a FeatureCollection Implementation for Client Code

The most basic FeatureCollection available in this package is the one that store information completly in memory. This is designed to be used by end users and is available for construction via a FeatureFactory (or SimpleFeatureFactory as required).

A common request involves using a MemoryFeatureCollection to cache information for display. You are warned that this approach will often fail in real GIS useage where the quantity of information can not be limited by memory.

Implementing a FeatureCollection Implementation as a Data Provider

As a Data provideder you are expected to extend the AbstractFeatureCollection classes provided here to make the most performant implementation of feature access you can.

• All FeatureCollection Implementation: required to represent all content on accessed with Transaction.AUTO_COMMIT, bounds and count information provided by metadata. This implementation is mostly used to defined sub collections via filter and sort methods.
• "Sub"FeatureCollection Implementation: produced in response to a filter or sort method should be either lazy, or backed by a result set obtained by the first opperation. A cache may be emplyed for information such as bounds and count.
• FeatureList Implementation: if for file or feature result can be sorted (either via an initial SQL request or via consulting an attribute index file) you can "out" this capability to your end users by use of a FeatureList.
• Getting Spatial with your Collections: many spatial file formats can make use of a spatial index (or SFSQL class) to provide an optimized experience. If possible please engage this early and often as we are spatial library, on a related note GeometryAttribute and Feature both support the settings of bounds, if this information is available please make use of it to prevent the running an expensive bounds calculation in software.

A word about Simple Features

The SimpleFeature interface is by no means required, it only represents a set of additional methods that can be defined safely when the content is a flat ordered list of atomic types with no multiplicity as dictated exactly in agreement with their type definition.

What does this mean for a FeatureCollection? For a SimpleFeatureCollection no attributes are supported at the SimpleFeatureCollectionType level, and the content members are restricted to a belonging single SimpleFeatureType.

References

• Simple Features for SQL

Common Query Language (CQL)

CQL BNF with SQL Extensions

The original BNF was extended thinking in a SQL where expression. The original BNF is reproduced to indicate the extensions highlighted with bold characters.

Extensions in original BNF

	
    <SequenceOfSearchConditions > ::= 
              <search condition> 
         |    <SequenceOfSearchConditions> ";" <search condition> 
     
    
    <between predicate> ::= 
    		<attribute name> [ NOT ] BETWEEN <literal> AND < literal > 
	
    <routine invocation> ::= 
             <geoop name><georoutine argument list>
           | <relgeoop name><relgeoop argument list>
           | <routine name><argument list>
           | <BBOX> <bbox argument list>	
           
    <geoop name> ::= 
           EQUAL | DISJOINT | INTERSECT | TOUCH | CROSS | 
           WITHIN | CONTAINS |OVERLAP | RELATE [1]
      
    <bbox argument list>::= 
       "(" <attribute> ","<min X> ","<min Y> ","<max X> ","<max Y>["," <crs>] ")"
    <min X> ::= <signed numerical literal> 
    <min Y> ::= <signed numerical literal> 
    <max X> ::= <signed numerical literal> 
    <max Y> ::= <signed numerical literal>
    <crs> ::= [2]  
      
      
    [1] RELATE is not supported (implementation in GeoTools is required)
    [2] If not supplied, the BoundingBox CRS is EPSG:4326.

    

Implementation Notes

The parser was generated using javacc. In expr.jjt file you can see the input grammar for javacc required to parse CQL with extensions.

This implementation does not check CRS. The problem can be solved adding tokens (standards simbols in grammar) or checking in semantic actions consturction (FilterBuilder). The last solution requires to fix a bug retrieved the correspondent factory for crs (srs).

This package is going to be "evolutionary", rather than "revolutionary". As functionality is added to the package, this page will be updated. This page should be considered a current synopsis of the capabilities of the module.

Revision Date

Requirements

• javax.media.jai.JAI
• com.sun.media.jai.operator.ImageReadDescriptor
• com.sun.media.imageio.plugins.tiff.GeoTIFFTagSet

Other classes are of course necessary to successfully read in the GeoTIFF image. As they typically come bundled with one or more of the above, they are assumed to be present if all of the above are present.

CRS Information

The ability of the GeoTiff module to interpret and accurately express the geographic information encoded in the GeoTIFF file relies strongly on it's ability to use the Geotools framework to construct a meaningful coordinate reference system (CRS) object. Geotools has a number of Authority Factories which take care of constructing CRS information given the code assigned to that CRS.

The central problem is that a complete CRS is composed of many smaller pieces (coordinate systems (CS), datums, and coordinate operations.) Each of these smaller peices is assigned a code for berevity. So when a GeoTIFF file is written, the coordinate information can either be a single code representing the entire CRS (if you're lucky), or a combination of each of the component codes. Reading a GeoTIFF involves the reverse process: looking up either a single code or a collection of the component codes and building up a CRS object from these components.

Geotools supports the looking up of EPSG codes in plugins. Therefore it is critical that the environment inside which the GeoTIFF plugin is running contain the appropriate epsg authority factory plugins. Unfortunately, the definition of "appropriate" varies according to the type of GeoTIFF file you are trying to read. If you know that your GeoTIFF file contains only codes for complete CRSes, then you can use an EPSG plugin which only looks up complete CRSes (e.g., epsg-wkt, the property file based EPSG authority factory.) If, however, you want to be able to handle more types of GeoTIFF files (perhaps you do not know where your GeoTIFF files are coming from), you must choose an EPSG authority factory which can lookup components of a CRS (e.g., epsg-access, the MS Access backed authority factory.)

In short, the exact means by which EPSG codes are turned into actual Java Objects is left up to the application writer. Ensure that the capabilities you have configured match the requirements imposed by the data you are trying to read.

Current Functionality

The current iteration of the GeoTIFF plugin will read GeoTIFF files with the following restrictions:

• The coordinate system must be either projected or geographic (geodetic coordinate systems not supported.)
• The EPSG authority factory plugin chosen by the application writer must successfully construct everything necessary to represent the scene coordinates.
• The Raster to Model transformation must be a simple translation.
• This plugin does not use the "Hints" mechanism as of yet. I don't know how to have the user specify the EPSG factories they wish to use.
• When constructing a user defined projected CRS, the Cartesian CS associated with the system always has easting as the first axis and northing as the second axis, and the units are always the length units defined in the GeoTIFF file. I do not know if it is possible to have a different combination.

The GeoTIFF plugin currently does not write GeoTIFF files. The current obstacles to writing a GeoTIFF file are:

1. The GeoTiffIIOMetadataAdapter cannot modify the IIOMetadata object (e.g., it's read-only).
2. No mechanism exists to examine the parameters of a coordinate system and produce an EPSG code.

Key features of the package:

1. Has a reasonable level of isolation from the Geotools library ala the GeoAPI interfaces. Areas of best isolation are CRS, and areas of worst isolation are the grid coverage exchange API.
2. Utilizes the JAI ImageI/O tools to perform the actual file I/O.
3. Interprets metadata retrieved as IIOMetadata.
4. Functionality is logically subdivided:
   • Classes required to interface to Geotools.
   • An adapter class to retrieve GeoKeys from the IIOMetadata by symbolic name (GeoTiffIIOMetadataAdapter).
   • An adapter class to interpret the values in the GeoKeys and create a corresponding coordinate system with a factory (GeoTiffCoordinateSystemAdapter).

License Information

The {@link org.geotools.geometry.GeneralDirectPosition} class represents a point in a multi-dimensional space. This space may have an arbitrary number of dimensions. For a two-dimensional space, DirectPosition is conceptually equivalent to {@link java.awt.geom.Point2D}.

The class {@link org.geotools.geometry.GeneralEnvelope} represents a box in a multi-dimensional space. For a two-dimensional space, Envelope is conceptually equivalent to {@link java.awt.geom.Rectangle2D}.

Reads GML files and translates them into Java objects.

Note that the final OGC simple geometry types used by these classes are the ones developed by Vivid Solutions as part of the Java Topology Suite.  However, this not the only type of Java object that may be generated by using this suite of filters.  For example, you could implement a GMLGeometryHandler to create custom geometry types or to store OGC simple types in your own custom format.  The illustration shows how this works.

GMLDocumentFilter reads in an arbitrary XML file, extracts all GML-namespace associate elements, and translates them into primitive geometry calls, handled by the GMLGeometryHandler.  Essentially, GMLDocumentFilter handles all coordinate parsing so that handlers further down the chain never see any character data within GML objects.

GMLGeometryFilter implements a GMLGeometryHandler and uses the SubHandlers to create finished JTS-based geometries.  This is the only object that GMLGeometryFilter passes on down the chain from the GML namespace.  All other XML is passed through without modification.

{@link org.geotools.image.io.StreamImageReader} is the base class for image decoders reading stream with few (if any) meta-data. Examples of such streams are matrix containing the pixels values in a binary form (RAW images), or ASCII files containing values written as decimal numbers. Such files contain often geophysical values (e.g. temperature in Celsius degrees, elevation in metres, etc.) better represented as floating point numbers than integers.

By default, {@link org.geotools.image.io.StreamImageReader} stores decoded image using data type {@link java.awt.image.DataBuffer#TYPE_FLOAT} and a grayscale color space. This politic produce images matching closely the original data, i.e. it involves as few transformations as possible. But displaying floating-point images is usually very slow. Users are strongly encouraged to use Java Advanced Imaging's operations after reading in order to scale data as they see fit. The example below reformats the {@link java.awt.image.DataBuffer#TYPE_FLOAT} data into {@link java.awt.image.DataBuffer#TYPE_BYTE} and changes the grayscale colors to an indexed color model.

import {@link javax.media.jai.JAI javax.media.jai.JAI};
import {@link javax.media.jai.ImageLayout javax.media.jai.ImageLayout};
import {@link java.awt.RenderingHints java.awt.RenderingHints};
import {@link java.awt.image.DataBuffer java.awt.image.DataBuffer};
import {@link java.awt.image.IndexColorModel java.awt.image.IndexColorModel};
import {@link java.awt.image.renderable.ParameterBlock java.awt.image.renderable.ParameterBlock};

// Omitting class and method declaration...


/*
 * Prepare the indexed color model. Arrays
 * R, G and B should contains 256 RGB values.
 */
final byte[] R=...
final byte[] G=...
final byte[] B=...
final IndexColorModel colors = new IndexColorModel(8, 256, R,G,B);
final ImageLayout     layout = new ImageLayout().setColorModel(colorModel);
final RenderingHints   hints = new RenderingHints(JAI.KEY_IMAGE_LAYOUT, layout);

/*
 * Rescale the image.   First, all pixels values are transformed using
 * the equation pi=CO+C1*p. Then, type float is clamp to type byte and
 * the new index color model is set.   Displaying such an image should
 * be much faster.
 */
final double C0 = ...
final double C1 = ...
image = JAI.create("Rescale", new ParameterBlock().addSource(image).add(new double[]{C1}).add(new double[]{C0}));
image = JAI.create("Format",  new ParameterBlock().addSource(image).add(DataBuffer.TYPE_BYTE), hints);

This package defines a {@link org.geotools.image.io.metadata.GeographicMetadataFormat geographic metadata format} which is aimed as image format neutral. The metadata format defines a structure for a tree of nodes in a way similar to the way methods are defined in GeoAPI interfaces. For example it defines a {@code "CoordinateReferenceSystem"} node with {@code "CoordinateSystem"} and {@code "Datum"} child nodes.

The {@link org.geotools.image.io.metadata.GeographicMetadata} class contains convenience methods for encoding metatadata. Metadata are usually given as {@link java.lang.String} or {@code double} attributes only, but image readers can optionaly attach fully constructed GeoAPI objects if they wish. If only {@link java.lang.String} and {@code double} are used, then the duty to create GeoAPI objects from them incomb to the {@link org.geotools.coverage.io} package.

This package should not be used directly, since providers are declared in the {@code META-INF/services/} directory.

The gt2-imageio.jar file declares a service provider for the following image readers:

Example: a user may want to read an ASCII file containing gridded elevation on the ocean floor (left side below). The {@link org.geotools.image.io.TextRecordImageReader} class can read such file, detect automatically minimum and maximum values (in order to scale the grayscale palette) and produce the image below:

Longitude Latitude Altitude 59.9000 -30.0000 -3022 59.9333 -30.0000 -3194 59.9667 -30.0000 -3888 60.0000 -30.0000 -3888 45.0000 -29.9667 -2502 45.0333 -29.9667 -2502 45.0667 -29.9667 -2576 45.1000 -29.9667 -2576 45.1333 -29.9667 -2624 45.1667 -29.9667 -2690 45.2000 -29.9667 -2690 45.2333 -29.9667 -2692 45.2667 -29.9667 -2606 45.3000 -29.9667 -2606 45.3333 -29.9667 -2528 etc...

The JAI operations provided in this package should be registered automatically at JAI startup time, since they are declared in the {@code META-INF/registryFile.jai} file. However, this default JAI mechanism may fail in some occasions, for example when the Geotools JAR file is unreachable from the JAI class loader. In such case, the {@link org.geotools.image.jai.Registry#registerGeotoolsServices registerGeotoolsServices} method may be invoked programmatically as a fallback. This is done automatically by the {@link org.geotools.coverage.processing} package; users need to care only if they want to use directly the custom JAI operations provided in this package.

Possible metadata implementations (already available or planed in a future Geotools version) are:

• {@link org.geotools.metadata.iso}: concrete implementation of ISO interfaces, including ISO 19115.

• {@code org.geotools.metadata.dublin}: concrete implementation of Dublin core interfaces. Not yet implemented.

• {@link org.geotools.metadata.sql}: implementation of metadata interfaces backed by a SQL database. The metadata interfaces doesn't need to be ISO ones, which is why this package is not a sub-package of the ISO's one.

• {@code org.geotools.metadata.xml}: implementation of metadata interfaces backed by a XML files. The metadata interfaces doesn't need to be ISO ones, which is why this package is not a sub-package of the ISO's one. Not yet implemented.

• Sea water properties (density, sound velocity, fusion temperature, etc.) computed from salinity, temperature and pression using algorithms published by UNESCO.
• Values relative to earth calendar, like tropical year length.
• etc.

Compilation and deployment instruction

All {@code XFoo} Java interfaces are generated from IDL files with the same name. As long as {@code XFoo} Java/IDL interfaces are not modified, there is no need for the OpenOffice SDK. But if any {@code XFoo} interface is modified, then steps 1 to 3 below must be done. Steps 5 to 7 are performed by Maven, but are cited here for completness. Step 8 must be executed on the client machine (users can also use the "Tools / Package manager" menu from OpenOffice GUI).

The starting point is often {@link org.opengis.parameter.ParameterDescriptorGroup}. Operation implementations need to defines one. Operation usages typically invoke its {@link org.opengis.parameter.ParameterDescriptorGroup#createValue createValue} method and fill the returned object with parameter values. This Geotools package provides the following implementations:

• {@link org.geotools.parameter.DefaultParameterDescriptorGroup} for the general case.

• {@link org.geotools.parameter.ImagingParameterDescriptors} for wrappers around {@linkplain javax.media.jai.ParameterListDescriptor Java Advanced Imaging's parameters}.

• {@link org.geotools.parameter.MatrixParameterDescriptors} for matrix parameters, including the number of rows and columns. The total number of parameters in this group vary according the number of rows and columns.

This package provides implementations for general positioning, coordinate reference systems (CRS), and coordinate transformations. Coordinates can have any number of dimensions. So this implementation can handle 2D and 3D coordinates, as well as 4D, 5D, etc.

This package provides a special implementation of {@linkplain org.geotools.referencing.NamedIdentifier identifier}, which is also a {@linkplain org.opengis.util.GenericName generic name}. By implementing those two interfaces, it is possible to use the same kind of object for specifying both the {@linkplain org.geotools.referencing.AbstractIdentifiedObject#getName main identifier} and the {@linkplain org.geotools.referencing.AbstractIdentifiedObject#getAlias aliases} of an {@linkplain org.geotools.referencing.AbstractIdentifiedObject identified object}.

All factory methods are capable to find an object using an unscoped (or local) name. However, in order to avoid potential conflict, it is recommanded to use scoped name when possible. For example even if both can work, prefer "EPSG:9624" instead of "9624" for the affine transform in order to avoid potential conflict with an other authority using the same code number.

Command-line tools

A set of command lines tools is provided for performing queries. The tools are implemented in the main method of some key classes. The tools are:

{@link org.geotools.referencing.crs.AbstractCRS} is the base class for all coordinate reference systems (CRS). CRS can have an arbitrary number of dimensions. Some are two-dimensional (e.g. {@link org.geotools.referencing.crs.DefaultGeographicCRS GeographicCRS} and {@link org.geotools.referencing.crs.DefaultProjectedCRS ProjectedCRS}), while some others are one-dimensional (e.g. {@link org.geotools.referencing.crs.DefaultVerticalCRS VerticalCRS} and {@link org.geotools.referencing.crs.DefaultTemporalCRS TemporalCRS}). Those simple coordinate systems can be used as building blocks for more complex coordinate reference systems. For example, it is possible to construct a three-dimensional CRS with (latitude, longitude, time) with an aggregation of {@link org.geotools.referencing.crs.DefaultGeographicCRS GeographicCRS} and {@link org.geotools.referencing.crs.DefaultTemporalCRS TemporalCRS}. Such aggregations are built with {@link org.geotools.referencing.crs.DefaultCompoundCRS CompoundCRS}.

Geotools provides some convenience methods for fetching specific coordinate values in standard units. For example the {@link org.geotools.referencing.cs.DefaultEllipsoidalCS} class provides a {@link org.geotools.referencing.cs.DefaultEllipsoidalCS#getLongitude getLongitude} method that returns the longitude value in a given set of coordinates. This convenience method free the user from the task of finding which axis is for the longitude, and performing unit conversion.

Extensions to OpenGIS API

Convenience methods were added to the {@linkplain org.geotools.referencing.datum.DefaultEllipsoid default ellipsoid} class in order to compute orthodromic distance.

EPSG codes are numerical identifiers. For example "4326" is the EPSG identifier for the "WGS 84" geographic CRS. However, the default implementation accepts names as well as numeric identifiers. For example "NTF (Paris) / France I" and {@code "27581"} both fetchs the same object. Note that names may be ambiguous since the same name may be used for more than one object. This is the case of "WGS 84" for example. If such an ambiguity is found, an exception will be thrown.

An EPSG authority factory is created using the following code:

{@linkplain org.opengis.referencing.crs.CRSAuthorityFactory} factory = {@linkplain org.geotools.referencing.ReferencingFactoryFinder}.getCRSAuthorityFactory("EPSG", null);

This package provides the general framework for accessing an EPSG database, but the actual connection to a database requires the existence of an EPSG plugin in the classpath. Otherwise, a {@link org.geotools.factory.FactoryNotFoundException} will be thrown. Available plugins are:

• {@code CRS} space
• {@code AUTO2} space: automatic projections (dynamic projections) based on code and location:
  • {@code AUTO2} projection codes are in the range 42000-42499
  • lon0 and lat0 are central point of the projection
  • The lon0/lat0 are provided by the SRS parameter of the map request.

Those CRS are defined in Annex B (CRS definitions) of ISO 19128 (Web Map Service Implementation Specification).

How to know the available {@linkplain org.opengis.referencing.operation.MathTransform math transforms}

The {@linkplain org.geotools.referencing.operation.DefaultMathTransformFactory math transform factory} search for all math transforms in the class path, not just Geotools implementations. To be found, math transforms must be registered as services in its JAR file, more specifically in the following JAR entry:

META-INF/services/org.geotools.referencing.operation.MathTransformProvider

{@link org.geotools.referencing.operation.DefaultMathTransformFactory} can be run from the command line in order to gets the list of all registered math transform, as in the example below:

java org.geotools.referencing.operation.DefaultMathTransformFactory

This will print a table with the name of all math transforms. If a name from this list is specified as a command-line argument, then the parameters expected by the nammed math transform will be listed. The example below prints the arguments expected by the "Mercator 1SP" map projection:

java org.geotools.referencing.operation.DefaultMathTransformFactory Mercator_1SP

Note that instead of the "Mercator_1SP" argument, alias can be specified as well. For example, "EPSG:9804" or just "9804" will produce the same result than above.

A package of convenience classes which use control points common to two data sets to derive empirically the transformation parameters needed to convert positions between the coordinate systems of the two data sets.

Note the implementation is currently (January 2008) limited to two dimensions. The methods, however, are generic and could be expanded to three dimensions someday. At that time, we will probably make minor changes to the API.

The package consists of two types of convenience classes: the various builder classes which use a set of individual control points to obtain the conversion and the GridToEnvelopeMapper class which derives the conversion from a grid range to a georeferenced Envelope.

The builder classes should be used by users who have two data sets that are known to share certain common points but who currently do not line up. This could be the case, for example, if a user has two data sets describing the same region but one of these has an unknown coordinate referencing system. In this situation, there is no way to convert coordinate positions between the two data sets. However, if the user can identify a series of positions coupled in each data set, a Builder can calculate an empirical conversion between the two data sets. The different Builder classes use different mathematical approaches to obtain the empirical estimate.

The GridToEnvelopeMapper should be used by users who have a grid, such as an image, which is not georeferenced but the user knows the grid is aligned in one of the four cardinal directions and the user can identify the outer georeferenced envelope of the grid. The Mapper class can then calculate an empirical conversion object to map positions in the image coordinate system to georeferenced positions.

The builder classes require a matched set of known positions, one from a "source" data set and another from a "target" data set; the builder will then provide a structure which contains a conversion object to transform positions from the "source" coordinate system to the "target" coordinate system. The builders require a list of {@linkplain org.geotools.referencing.operation.builder.MappedPosition MappedPosition} objects which are associations of a {@linkplain org.opengis.referencing.DirectPosition DirectPosition} in the "source" data set with another DirectPosition in the "target" data set. The {@linkplain org.geotools.referencing.operation.builder.MathTransformBuilder#getTransformation() getTransformation() method} in the builder can then be used to provide a {@linkplain org.opengis.referencing.operation.Transformation Transformation} object from which the user can obtain the {@linkplain org.opengis.referencing.operation.MathTransform MathTransform} to use for conversion operations.

Different builders use different mathematical approaches for obtaining the empirical estimate of the conversion parameters. The builders are:

• {@linkplain org.geotools.referencing.operation.builder.ProjectiveTransformBuilder ProjectiveTransformBuilder}
• {@linkplain org.geotools.referencing.operation.builder.AffineTransformBuilder AffineTransformBuilder}
• {@linkplain org.geotools.referencing.operation.builder.SimilarTransformBuilder SimilarTransformBuilder}
• {@linkplain org.geotools.referencing.operation.builder.BursaWolfTransformBuilder BursaWolfTransformBuilder}
• {@linkplain org.geotools.referencing.operation.builder.RubberSheetBuilder RubberSheetBuilder}

Axis units and orientation

Many {@linkplain org.opengis.referencing.crs.GeographicCRS geographic coordinate reference systems} use axis in (latitude,longitude) order, but not all. Axis order, orientation and units are CRS-dependent. For example some CRS use longitude values increasing toward {@linkplain org.opengis.referencing.cs.AxisDirection#EAST East}, while some others use longitude values increasing toward {@linkplain org.opengis.referencing.cs.AxisDirection#WEST West}. The axis order must be specified in all CRS, and any method working with them should take their axis order and units in account.

However, map projections defined in this package are transformation steps, not final CRS. All projections defined in this package must complies with the OGC 01-009 specification. This specification said (quoting section 10.6 at page 34):

Cartographic projection transforms are used by projected coordinate reference systems to map geographic coordinates (e.g. Longitude and Latitude) into (X,Y) coordinates. These (X,Y) coordinates can be imagined to lie on a plane, such as a paper map or a screen. All cartographic projection transforms will have the following properties:

• Converts from (Longitude, Latitude) coordinates to (X,Y).
• All angles are assumed to be decimal degrees, and all distances are assumed to be meters.
• The domain should be a subset of {[-180,180)×(-90,90)}.

Although all cartographic projection transforms must have the properties listed above, many projected coordinate reference systems have different properties. For example, in Europe some projected coordinate reference systems use grads instead of decimal degrees, and often the base geographic coordinate reference system is (Latitude, Longitude) instead of (Longitude, Latitude). This means that the cartographic projected transform is often used as a single step in a series of transforms, where the other steps change units and swap ordinates.

The Geotools implementation extends this rule to axis directions as well, i.e. (X,Y) coordinates must be ({@linkplain org.opengis.referencing.cs.AxisDirection#EAST East}, {@linkplain org.opengis.referencing.cs.AxisDirection#NORTH North}) orientated. This rule implies a non-intuitive behavior for the Transverse Mercator South Orientated projection, which still projects coordinates with Y values increasing toward North. The real axis flip is performed by the rest of the CRS framework upon {@linkplain org.opengis.referencing.cs.CoordinateSystemAxis coordinate system axis} inspection. In order to get a real South orientated projection, the cartographic transform must be concatenated with an affine transform. This is done automatically if the {@linkplain org.opengis.referencing.crs.ProjectedCRS projected CRS} is created with the Geotools's {@link org.geotools.referencing.factory.FactoryGroup#createProjectedCRS createProjectedCRS} convenience method with a South orientated {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate system} in argument.

In order to reduce the risk of confusion, this package never defines south orientated {@link org.geotools.referencing.operation.projection.MapProjection} implementations. The providers always create south-orientated projections as a concatenation of their north-orientated variants with an affine transform. This approach removes all ambiguity when reading a transform in Well Known Text (WKT) format, since only the north-orientated variant is used and the affine transform coefficients tell exactly which axis flips are applied.

For many of us in geotools *this* is the reason we came along for the ride - a pretty picture. The contents of this package are adapted from the OpenGIS® Styled Layer Descriptor specification v1.0.0.

Conformance to SLD 1.0.0

We may experiment with our own (or SLD 1.1) ideas but will mark such experiments for you. This is only an issue of you are considering writing out these objects for interoptability with other systems.

General stratagy for supporting multiple SLD versions (and experiments):

• These interfaces will reflect the current published specification
• Our implementations will be BIGGER and more capabile then any one specification
• We cannot defined explicit interfaces tracking each version until we move to Java 5 (perferably GeoAPI would hold these anyways)
• We can provided javadocs indicating extentions, and isolate these using the normal java convention: TextSymbolizer and TextSymbolizer2 (In short you will have to go out of your way to work with a hack or experiment, you won't depend on one by accident)
• We can use Factories (aka SLD1Factory and SLD1_1Factory and SEFactory) to support the creation of conformant datastructures. Code (such as user interfaces) can be parameratized with these factories when they need to confirm to an exact version supported by an individual service. We hope that specifications are always adative, and will be forced to throw unsupported exceptions when functionality is removed from a specification.

Care and Feeding of Style Objects

SLD is an XML specification, the definition of objects capturing this information, the binding of objects to these XML documents, and the provision of events on object modification all need to be accounted for.

StyleFactory

  StyleFactory factory = StyleFactoryFinder.createStyleFactory();
  StyleLayerDescriptor sld = factory.createStyleLayerDescriptor();
  // an empty sld document
  sld.setTitle("Basic Black");
  sld.setAbstract("Grayscale style suitable for use with photocopiers");
  
  

When creating a complex data structure direct use of a Factory is a pain. Which leads us to the next section.

Notes:

• At this time one implementation of StyleFactory is available, this will not provide true in the future (as SLD experiments, and code generation are brought to bare on future specifications).

StyleBuilder

When constructing a complex data structure, such as an SLD document, the use of a Factory is a bit of a pain. That is where StyleBuilder is brought to bare. A Builder is simply a class that help you construct a complicated data structure, for a make involved/interesting example of a builder have a look at the graph package.

Example

    private Style buildStyle() throws Exception {
        StyleBuilder sb = new StyleBuilder();
        FilterFactory ff = sb.getFilterFactory();
        Style style = sb.createStyle();
        style.setName("MyStyle");

        // "testPoint" feature type style
        Mark testMark = sb.createMark(sb.attributeExpression("name"),
                sb.createFill(Color.RED, 0.5), null);
        Graphic graph = sb.createGraphic(null, new Mark[] { testMark }, null,
                sb.literalExpression(1), sb.attributeExpression("size"),
                sb.attributeExpression("rotation"));
        style.addFeatureTypeStyle(sb.createFeatureTypeStyle("testPoint",
                new Symbolizer[] { sb.createPointSymbolizer(graph) }));

        // "labelPoint" feature type style
        AnchorPoint anchorPoint = sb.createAnchorPoint(sb.attributeExpression("X"),
                sb.attributeExpression("Y"));
        PointPlacement pointPlacement = sb.createPointPlacement(anchorPoint, null,
                sb.literalExpression(0));
        TextSymbolizer textSymbolizer = sb.createTextSymbolizer(sb.createFill(Color.BLACK),
                new Font[] { sb.createFont("Lucida Sans", 10), sb.createFont("Arial", 10) },
                sb.createHalo(), sb.attributeExpression("name"), pointPlacement, null);
        Mark circle = sb.createMark(StyleBuilder.MARK_CIRCLE, Color.RED);
        Graphic graph2 = sb.createGraphic(null, circle, null, 1, 4, 0);
        PointSymbolizer pointSymbolizer = sb.createPointSymbolizer(graph2);
        style.addFeatureTypeStyle(sb.createFeatureTypeStyle("labelPoint",
                new Symbolizer[] { textSymbolizer, pointSymbolizer }));

        return style;
    }

Common Query Language (CQL)

CQL BNF with SQL Extensions

The original BNF was extended thinking in a SQL where expression. The original BNF is reproduced to indicate the extensions highlighted with bold characters.

Extensions in original BNF

    <between predicate> ::= 
    		<attribute name> [ NOT ] BETWEEN <literal> AND < literal > 
	
    <routine invocation> ::= 
             <geoop name><georoutine argument list>
           | <relgeoop name><relgeoop argument list>
           | <routine name><argument list>
           | <BBOX> <bbox argument list>	
           
    <geoop name> ::= 
           EQUAL | DISJOINT | INTERSECT | TOUCH | CROSS | 
           WITHIN | CONTAINS |OVERLAP | RELATE [1]
      
    <bbox argument list>::= 
       "(" <attribute> ","<min X> ","<min Y> ","<max X> ","<max Y>["," <crs>] ")"
    <min X> ::= <signed numerical literal> 
    <min Y> ::= <signed numerical literal> 
    <max X> ::= <signed numerical literal> 
    <max Y> ::= <signed numerical literal>
    <crs> ::= [2]  
      
      
    [1] RELATE is not supported (implementation in GeoTools is required)
    [2] If not supplied, the BoundingBox CRS is EPSG:4326.

    

Implementation Notes

The parser was generated using javacc. In expr.jjt file you can see the input grammar for javacc required to parse CQL with extensions.

This implementation does not check CRS. The problem can be solved adding tokens (standards simbols in grammar) or checking in semantic actions consturction (FilterBuilder). The last solution requires to fix a bug retrieved the correspondent factory for crs (srs).

All GeoTools code should fetch their logger through a call to {@link org.geotools.util.logging.Logging#getLogger(String)}, not {@link java.util.logging.Logger#getLogger(String)}. This is necessary in order to give GeoTools a chance to redirect log events to an other logging framework.

The Validation Process is defined separately from GeoServer so that it may be reused in the future by other applications.

It is currently lurking in the geotools2 folder in the hopes that when it is finished it may be migrated to the Geotools2 library.

This work has been donated by Refractions Research as part of a GeoConnections funded Validating Web Feature Server project.

This package is used to store simple Attribute based Validation implementations. Many of these will be simple FeatureValidation implementations concerned with enforcing constraints on the attributes of a Feture.

At least a couple IntegrityValidation tests will also be implemented here performing such opperations as ensuring that an attribute is unique for an entire FeatureType.

The Validation Processor set up is provided using Data Transfer Objects from this package. Both the initial loading the initial XML configuration files and the dynamic configuraiton systems are handled using these objects.

The use of Data Transfer Objects allows the Validation package to not depend on either the Persistence Method or the Dyanmic Configuration System.

This package is used to store simple Geometry based Validation implementations. Many of these will be simple FeatureValidation implementations concerned with limiting the defaultGeometry of a Feature.

At least a couple IntegrityValidation tests will also be implemented here performing such opperations as ensuring the defaultGeometries do not overlap for an entire FeatureType.

The constraints represented by many of these Validation checks are designed to provide similar coverage to the ArcSDE GeoDatabase appliaction. Where possible we have followed a similar naming convention to the ESRI product.

This package contains the functionality required to read and write XML versions of the org.geotools.validation.dto classes.

These classes have dependencies of SAX and DOM parsers as well as some GeoTools XML io functionality.

Overview

This package provides the necessary tools to parse an XML instance document using the XMLSAXHandler and DocumentFactory. As the document is parsed, and validated, an instance of the ElementHandlerFactory will gather a collection of valid namespaces for the instance document. The ElementHandlerFactory will then use this information to create Complex and Simple Element handlers.

On occation, generic valid data may exist, but that we are unable to fully parse. This content will be ignored using the IgnoreHandler.

The Document Handler is used by the XMLSAXHandler to bootstrap the process of importing schemas and creating handlers.

Overview

This package contains information about xml schemas, and processes to create parse and interpret Schema. One of the more important function is the simplification of a Schema into the interface in the xsi package, as well as compressing some of the heirarchy.

These classes should be used by assessing the SchemaFactory.

Future Work / Caveat

Work can be completed on two fronts, improving the compression algorithms for the Schema compression. The second major work for this schema should be to encode the Schema parsing (this package) as a Schema Object, using the document parser to complete the same task through an xsi extension.

Although it was evident early on that these tasks were similar, the exact nature and method of bootstrapping the process was not evident. Converting these classes to a Schema definition similar to GML would simplify the code, making it easier to maintain.

Schema Interfaces

Overview

This package is intended to provide all the necessary interfaces to semantically represent an XML Schema. Some of the concious shortcomings of this interface set include the in-ability to reproduce exact xml schema documents from a schema represented in memory using just these interfaces (some non-essential constructs have been removed/ignored).

Implementors creating instances of this package should refer to the SchemaFactory (org.geotools.gml) to link your implmentation into the parser.

How to make an extension

This is easy to describe, but hard to implement (or rather to test + debug). Essentially you should create a class that implements Schema, and register it with the SchemaFactory. When creating the appropriate Types as part of the Schema (I assume your Schema will have these) you can link extra parsing into the getValue method (see Type Interface).

Captures initial mapping of XML Simple Types to Java Objects.

Intended Use

Where possible mappings are in agreement with JAXB and will make use of the same utility classes.

Please consider the following reference matterial:

• XML Schema Part 0: Primer Second Edition
• XML Schema Part 1: Structures Second Edition
• XML Schema Part 2: Datatypes Second Edition
• Feature Type Survey
• Web Services Developer Pack (and DataTypeConverter )

The Big Picture

Captures initial mapping of XML Simple Types to Java Objects.

Intended Use

Where possible mappings are in agreement with JAXB and will make use of the same utility classes.

Please consider the following reference matterial:

• XML Schema Part 0: Primer Second Edition
• XML Schema Part 1: Structures Second Edition
• XML Schema Part 2: Datatypes Second Edition
• Feature Type Survey
• Web Services Developer Pack (and DataTypeConverter )

The Big Picture

Captures initial mapping of XML Simple Types to Java Objects.

Intended Use

Where possible mappings are in agreement with JAXB and will make use of the same utility classes.

Please consider the following reference matterial:

• XML Schema Part 0: Primer Second Edition
• XML Schema Part 1: Structures Second Edition
• XML Schema Part 2: Datatypes Second Edition
• Feature Type Survey
• Web Services Developer Pack (and DataTypeConverter )

The Big Picture