Using the GeoExplorer and the GeoViewer

Latest update: January 10, 2010 for forceTen v0.5.6.

In this tutorial we are going to demonstrate how to use and customize the two basic components of forceTen, the GeoExplorerPresentation and the GeoViewerPresentation, in your NetBeans Platform application using Maven.

For this tutorial you need Java 6 and NetBeans 6.8 or later (but it could work with 6.7.1 too). This tutorial is also available as a screencast and a similar source is available in the “Example1” module in forceTen sources.

 

Creating a skeleton platform project

  1. Select the menu “File / New Project”.
  2. Select the “Maven” category and “Maven Project” under Projects. Press “Next”.
  3. Select the “Maven NetBeans Platform Application Archetype” and press “Next”.

If it's the first time you're using Maven, some steps might require a while as Maven download the required artifacts from the network (downloading the NetBeans Platform artifacts can be very long, but you need to do that only once).

Now, you should be in the “Name and Location” window; fill in as indicated:

  1. Project name: example1
  2. Project location: your favourite path
  3. Group Id: it.tidalwave.geo.examples
  4. Version: 1.0-SNAPSHOT
  5. Package: it.tidalwave.geo.examples.example1

Now press the “Finish” button. After the operation completes, you'll find four projects in the “Projects” tab. They are a master project and three modules:

  1. “example1 - NetBeans Platform Application”: the module with the master pom
  2. “example1 - NetBeans Platform based application”: a module which builds the application
  3. “example1 - Platform application branding resources”: a module with branding settings
  4. “example1 - sample NetBeans Module”: a module with a sample Platform Module

Make sure that the “master pom” project is the main project (eventually click on it and select the menu “Set as Main Project”). Execute the “Clean and Build” operation to compile your project (again, the first time this might take a while as artifacts are downloaded from the network).

Now select the “nbm-application” module and execute the “Run” action. You should see the skeleton application running - basically and empty windows with some default menus and buttons in the toolbar.

 

Adding the repositories and configuring the compiler

Open the pom.xml file of the “master pom” project, locate the repositories section and add the following part:

<repositories>
    <repository>
        <id>netbeans</id>
        <name>NetBeans Platform Maven Repository</name>
        <url>http://bits.netbeans.org/maven2/</url>
    </repository>
    <repository>
        <id>maven2-release-repository.nbpwr.kenai.com</id>
        <name>NBPWR Maven Release Repository</name>
        <url>https://kenai.com/website/nbpwr/maven-repository/releases</url>
    </repository>
    <repository>
        <id>maven2-release-repository.openbluesky.kenai.com</id>
        <name>OpenBlueSky Maven Release Repository</name>
        <url>https://kenai.com/website/openbluesky/maven-repository/releases</url>
    </repository>
    <repository>
        <id>maven2-release-repository.forceten.kenai.com</id>
        <name>forceTen Maven Release Repository</name>
        <url>https://kenai.com/website/forceten/maven-repository/releases</url>
    </repository>
</repositories>

We have added a few repository to retrieve libraries from, most notably the forceTen repository, the OpenBlueSky repository (a set of components used by forceTen) and the NBPWR repository (a set of common open source libraries prepared for the NetBeans Platform).

Then locate the pluginManagement section and make sure you're compiling with Java 6, configuring the compiler plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>2.0.2</version>
    <configuration>
        <source>1.6</source>
        <target>1.6</target>
    </configuration>
</plugin>

Adding the GeoExplorerPresentation

This component allows navigating in a geographic hierarchy so you can choose a certain location (a country, a region, a province or a town). With NetBeans, artifacts can be added as libraries by selecting the “Libraries” icon of the “NetBeans Platform Application (pom)” module and click Add Dependency. At that point, it is possible to enter the coordinates or even search for the artifact by using part of the name. In this tutorial, all artifacts will be described by listing the fragment that needs to be pasted into the POM; you can add the dependency in the way that you like more.

To add the “GeoExplorerPresentation” component, enter these coordinates (they must be pasted in the <dependencies> section):

<dependency>
    <groupId>it.tidalwave.geo</groupId>
    <artifactId>it-tidalwave-geo-explorer</artifactId>
    <version>1.1.40</version>
</dependency>

NetBeans will take a while to download the artifact; if you look at the Libraries icon again you can see that many more modules have been added - Maven has automatically resolved the dependencies of the GeoExplorerPresentation artifact. As part of the downloaded artifacts, Maven has also retrieved the sources and the javadocs of the code, that will be helpful later when we will write some code using the forceTen APIs.

Recompile and run the application. When you see the application window, select the menu “Window / Geo Explorer”. The component should appear at the left side of the window, and be empty: there are no data, since we didn't define any data provider.

 

Adding a GeoCoding provider

Repeat the procedure to add an artifact with the following coordinates:

<dependency>
    <groupId>it.tidalwave.geo</groupId>
    <artifactId>it-tidalwave-geo-geocoding-geonamesprovider</artifactId>
    <version>1.0.43</version>
</dependency>

Recompile and run the application, then show the GeoExplorerPresentation. This time it should get populated with a hierarchical view of geographic locations.

As you can see, all the nodes are rendered with a single default icon. One might desire to customize them, for instance using a small reproduction of the flag of each country. This need allows us to shortly introduce the way in which forceTen components can be customized (but remember that this topic will be dealt in detail in next tutorials). First, add this artifact to the POM:

<dependency>
    <groupId>it.tidalwave.geo</groupId>
    <artifactId>it-tidalwave-geo-node-flagsoftheworld</artifactId>
    <version>1.0.3</version>
</dependency>

It's a special decorator for the nodes that attaches the country flags. Now, open the project “example1 - sample NetBeans module”, click on the “Important files” icon and locate the “XML Layer”; click on it so an editor is opened. The XML Layer is one of the more convenient ways to configure components in the NetBeans Platform. Paste the following frament into it.

<folder name="Roles">
    <folder name="it.tidalwave.geo.explorer.GeoExplorerPresentation">
        <file name="FlagsOfTheWorldDecorator.instance">
            <attr name="instanceClass"
                  stringvalue="it.tidalwave.geo.node.flagsoftheworld.GeoNodeFlagsOfTheWorldDecorator"/>
        </file>
    </folder>
</folder>

Now, the node decorator has been injected in the GeoExplorerPresentation. Recompile and rerun the application and check that flags have appeared.

Before going on, return to the XML Layer and paste this further fragment:

<folder name="Toolbars">
    <folder name="Viewer">
        <file name="it-tidalwave-geo-viewer-GeoExplorerAction.shadow">
            <attr name="originalFile"
                  stringvalue="Actions/it.tidalwave.geo.explorer.GeoExplorerPresentation/ToggleGeoExplorerAction.instance"/>
        </file>
    </folder>
</folder>

This will show an icon in the toolbar that makes it easier to show and hide the GeoExplorerPresentation.

 

Add the GeoViewer

Now we add the GeoViewer, a component capable to render maps. Add this artifact to the main POM:

<dependency>
    <groupId>it.tidalwave.geo</groupId>
    <artifactId>it-tidalwave-geo-viewer</artifactId>
    <version>2.3.43</version>
</dependency>

Rebuild and run the application. Select the menu “Window / Geo Viewer”: this time, a large panel should fill the central part of the window, and look empty. The reason is that the component is just a generic container service that depends on the installation of further modules which render different geographical views.

Let's install the provider for OpenStreetMap, a popular free and open map provider, and Microsoft Virtual Earth. Add these artifacts to the master POM:

<dependency>
    <groupId>it.tidalwave.geo</groupId>
    <artifactId>it-tidalwave-geo-viewer-spi-openstreetmap</artifactId>
    <version>1.0.41</version>
</dependency>
<dependency>
    <groupId>it.tidalwave.geo</groupId>
    <artifactId>it-tidalwave-geo-viewer-spi-microsoftvirtualearth</artifactId>
    <version>1.0.38</version>
</dependency>

Rebuild and run the application. Now, if you go to the Geo Viewer, you should see our first map. By default, the viewer centers on the coordinate (0;0), so you should see the Atlantic Ocean off the Africa coast. You can drag the map and change the zoom at your will and select the map provider; Microsoft Virtual Earth provides three different renderings (map, satellite and satellite + map) and you can select them from the controls at the bottom of the window.

If you select a node in the Geo Explorer you'll see that the map recenters to show it. The two components, indeed, don't know each other, but cooperate by a facility named the “EventBus”. We will cover this facility in a different tutorial, also explaining how to customize it eventually replace it with a different way in which the two components can cooperate.

Now, let's add another provider, by adding this in the POM:

<dependency>
    <groupId>it.tidalwave.geo</groupId>
    <artifactId>it-tidalwave-geo-viewer-spi-worldwindprovider</artifactId>
    <version>1.1.40</version>
</dependency>

Rebuild and run the application. Now a 3D renderer is available from the provider selection. 

As the final step for this tutorial, re-open the XML layer in the “example1 - sample NetBeans Module” and copy this fragment in the “Toolbars” folder:


<file name="it-tidalwave-geo-viewer-GeoViewerAction.shadow">
    <attr name="originalFile" 
          stringvalue="Actions/it.tidalwave.geo.viewer.GeoViewerPresentation/ToggleGeoViewerAction.instance"/>
</file>

So we have another icon in the toolbar for the GeoViewer as we earlier introduced one for the GeoExplorer.

So far you've had a pretty good demonstration of how it's possible to use the NetBeans Platform to create a really modular application. forceTen provides a few more geographical providers and of course defines a SPI (Service Provider Interface) that can be used to write even more.

Do you think this is cool? Yes, it is. But it's only part of the reuse problem, as it's unlikely that you need to use those components exactly in the way I've designed them. You might want to change the way selections are performed, navigate through a subset of the data, design your own user interface. The components in forceTen have been implemented in a way so it's possible to change and enhance their behaviours by changing a configuration file and eventually adding small portions of code. This topic will be covered by the next tutorial.