<chapter id="chapter-design">
  <title>Design</title>

  <!-- This is at the top level to avoid any chapter TOC. -->
  <para>
    This chapter introduces the design of the &geot; library. The &geot; code 
    library is built in modular components assembled into layers with specific 
    functionality. An application using &geot; can assemble only the components 
    it needs. 
  </para>
  
  
  
  
  <sect1 id="sect-design-runtime">
    <title>Runtime</title>
    
    <para>
      Since Geotools is a Java library, applications using the library will run 
      in a well defined environment and have one of several contexts dependent 
      on the purpose of the client application.
    </para>
    
    <sect2 id="sect-design-runtime-environment">
      <title>Environment</title>
      
      <para>
        The &geot; library runs inside a java virtual machine on one of several 
        operating systems. 
      </para>

      <para>
        The environment on which the Geotools library runs is shown in <xref
        linkend="fig-geotools-environment" />.
        <figure id="fig-geotools-environment">
          <title>The Geotools Environment.</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/geotools-environment.png" 
                    format="PNG" />
              </imageobject>
              <textobject>
                <phrase>
                  An image of the components on which the Geotools library runs.
                </phrase>
              </textobject>
        	     <caption>
            	  <para>
            	    &geot; is written in Java and therefore runs inside a Java Virtual 
                  machine (VM). The Java VM generally runs through the POSIX layer 
                  on the hardware. The library requires two of the standard Java 
                  extension libraries, Java Advanced Imaging and Java Image I/O.  
                  &geot; uses the GeoAPI project to define a standard API, the JTS 
                  project for robust geometric convolutions, and the definitions 
                  for scientific units provided by JSR-108 or more recently by the
                  JScience project. There are also several external libraries and 
                  code plugins which can be connected to &geot;.
            	  </para>
            	</caption>
            </mediaobject>
          </screenshot>
        </figure>
      </para>
    
    </sect2>
    
    
    
    <sect2 id="sect-design-archi-userApp">
      <title>Context</title>

      <!--TODO: make the userAppModel figure. -->
      <para>
        Applications built on the &geot; library could use the library to varying 
        degrees. By considering the state during runtime of an application using 
        the library extensively, a user might better understand the essential 
        design of &geot; and therefore better grasp how to start building an 
        application.
      </para>
      
      <para>
        Figure <xref linkend="fig-geotools-userAppModel" /> below shows an 
        overview of the structure of an application during runtime.
        
        <figure id="fig-geotools-userAppModel">
          <title>The structure of an example user application.</title>
          <screenshot>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/ToDo.png" 
                    format="PNG" />
              </imageobject>
              <textobject>
                <phrase>
                  An image of the internal structure of a user application using
                  the &geot; library.
                </phrase>
              </textobject>
            	<caption>
            	  <para>
            	    A user application which uses most of the &geot; library to 
            	    define and render its geospatial data will contain the systems 
            	    shown in the figure.
            	  </para>
            	</caption>
            </mediaobject>
          </screenshot>
        </figure>
      </para>
    
    </sect2>
    
  </sect1>


  
  <sect1 id="sect-design-archi">
    <title>Architecture</title>
    
    <para>
      The &geot; library runs inside a java virtual machine on one of several 
      operating systems. The library necessarily depends on a number of third 
      party libraries and can optionally use other libraries for specific 
      functionality.
    </para>

    <sect2 id="sect-design-archi-subsys">
      <title>Library Subsystems</title>

      <para>
         The Geotools library is split into several, essentially separate components. This component architecture makes it easy to use only part of the library, provides a clean separation to extend Geotools with new functionality, and provides a simple way to replace the default implementation of any particular component with another implementation.
      </para>

      <para>
       The architecture of the Geotools library runs is sketched in <xref
        linkend="fig-geotools-subsystems" /> .
        <figure id="fig-geotools-subsystems">
          <title>The General Geotools Subsystems.</title>
          <screenshot>
            <mediaobject>
            <imageobject>
              <imagedata fileref="figures/geotools-subsystems.png" 
                  format="PNG" />
            </imageobject>
            <textobject>
              <phrase>
                An image of the internal architecture of the Geotools library.
              </phrase>
            </textobject>
    	<caption>
    	  <para>
    	    The &geot; architecture is comprised of several data subsystems and a 
                display subsystem.
    	  </para>
    	</caption>
            </mediaobject>
          </screenshot>
        </figure>
      </para>

      <para>
        &geot; is comprised of several components each with various subsytems. The 
        main library is split between the View component and the Data Model component 
        following the standard model/view/controller computer code pattern.
      </para>
      
      <para>
        The Data Model component consists of the geometric subsystem, the 
        geopositioning 
        subsystem, and the feature subsystem, which jointly provide the core data 
        model for geospatial entities. The positioning subsystem uses one or more 
        authorities, most notably the EPSG database. &geot; also uses a Data access 
        and storage subsystem, with plugins for many common data formats. A Query 
        subsystem provides a rich facility for data selection and manipulation.
      </para>
      
      <para>
        The View component consists of the display substem which provides a way 
        to style and render features selected through a query.
      </para>

    <!-- TODO: add the ext/ and spike/ dirs -->

      <para>
    The Geotools library is split between the Main module and the Plugin modules. The Main module provides the core libraries and the plugins provide specific functionality. There are several plugins that provide access to different format versions of the European Petroleum Survey Group (EPSG) data base of known coordinate geo-referencing systems. Similarly, there are multiple plugins which provide access to common geospatial data formats such as imagery and vector formats either on the local disk, in databases, or on the internet.
      </para>

      <para>
    The Main module itself is split into two components, the data model component and the data view component. These two components are two of the three components in a standard Model-View-Controller split used for most modern GUI application. The Model-View-Controller architecture is a standard architectural design pattern designed to cleanly separate the data model from the logic used to create and modify that model. In general, this architecture does not split the view and controller components in quite as distinctive a manner. However, the Geotools library does not provide any controller logic so the library is cleanly split into a Model-View division.
      </para>


      <sect3 id="sect-conceptual-foundations-archi-subsys-dataComponent">
      <title>The Data Component</title>

      <para>
        The &geot; library follows the standard split between the model, view, 
        and controller components. The data component consists of the entities 
        which describe the real world entities within the computational system.
      </para>

      <sect4 id="sect-conceptual-foundations-archi-subsys-geometry">
        <title>The Geometric Model</title>

        <para>
          This model provides the infrastructure for defining vector based geometric figures. The model is based on the idea of coordinates and of aggregates of these coordinates into points, lines, polygons, multipoints, multilines, or multipolygons. The geometric model also includes operators to perform standard computational geometry operations on the aggregates. In versions up to Geotools 2.2, the Geotools library depends on the Java Topology Suite (JTS) library and is therefore limited to working in two dimensions.
        </para>

      </sect4>

      <sect4 id="sect-conceptual-foundations-archi-subsys-geopositioning">
        <title>The Geopositioning Model</title>

        <para>
          This model provides the infrastructure for geopositioning and for common operations on geo-referenced data such as transformations and re-projections. This model provides ways to define Coordinate Reference Systems (CRS) and the EPSG plugins provide a standard source for the commonly defined geodetic datums and CRS. The model further provide access to fundamental units and parameter structures.
        </para>

      </sect4>

      <sect4 id="sect-conceptual-foundations-archi-subsys-feature">
        <title>The Feature Model</title>

        <para>
          Features are the fundamental unit of geospatial data in the terminology used by Geotools. Features may describe a real world entities or theoretical constructs. Conceptually, Features contain an identifier, a bunch of attributes in a java array, and a schema defining the attributes and the layout of these attributes within the attribute array. The attributes will include the geospatial definition of the feature, any temporal definition of the entity, and any other attributes of the feature. The standard method to obtain feature contents is through the creation of 'queries', combinations of filters and expressions; these are described below.
        </para>

      </sect4>

      <sect4 id="sect-conceptual-foundations-archi-subsys-data">
        <title>The Data Access and Storage Model</title>

        <para>
          This model provides methods for creating, manipulating, and storing data. The model provides an approach to storing data from different sources in a single catalog structure. The model facilitates the interaction with data in vector or raster formats contained on the local file system, in a database or from a network server. The plugin module provides a number of plugins to access common data formats such as GML files, Shapefile format files, GeoTiff images, Geospatial databases, Web Mapping Servers and Web Feature Servers.
        </para>

      </sect4>

      <sect4 id="sect-conceptual-foundations-archi-subsys-query">
        <title>The Query Model</title>

        <para>
          This model provides a standard way to discover and obtain the contents of geospatial data from the data sources and from known features. The query model involves the creation of Filters to sub-select the data contents and expressions to extract only the relevant attributes from the features of interest.
        </para>

      </sect4>

      </sect3>



      <sect3 id="sect-conceptual-foundations-archi-subsys-viewComponent">
        <title>The View Component</title>

        <para>
        </para>


        <sect4 id="sect-conceptual-foundations-archi-subsys-display">
          <title>The Display Model</title>

          <para>
            The display model provides a standard approach to the creation of visuals through which to present the contents of a group of features. This model provides a standard approach to styling feature contents according the complex rules which are necessary to create visually appealing maps. The model also provides a rendering infrastructure for the creation of images.
          </para>

        </sect4>

      </sect3>


      <sect3 id="sect-conceptual-foundations-archi-subsys-controllerComponent">
        <title>No Controller component</title>

        <para>
          There is <emphasis>no</emphasis> controller component in the Geotools
          library; the component is explicitly left to be implemented by 
          library users. 
        </para>

      </sect3>


      <sect3 id="sect-conceptual-foundations-archi-subsys-plugins">
        <title>Plugins</title>

        <para>
          Geotools uses several plugins to provide geopositioning information 
          or to provide access to specific data formats.
        </para>


  <table>
  <title>Plugins</title>
  <tgroup cols="2">
  <thead>
  <row>
    <entry>Name</entry>
    <entry>Description</entry>
  </row>
  </thead>
  <tbody>
  <row>
    <entry>arcgrid</entry>
    <entry>A plugin to support the use of files in the ArcGRID raster format.</entry>
  </row>
  <row>
    <entry>arcsde</entry>
    <entry>A plugin to support access to the ESRI ArcSDE database. This may require a download of a proprietary library through which to access the database. [TODO: Check]</entry>
  </row>
  <row>
    <entry>db2</entry>
    <entry>A plugin to support access to the DB2 database.</entry>
  </row>
  <row>
    <entry>dir_ds</entry>
    <entry>TODO</entry>
  </row>
  <row>
    <entry>epsg-access</entry>
    <entry>A plugin with a version of the EPSG database of coordinate reference systems and datums in the Microsoft Access (tm) database format. This is the only authoritative version.</entry>
  </row>
  <row>
    <entry>epsg-hsql</entry>
    <entry></entry>
  </row>
  <row>
    <entry>epsg-postgresql</entry>
    <entry>A plugin with a version of the EPSG database of coordinate reference systems and datums in the in-memory HSQL database format. This is an alternative, non-authoritative version.</entry>
  </row>
  <row>
    <entry>epsg-wkt</entry>
    <entry>A plugin with a version of the EPSG database of coordinate reference systems and datums in a set of Well-Known Text (WKT) file format. This version is almost always functional, but its content is significantly different from the content of the Access database. This is an alternative, non-authoritative version.</entry>
  </row>
  <row>
    <entry>geomedia</entry>
    <entry>TODO</entry>
  </row>
  <row>
    <entry>geotiff</entry>
    <entry>A plugin which supports access to files in the GeoTIFF image format.</entry>
  </row>
  <row>
    <entry>gml</entry>
    <entry>A plugin to enable the reading and writing of files in the Geographic Markup Language (GML) extension to the eXtensible Markup Language (XML) format.</entry>
  </row>
  <row>
    <entry>image</entry>
    <entry>TODO</entry>
  </row>
  <row>
    <entry>mif</entry>
    <entry>A plugin to enable access to the MIF file format.</entry>
  </row>
  <row>
    <entry>mysql</entry>
    <entry>A plugin to enable access to the MYSQL database.</entry>
  </row>
  <row>
    <entry>oracle-spatial</entry>
    <entry>A plugin to enable access to the MYSQL database.This may require a download of a proprietary library through which to access the database. [TODO: Check]</entry>
  </row>
  <row>
    <entry>postgis</entry>
    <entry>A plugin to enable access to a PostGIS database, a spatial extension to the PosgreSQL database.</entry>
  </row>
  <row>
    <entry>shapefile</entry>
    <entry>A plugin to enable the use of files in the Shapefile format.</entry>
  </row>
  <row>
    <entry>tiger</entry>
    <entry>A plugin to enable the use of files in the TIGER format used by the Census Bureau of the United States Government.</entry>
  </row>
  <row>
    <entry>vpf</entry>
    <entry>A plugin to enable the use of files in the Vector Product Format (VPF) which has become the standard format for the distribution of geo-spatial data by the United States Geological Survey (USGS).</entry>
  </row>
  <row>
    <entry>wfs</entry>
    <entry>A plugin to support the use, over a network, of a Web Feature Server (WFS) host.</entry>
  </row>
  <row>
    <entry>wms</entry>
    <entry>A plugin to support obtaining raster images, over a network, from a Web Mapping Server (WMS).</entry>
  </row>
  </tbody>
  </tgroup>
  </table>

      </sect3>

    </sect2>
    

    
  </sect1>

  
  
  
  <sect1 id="sect-design-api">
    <title>Interfaces</title>

    <para>
      The Application Programming Interface (API) to the &geot; library 
      consists of four seperate layers divided according to the maturity, 
      standards conformance, testing, and expected stability of the interface.
    </para>
     
    <para> 
      The most stable interfaces are those defined in the 
      <ulink url="http://www.geoapi.org/" type="http">GeoAPI project</ulink> 
      which aims to implement the standard java language interfaces to the 
      major ISO and OGC geospatial standards. 
    </para>
     
    <para> 
      The &geot; library itself defines a set of stable interfaces in the separate
      <code>geotools/modules/library/api</code> module; these are interfaces 
      which have matured sufficiently to be considered stable from the 
      perspective of the library although the interfaces either have not yet 
      been incorporated into GeoAPI or are not implementations of any accepted 
      standard and therefore do not belong in the GeoAPI interfaces. 
    </para>
     
    <para> 
      The third level of interfaces are those simply defined in the packages 
      themselves. These interfaces are much less stable and are expected to 
      change between releases although all interface changes follow the rule  
      that an interface will be deprecated first for one whole release cycle 
      prior to removal during the subsequent release cycle.
    </para>
     
    <para> 
      The fourth level of interfaces are the access methods provided by the 
      libraries on which &geot; depends. The JTS library, for example, provides 
      a number of classes and methods which are used throughout the &geot; code 
      base. While not technically part of the &geot; library, these interfaces 
      are, for practical purposes, part of the API any user program will need to 
      use.
    </para>

    <para>
      Developers can use several programming interfaces through which to access 
      the functionality of &geot;. Obviously, since the code is openly distributed   
      and freely accessible, users can develop their applications in any way they 
      choose. However, there are several defined series of interfaces which have
      been created to allow users to develop applications which use standard 
      intefaces and theefore can be updated relatively easily as newer versions of 
      &geot; are released in the future.
    </para>

    <para>
      While the developers using the &geot; library have the freedom to use this 
      code in any way they please, best practice dictates using the most stable 
      interfaces possible to achieve any particular goal. This best practice 
      involves using the GeoAPI interfaces as extensively as possible, using the 
      stable &geot; interfaces where avaiable and then, only if none of these 
      provide the needed functionality, using the interfaces defined in each 
      &geot; package directly or the interfaces provided by third party 
      libraries. Following such a practice will lead to code which can be 
      upgraded to newer versions of the &geot; library with the least significant 
      changes. 
    </para>
    
    <warning>
      <para>
        Users of &geot; should be ready to stray far from best practices. The 
        library is not yet mature enough to guarantee that even a subset of 
        opertions can be done using only stable interfaces. During the creation 
        of the library there have even been periods where it was impossible to 
        use the library without using deprecated classes. 
      </para>
    </warning>

<!--
    <sect2 id="sect-design-api-geoAPI">
      <title>GeoAPI</title>

      <para>
        The GeoAPI project aims to define a set of interfaces for the 
        fundamental geospatial standards defined by the ISO and the OGC which 
        would allow users and implementers of the standard to code against a 
        stable contract. Applications coded against this interface would be 
        completely portable between independent implementations of the standards, 
        while implementations could seek different approaches without harming 
        the stability of their clients. 
      </para>
      
      <para>
        Unfortunately, GeoAPI is a young project, the specifications themselves 
        are untested, and no one is sure how the interfaces will need to change 
        as the projects seek to implement more complex semantics. While it will
        hopefully eventually be possible to use &geot; by obtaining a single 
        reference to one &geot; object and developing all the remaing code 
        against the GeoAPI interfaces, that situtation will not arise in the 
        near futre.
      </para>
    
      <para>
        GeoAPI is designed ... (TODO)
      </para>

    </sect2>



    <sect2 id="sect-design-api-gtAPI">
      <title>&geot; stable API</title>

      <para>
        The 'api' module (modules/library/api) of &geot; defines a set of 
        generally stable interfaces. 
      </para>

    </sect2>



    <sect2 id="sect-design-api-moduleAPI">
      <title>&geot; module API</title>

      <para>
        Sometimes users must access needed functionality by directly accessing 
        classes in the &geot; library. 
      </para>

    </sect2>



    <sect2 id="sect-design-api-dependAPI">
      <title>Dependency Interfaces</title>

      <para>
        
      </para>

    </sect2>
    
-->

  </sect1>
  
  
  <sect1 id="sect-design-dataModel">
    <title>Data Model</title>
    
    <para>
      Since Geotools implements the ISO/OGC geospatial standards, applications 
      using the library are forced to use a similar semantic model for their 
      data. This section presents the data model of a client desktop 
      application which uses Geotools.
    </para>
    
  </sect1>
  
  
  
  
  
  <sect1 id="sect-design-practical">
    <title>Practical Info</title>
    
    <para>
      
    </para>
    
    
    
    <sect2 id="sect-design-practical-layout">
      <title>Code Layout</title>
      
      <para>
        
      </para>
      
    </sect2>
    
    
    
    <sect2 id="sect-design-practical-factory">
      <title>Factory Systems</title>
      
      <para>
        
      </para>
      
    </sect2>
    
    
    
    <sect2 id="sect-design-practical-logging">
      <title>Logging</title>
      
      <para>
        
      </para>
      
    </sect2>
    
  </sect1>
  
</chapter>





