<chapter id="chapter-start">
  <title>Quick Start</title>
  
  <!-- Top Level, a description with the chapter TOC -->
  <para>
    This chapter provides a user with a quick introduction to the Geotools 
    library. The introduction includes a brief explanation of how to setup a computer 
    system to use the library, a walk through the demonstration application 
    included with the library, an introduction to two code artifacts which can 
    be used as the basis of of future work, one designed for the creation of an 
    application using Geotools, the other designed for the creation of a new 
    library module, and the chapter concludes by explaining how to configure two 
    popular integrated development environments (IDE) to use the library.
  </para>

  <note>
    <para>
      The chapter assumes that the programmer understands the following:
      <itemizedlist>
        <listitem>
          <para>
          The Java (tm) Programming Language
          </para>
        </listitem>
        <listitem>
          <para>
            The basics of Geographic Information Systems 
          </para>
        </listitem>
      </itemizedlist>
      This chapter tries not to assume any other specialized knowledge; 
      the examples therefore start from the basic desktop of modern GUI 
      operating systems either of the UNIX heritage, namely GNU based or 
      MacOS X, or from the CPM heritage, namely Windows (tm). Since each
      programmer uses her own tools to actually develop her programs, each 
      will have to adapt these examples to fit her own needs.
    </para>
  </note>




<sect1 id="sect-start-setup">
  <title>Setup</title>
  
  <para>
    Users wanting to use the &geot; library, must first obtain and configure 
    a Java Runtime Environment along with two associated core libraries, the 
    Java Advanced Imaging library and the Java Image I/O library. Next, the user 
    must obtain the &geot; library itself. The user can then run the example 
    application which included in the codebase to verify that everything is 
    working correctly. 
  </para>
  
  <para>
    Users can then proceed on their own to develop new applications, new library 
    modules or even to alter the library itself---the free license gives users 
    the freedom to do everything short of taking freedoms away from others.
  </para>
  
  <para>
    However, users may choose to use the ready prepared skeleton application or 
    example module provided by the &geot; project, as explained later in the  
    chapter in <xref linkend="sect-start-firstApp"/> and 
    <xref linkend="sect-start-firstModule"/>.
  </para>



  <sect2 id="sect-start-configJava">
    <title>Configure Java</title>

    <para>
      Geotools requires a Java VM and two imaging libraries, the 
      Java Advanced Imaging library and the Java Image I/O library. These 
      must all be configured correctly for the examples which follow.
    </para>
    
    <note>
      <para>
        The &geot; library and demo application only require a Java Runtime 
        Environment to run. However, since this document aims to show users how 
        to develop new code, this section explains how to install the full 
        development environment which can then be used to create, compile and 
        run new code.
      </para>
    </note> 
    
    <note>
      <para>
        Most developers also use an Integrated Development Environment (IDE) 
        such as Eclipse or NetBeans, applications which greatly facilitate the 
        development of complex programs. Instructions for the use of those two
        popular IDEs are presented in <xref linkend="sect-start-ide"/> 
        below.
      </para>
    </note>
    
    <para>
      Most &geot; developers use the Java Software Developers' Kit (SDK) 
      provided by Sun Microsystems (TM) which is available at no charage from the 
      <ulink url="http://java.sun.com/" type="http">Java webpage</ulink>. The 
      Java SDK can be installed by following the instructions on that web page. 
      The Java SDK provides both the necessary Java Runtime Environment with its
      virtual machine and the tools and libraries necessary to compile a Java 
      application
    </para>

    <para>
      The two imaging libraries must be obtained from Sun Microsystems (TM). 
      They are also available at no charage. The Java Advanced Imaging library 
      can be obtained from the 
      <ulink url="http://java.sun.com/" type="http">JAI webpage</ulink> while 
      the Java Image I/O library can be obtained from the
      <ulink url="http://java.sun.com/" type="http">Java Image I/O webpage</ulink>. 
      Both libraries can be installed by following the instructions on their 
      respective web pages. 
    </para>
    
    <para>
      Once these Java components are installed, a minimal amount of 
      configuration will ensure that the java environment can be found. Two 
      environmental variables generally need to be modified or set: the 
      <code>PATH</code> and <code>JAVA_HOME</code> variables. The 
      <code>PATH</code> envirnomental variable must be modified to include the 
      directory containing the binary applications provided by the SDK, such as 
      the <code>javac</code> compiler, so that shell can find these programs.
      The JAVA_HOME environmental variable must also be set to provide acess to 
      the location of the java installation. 
    </para>
    
    <para>
      For example, on a GNU system using the tcsh, a user could set both 
      variables by typing the following:
<screen>
setenv PATH      /path/to/the/j2sdk/bin:$PATH
setenv JAVA_HOME /path/to/the/j2sdk/
</screen>
      Users on other systems would set these variables in a similar way.
    </para>
    
    <note>
      <para>
        Users who do not understand the concept of environmental variables 
        should turn to the web or to a good reference book on their operating 
        system's <emphasis>shell</emphasis> program. The environment of a 
        program describes the configuration around a program when it runs---it 
        is a critical factor to how a program behaves and must be understood by
        anyone attempting to write modern computer programs.
      </para>
    </note>

  </sect2>



  <sect2 id="sect-start-getGt">
    <title>Install &geot;</title>

    <para>
      &geot; is distributed in three separate pieces: as a binary 
      distribution, as a source distribution, and as a javadoc collection. 
      Each of these can be obtained from the 
      <ulink url="http://www.geotools.org/" type="http">project website</ulink>.
    </para>
    
    <para>
      Most developers get all three components although only the binary 
      distribution is required for this demo. Once the binary distribution is 
      downloaded, it must be unzipped. Presumably most users will expand the zip
      archive somewhere in their home directory. Once expanded the binary 
      distribution contains only a series of JAR files, each representing a 
      different component of the final application.
    </para>

  </sect2>
  
  
  
  <sect2 id="sect-start-test">
    <title>Test the installation</title>

    <para>
      The demonstration application distributed with the Geotools library can 
      serve to test the Java configuration and library installation. The demo 
      itself will be discussed in detail in <xref linkend="sect-start-demo"/> 
      below. 
    </para>
    
    <para>
      The demo can be run by typing:
<screen>
java -jar /path/to/gt2-demo-introduction-VERSION_NUMBER.jar
</screen>
      where "<code>path/to/</code>" is altered to point to the installation 
      directory of the JAR files and "<code>VERSION_NUMBER</code>" is the number 
      of the &geot; release. 
      The command should cause a simple swing application to open with a series 
      of buttons on the left. The functionality of the setup can be tested by 
      clicking sequentially on each button to the left of the application. If 
      everything is setup correctly the application should show some text, draw
      some maps, and then quit all while generating a minimum of text messages.
    </para>
    
  </sect2>



</sect1>




<sect1 id="sect-start-demo">
    <title>Demo</title>

    <para>
      Geotools contains a demonstration application which itself is useless but 
      serves to introduce all of the modules of the Geotools library. When run, 
      the demo provides a minimal description of what it does; the real utility 
      of the demo comes from reading the source code along with the descriptions 
      provided below.
    </para>

  <sect2 id="sect-start-runDemo">
      <title>Run the Demo</title>

      <para>
        Once the Java libraries have been configured and the binary distribution
        of &geot; installed, the demo can be run with the following command:
<screen>
java -jar /path/to/gt2-demo-introduction-VERSION_NUMBER.jar
</screen>
        where "<code>path/to/</code>" is altered to point to the installation 
        directory of the JAR files and "<code>VERSION_NUMBER</code>" is the 
        number of the &geot; release.
      </para>

      <para>
        This command will lead to the following window:
      <!-- SYNC WITH WELCOME -->
      <figure id="fig-geotools-demo-start">
        <title>The Geotools Demo when first opened.</title>
        <screenshot>
          <mediaobject>
          <imageobject>
            <imagedata fileref="figures/geotools-demo-start.png" 
                       format="PNG" 
                       width="600px"
                       scalefit="1"
                       />
          </imageobject>
          <textobject>
            <phrase>
              A screenshot of the user demo as it first appears on screen.
            </phrase>
          </textobject>
  	<caption>
  	  <para>
  	    The &geot; demonstration application uses swing components, such 
        as a label, buttons, and a text area, but also uses the JMapPane
        component to display geospatial data and provide a simple toolbar 
        with tools to manipulate those data.
  	  </para>
  	</caption>
          </mediaobject>
        </screenshot>
      </figure>
        The demo consists of a series of buttons on the left. Each button 
        performs a separate action as summarized below. Each button becomes 
        active when the previous button has been pressed.
      </para>

      <para>
        <itemizedlist>
          <listitem>
            <para>
              Create: Make FeatureSources from scratch, file, or servers.
            </para>
          </listitem>
          <listitem>
            <para>
              Style: Create styles for the features.
            </para>
          </listitem>
          <listitem>
            <para>
              Render: Display a map of styled features.
            </para>
          </listitem>
          <listitem>
            <para>
              Project: Redraw the map using a Mercator projection.
            </para>
          </listitem>
          <listitem>
            <para>
              Filter: Select a set of Features based on criteria.
            </para>
          </listitem>
          <listitem>
            <para>
              Capture: Create an image file copy of the rendered map.
            </para>
          </listitem>
          <listitem>
            <para>
              Save: Save the features in a FeatureSource to a file.
            </para>
          </listitem>
          <listitem>
            <para>
              Commit: Save the features in a FeatureSource to a web server.
            </para>
          </listitem>
          <listitem>
            <para>
              Analyze: An example of an advanced analysis.
            </para>
          </listitem>
        </itemizedlist>
      </para>


  </sect2>


  <sect2 id="sect-start-readDeom">
    <title>Read the Code</title>

    <para>
      The source code for the Demo application provides a quick introduction 
      to each of the major modules of the code library. The source walks 
      through the process of creating Features, both programatically and from 
      various sources such as shapefile and web servers. The source then
      discusses how to create styles and display a map. The source continues 
      by discussing advanced features of the &geot; library.
    </para>

    <para>
      The source is contained in the
        <filename>org.geotools.demo.introduction.DemoApp.java</filename>
        source file within the 
        <filename>gt2-demo-introduction-VERSION.jar</filename>
        JAR file (where VERSION is replaced by the current version number).
    </para>

    <note>
      <title>The code is static and sequential</title>
      <para>
        The code in the &geot; Demo is created for legibility not for elegant 
        design. All methods are static, as are most variables, and the class
        itself is never instantiated. The idea is to have each button linked
        to one or more self-contained methods, each of which is then discussed 
        below.
      </para>
    </note>

    <sect3 id="sect-start-readDemo-create">
      <title>Create FeatureSources</title>

      <para>
      </para>

    </sect3>


    <sect3 id="sect-start-readDemo-style">
      <title>Style the features</title>

      <para>
      </para>

    </sect3>


    <sect3 id="sect-start-readDemo-render">
      <title>Render a map</title>

      <para>
      </para>

    </sect3>


    <sect3 id="sect-start-readDemo-project">
      <title>Project the map</title>

      <para>
      </para>

    </sect3>


    <sect3 id="sect-start-readDemo-filter">
      <title>Filter</title>

      <para>
      </para>

    </sect3>


    <sect3 id="sect-start-readDemo-capture">
      <title>Capture an image</title>

      <para>
      </para>

    </sect3>


    <sect3 id="sect-start-readDemo-save">
      <title>Save to a file</title>

      <para>
      </para>

    </sect3>


    <sect3 id="sect-start-readDemo-commit">
      <title>Commit to a server</title>

      <para>
      </para>

    </sect3>


    <sect3 id="sect-start-readDemo-analyze">
      <title>Advanced Analysis</title>

      <para>
        An example of advanced analysis.
      </para>

    </sect3>
  </sect2>

</sect1>


<sect1 id="sect-start-firstApp">
  <title>First Application</title>
  
  <warning>
    <para>
      This currently does not yet work. The archetype system in Maven 2 is 
      still quite young and the &geot; project doesn't yet fully understand 
      even the parts that work. These notes document how the system is 
      expected to eventually work.
    </para>
  </warning>
    
  <para>
    The user can generate, using the Maven 2 build tool, a skeleton 
    application designed to use the &geot; library and arranged 
    correctly to be built with maven. This system uses the 'archetype' system 
    of the maven tool. A user must first obtain maven, create the archetype, 
    build the archetype, and finally run the archetype. The archetype can then
    be modified to create a new application.
  </para>
  
  <sect2 id="sect-start-archetype-getMvn">
    <title>Get Maven 2</title>
    
    <para>
      The Maven 2 build tool can be obtained from the Apache project. It must
      be downloaded and unbundled, the Java runtime environment must be 
      indicated by the <code>JAVA_HOME</code> environmental variable, and 
      finally the <code>mvn</code> binary can be called, possibly by having 
      its directory placed on the <code>PATH</code>.
    </para>
    
  </sect2>
  
  
  
  <sect2 id="sect-start-archetype-create">
    <title>Create the Archetype</title>
    
    <para>
      The archetype is created by the maven binary tool <code>mvn</code> based 
      on information obtained in a maven plugin bundle. The approach used here
      is to first download an archetype creator plugin, next install that to 
      the local repository (generally .m2/repository/ under a user's home 
      directory), and finally to create the archetype from the plugin.
    </para>
    
    <para>
      While an archetype can be created in any directory. It is presumably a 
      good idea to create a new, separate directory for the files such as 
      creating a temporary directory in a users home directory. The 
      instructions which follow all presume a user is working within that 
      temporary directory.
    </para>
    
    <para>
      First, the user should download the bundle from the web. The bundle is 
      available from the repository at Refractions Research as the 
      <ulink url="http://lists.refractions.net/m2/org/ourgroup/geotools/base/base-1.0-SNAPSHOT.jar"
              type="http">base-1.0-SNAPSHOT.jar</ulink> JAR file. This file can 
      be downloaded through a web browser or using a downloading tool like 
      <code>wget</code>. 
    </para>
    
    <para>
      Second, the file should be installed into the local repository with 
<screen>
mvn install:install-file -DgroupId=org.geotools.maven \ 
                         -DartifactId=archetype \ 
                         -Dversion=2.4-SNAPSHOT \ 
                         -Dpackaging=jar \ 
                         -Dfile=./base-1.0-SNAPSHOT.jar
</screen>
      where the <code>2.4-SNAPSHOT</code> should be replaced by the 
      appropriate version number. This command will involve maven downloading 
      a number of plugins to get all the tools it needs to perform this task.
    </para>
    
    <para>
      Third, the archetype itself can be created with the command:
      <!-- FIXME: no way to get the repository. -->
<screen>
mvn archetype:create -Drepository=lists.refractions.net/m2/ \
                     -DarchetypeGroupId=org.geotools.maven \
                     -DarchetypeArtifactId=archetype \
                     -DarchetypeVersion=2.4-SNAPSHOT \
                     -DgroupId=org.ourgroup.geotools \
                     -DartifactId=base
</screen>
      where, again, the <code>2.4-SNAPSHOT</code> can be replaced by the appropriate 
      version number and where a user can choose appropriate names for the 
      groupId and artifactId. Here again, maven will download a number of 
      plugins to generate the artifact. This will result in the creation of a 
      directory called <code>base/</code> in the local directory. 
    </para>
    
    <para>
      Fourth, the archetype must be built. The user should first change into 
      the <code>base/</code> directory which was created during the last step 
      and then run the command
<screen>
mvn install
</screen>
      which will cause maven to download more artifacts including the entire 
      set of geotools JAR files and then to build the example application.
    </para>
    
    <para>
      Finally, the archetype can be run. 
    </para>
    
  </sect2>
  
</sect1>



<!-- TODO: Create an artifact that does this. -->
<sect1 id="sect-start-firstModule">
    <title>First Module</title>

    <para>
      &geot; does not currently have a Maven2 archetype to create a new 
      directory configured to be useful for module developers. However, in the 
      source distribution of the &geot; library, there is a directory 
<screen>
geotools/modules/unsupported/example/
</screen>
      with which a user can start.
    </para>

</sect1>


<sect1 id="sect-start-ide">
  <title>IDE</title>
  
  <para>
    This section describes the configuration of two popular Integrated 
    Development Environments (IDE), Eclipse and NetBeans, to use Geotools when 
    developing new applications. 
  </para>
  
  <warning>
    <para>
      This section assumes that the user has setup a Java environment according 
      to the instructions provided in <xref linkend="sect-start-configJava"/>. 
    </para>
  </warning>
    
  <para>
    This section describes the configuration of a development environment which
    uses <emphasis>but does not change</emphasis> the &geot; library. The 
    <ulink url="http://docs.codehaus.org/display/GEOT/Home" type="http">&geot; 
    Developer's Guide</ulink> describes how to configure an IDE to work on the 
    library source code itself.
  </para>


  <sect2 id="sect-start-ide-eclipse">
    <title>Eclipse IDE</title>

    <para>
      To be written...
    </para>

  </sect2>



  <sect2 id="sect-start-ide-netbeans">
    <title>Netbeans IDE</title>

    <para>
      To be written...
    </para>

  </sect2>

</sect1>


</chapter>




