:Author: Jody Garnett :Author: Micheal Bedward :Author: Ian Turton :Thanks: geotools-user list :Version: |version| :License: Create Commons with attribution ********************** Eclipse Quickstart ********************** .. sectionauthor:: Jody Garnett Welcome Eclipse Developers ========================== Welcome to Geospatial for Java. This workbook is aimed at Java developers who are new to geospatial and would like to get started. We are going to start out carefully with the steps needed to set up your Eclipse IDE. This workbook is also available for NetBeans or Maven command line use. If you are comfortable with the build tool Maven, it is our preferred option for downloading and managing jars but we will also document how to set up things by hand. These are visual tutorials that allows you to see what you are working with while you learn. These examples make use of Swing; be assured that this is only to make the examples easy and fun to use. These sessions are applicable to both server side and client side development. Java Install ============ We are going to be making use of Java, even if you already have a JDK we would like to ask you to install Java 17 for this tutorial. .. include:: jdk-install.txt Eclipse ======= Eclipse is a popular integrated development environment most often used for all kinds of Java development. For this tutorial we are doing straight up Java programming using the smallest download available - if you already have an Eclipse download please go ahead and use it and switch to the "Java Perspective". 1. Visit the Eclipse download page and download "Eclipse IDE for Java Developers". https://www.eclipse.org/downloads/packages/ 2. Double click on your desktop shortcut to start up eclipse. 3. When you start up eclipse for the first time it will prompt you for a workspace. To keep our java work in one spot you can type in: * ``~/java/eclipse-workspace`` * ``C:\\java\\eclipse-workspace`` Compiling is an intensive activity and local disk should be used (rather than a network share). 4. On the Welcome view press Workbench along the right hand side and we can get started 5. Open up :guilabel:`Preferences` and navigate to :menuselection:`Java --> Installed JREs`. The built-in JRE is selected by default, change to the Java 17 JDK downloaded earlier. Once selected there will be a warning about the compliance level. .. figure:: images/eclipse-installed-jre.png Installed JREs: Java 17 JDK selected 6. Navigate to :menuselection:`Java --> Compiler` and set the compliance level to 17. .. figure:: images/eclipse-compiler.png Java Compiler JDK Compliance 17 7. Press :guilabel:`Apply and Close` to save your changes. .. _eclipse-m2eclipse: M2E Plugin ---------- Maven is a build system for Java which is very good at managing dependencies. The GeoTools library is plugin based and you get to pick and choose what features you need for your application. While this is useful when determining just what is needed for delivery - it can be a pain to manage by hand so we encourage the use of a tool such as maven. The M2E plugin is included by default, this can be confirmed if the :guilabel:`Maven` preference page is listed. .. figure:: images/eclipse-m2.png Eclipse Maven Preference Page Quickstart ========== For this Quickstart we are going to produce a simple maven project, hook it up to GeoTools, and then display a shapefile. This tutorial is really focused on your development environment and making sure you have GeoTools ready to go. We will cover what a shapefile is and how the map is displayed shortly. Creating a Simple Maven project ------------------------------- Maven works by asking you to describe your project, the name, the version number, where the source code is, how you want it packaged, and what libraries it makes use of. Based on the description it can figure out most things: how to compile your code, creating javadocs, or even downloading the library jars for you. To use M2E plugin to create a create a new maven project: #. File > New > Other from the menu bar #. Select the wizard *Maven > Maven Project* and press *Next* to open the *New Maven Project* wizard #. The *New Maven project* page defaults are fine, press *Next* .. image:: images/newmaven.png :scale: 60 #. A large number of sample projects are available, type in ``maven-archetype-quickstart`` to search for the apache one. .. image:: images/archetype.png :scale: 60 #. The archetype acts a template using the parameters we supply to create the project. * Group Id: ``org.geotools`` * Artifact Id: ``tutorial`` * Version: ``0.0.1-SNAPSHOT`` (default) * Package: ``org.geotools.tutorial`` .. image:: images/artifact.png :scale: 60 #. Press *Finish* to create the new project. #. You can see that an application has been created; complete with ``App.java`` and a JUnit test case #. Open up ``src/main/java`` and select ``org.geotools.tutorial.App`` and press the *Run* button in the toolbar:: Hello World! #. You may also open up ``src/main/test`` and run ``org.geotools.tutorial.AppTest`` as a **JUnit Test**. Adding Jars to your Project --------------------------- The ``pom.xml`` file is used to describe the care and feeding of your maven project; we are going to focus on the dependencies needed for your project When downloading jars maven makes use of a "local repository" to store jars. ================== ======================================================== PLATFORM LOCAL REPOSITORY ================== ======================================================== Windows XP: :file:`C:\\Documents and Settings\\You\\.m2\\repository` Windows: :file:`C:\\Users\\You\\.m2\repository` Linux and Mac: :file:`~/.m2/repository` ================== ======================================================== To download jars maven makes use of public maven repositories on the internet where projects such as GeoTools publish their work. 1. Open up :file:`pom.xml` in your new project. You can see some of the information we entered earlier. .. image:: images/pom-overview.png :scale: 60 2. This editor allows you to describe all kinds of things; in the interest of time we are going to skip the long drawn out explanation and ask you to click on the :guilabel:`pom.xml` tab. 3. To make use of GeoTools we are going to add several things to this ``pom.xml`` file. 4. At the top after ``moduleVersion`` add a ``properties`` element defining the version of GeoTools we want to use. This workbook was written for |release| although you may wish to try a different version. .. include:: pom-properties.txt 5. We use the GeoTools Bill of Materials (BOM) to manage dependency versions. This ensures that all GeoTools modules use compatible versions: .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :start-at: :end-at: The BOM (Bill of Materials) pattern centralizes version management. By importing the ``gt-bom``, we don't need to specify version numbers for individual GeoTools modules. 6. We add dependencies to GeoTools modules. Note that we don't specify version numbers since these are managed by the BOM: .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :start-after: :end-at: 7. We need to list the external *repositories* where maven can download GeoTools and other required jars from. .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :start-at: :end-at: .. note:: Note the snapshot repository above is only required if you are using a nightly build (such as |series|-SNAPSHOT) 8. The project was generated with a build **dependencyManagement** section locking down plugin versions to avoid using Maven defaults.0 .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :prepend: :start-at: :end-at: :append: GeoTools now requires Java 17 - add build configuration to ask maven to use Java 17 source level. .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :start-after: :end-at: #. Here is what the completed :file:`pom.xml` looks like: .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :end-before: :append: * Recommend cutting and pasting the above to avoid mistakes when typing * You may also download :download:`pom.xml `, if this opens in your browser use :command:`Save As` to save to disk. The download has an optional quality assurance profile you can safely ignore. Tips: * If maven has trouble downloading any jar; you can try again by selecting :menuselection:`Project --> Update All Maven Dependencies`. * If the dependencies do not update automatically use :menuselection:`Project --> Clean` Quickstart Application ---------------------- Now that your environment is setup we can put together a simple Quickstart. This example will display a shapefile on screen. #. Create the package ``org.geotools.tutorial.quickstart`` using your IDE. #. Create the ``org.geotools.tutorial.quickstart.Quickstart`` class using your IDE. .. image:: images/class.png :scale: 60 #. Fill in the following code :file:`Quickstart.java`: .. literalinclude:: /../../tutorials/quickstart/src/main/java/org/geotools/tutorial/quickstart/Quickstart.java :language: java * You may find cutting and pasting from the documentation to be easier then typing. * You may also download :download:`Quickstart.java ` #. We need to download some sample data to work with. The http://www.naturalearthdata.com/ project is a great project supported by the North American Cartographic Information Society. Head to the link below and download some cultural vectors. You can use the 'Download all 50m cultural themes' at top. * `1:50m Cultural Vectors `_ Please unzip the above data into a location you can find easily such as the desktop. #. Run the application to open a file chooser. Choose a shapefile from the example data set. .. image:: images/QuickstartOpen.png :scale: 60 #. The application will connect to your shapefile, produce a map content, and display the shapefile. .. image:: images/QuickstartMap.png :scale: 60 #. A couple of things to note about the code example: * The shapefile is not loaded into memory - instead it is read from disk each and every time it is needed This approach allows you to work with data sets larger than available memory. * We are using a very basic display style here that just shows feature outlines. In the examples that follow we will see how to specify more sophisticated styles. Things to Try ============= .. include:: try.txt * When cutting and pasting GeoTools code examples use :kbd:`Control-Shift-O` to organise imports (resolving any missing imports). .. The ability to grab figure out what classes to import is a key skill; we are starting off here with a simple example with a single import. * So what jars did maven actually use for the Quickstart application? Open up your :file:`pom.xml` and switch to the :guilabel:`dependency hierarchy` or :guilabel:`dependency graph` tabs to see what is going on. .. image:: images/quickstart-dependency.png :scale: 60 We will be making use of some of the project in greater depth in the remaining tutorials. Alternatives to M2Eclipse ========================= There are two alternatives to the use of the M2Eclipse plugin; you may find these better suit the needs of your organization. * :ref:`eclipse-mvn-start` * :ref:`eclipse-download-start` .. _eclipse-mvn-start: Maven Plugin ------------ The first alternative to using eclipse to setup a maven project ... is using a maven to setup an eclipse project. The maven build tool also works directly on the command line; and includes a plugin for generating eclipse :file:`.project` and :file:`.classpath` files used by :command:`Eclipse`. 1. Download Maven from http://maven.apache.org/download.html The last version we tested with was: Maven 3.3.3 2. Unzip the file ``apache-maven-3.3.3-bin.zip`` to ``C:\java\apache-maven-3.3.3`` 3. You need to have a couple of environmental variables set for maven to work. Use :menuselection:`Control Panel --> System --> Advanced --> Environmental Variables` to set the following System Variables: Add the following system variables: * ``JAVA_HOME = :file:`C:\\Program Files (x86)\\Java\\jdk1.8.0_66``` * ``MAVEN_HOME = :file:`C:\\java\\apache-maven-3.8.6``` And add the following to your ``PATH``: * ``PATH = :file:`%JAVA_HOME%\\bin;%MAVEN_HOME%\\bin``` .. image:: images/env-variables.png :scale: 60 4. Open up a commands prompt :menuselection:`Accessories --> Command Prompt` 5. Type the following command to confirm you are set up correctly:: C:\\java> mvn -version If the `mvn` command is not found check your path using:: C:\\java> echo %PATH% 6. This should produce the following output .. image:: images/maven-version.png :scale: 60 7. We can now generate our project from ``maven-archetype-quickstart`` with:: C:>cd C:\java C:java> mvn archetype:generate -DgroupId=org.geotools -DartifactId=tutorial -Dversion=1.0-SNAPSHOT -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart 8. And ask for our project to be set up for eclipse:: C:java> cd tutorial C:java\tutorial> mvn eclipse:eclipse 9. You can now give Eclipse the background information it needs to talk to your "maven repository" (maven downloaded something like 30 jars for you) 10. Return to Eclipse 11. Use :menuselection:`Windows --> Preferences` to open the Preference Dialog. Using the tree on the left navigate to the Java > Build path > Classpath Variables preference Page. .. image:: images/classpath-variables.png :scale: 60 12. Add an ``M2_REPO`` classpath variable pointing to your "local repository" ================== ======================================================== PLATFORM LOCAL REPOSITORY ================== ======================================================== Windows XP: :file:`C:\\Documents and Settings\\Jody\\.m2\\repository` Windows: :file:`C:\\Users\\Jody\.m2\\repository` Linux and Mac: :file:`~/.m2/repository` ================== ======================================================== 13. We can now import your new project into eclipse using :menuselection:`File --> Import` 14. Choose *Existing Projects into Workspace* from the list, and press :guilabel:`Next` .. image:: images/import-existing.png :scale: 60 15. Select the project you created: :file:`C:\java\tutorial` 16. Press :guilabel:`Finish` to import your project 17. Navigate to the ``pom.xml`` file and double click to open it up. 18. We are going to start by defining the version number of GeoTools we wish to use. This workbook was written for |release| although you may wish to try a newer version, or make use of a nightly build by using something like ``15-SNAPSHOT``. .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :start-after: http://maven.apache.org :end-before: 19. The following dependencies: .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :start-after: :end-before: 20. Setup repositories to download GeoTools from: .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :start-after: :end-before: .. note:: Note the snapshot repository above is only required if you are using a nightly build (such as |series|-SNAPSHOT) 7. GeoTools now requires Java 17 - you need to tell Maven to use the 17 source level. .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml :start-after: :end-before: #. Here is what the completed :file:`pom.xml` looks like: .. literalinclude:: /../../tutorials/quickstart/pom.xml :language: xml * Recommend cutting and pasting the above to avoid mistakes when typing * You may also download :download:`pom.xml `, if this opens in your browser use :command:`Save As` to save to disk. 22. Return to the command line and maven to download the required jars and tell eclipse about it:: C:\java\example> mvn eclipse:eclipse 23. Return to eclipse and select the project folder. Refresh your project using the context menu or by pressing :kbd:`F5`. If you open up referenced libraries you will see the required jars listed. .. image:: images/maven-refresh.png :scale: 60 24. Using this technique of running ``mvn eclipse:eclipse`` and refreshing in eclipse you can proceed through all the tutorial examples. .. _eclipse-download-start: Download GeoTools ----------------- .. sidebar:: Caution This procedure is tricky and can often lead to problems with missing jars or too many jars. GeoTools is really too large and complex to consider building without the use of maven. Please reconsider before proceeding with this process. These are instructions are provided when working in an offline training environment. We can also download the GeoTools project bundle from source forge and set up our project to use them. Please follow these steps carefully as not all the GeoTools jars can be used at the same time. 1. Download the GeoTools binary release from http://sourceforge.net/projects/geotools/files 2. We are now going to make a project for the required jars. By placing the jars into their own project is is easier to upgrade GeoTools. Select File > New > Java Project to open the New Java Project wizard 3. Type in "GeoTools Download" as the name of the project and press Finish. 4. Choose File > Import to open the Import Wizard. 5. Select General > Archive File and press Next 6. Navigate to the ``geotools-bin.zip`` download and import the contents into your project. 9. Next we update our Java build path to include the remaining jars. Choose Project > Properties from the menu bar 10. Select Java Build Path property page; and switch to the library tab. 11. Press ``Add JAR``\ s button and add all the jars in the :file:`lib` folder. 12. Switch to the Order and Export tab and press Select All 13. We can now create a new Example project to get going on our Example. 14. Use Project > Properties on your new Example project to open up the Java Build Path page. 15. Switch to the Projects tab and use the ``Add..`` button to add GeoTools Downloads to the build path. 16. Our example project can now use all the GeoTools jars. 17. Please proceed to the Quickstart, the ``bin`` download already includes :file:`Quickstart.java` for your use.