Introduction

Attention!

This document is designed to work with version 2.0.0 of gvsIG. If you're developing on another version of gvSIG please check if there is documentation specific to that version.

data/developers_quick_start.png

This document is intended as an introduction to developing with gvSIG 2.0. It does not delve into the intricacies of gvSIG but rather provides an overview of the major components and how they can be used to build your first gvSIG development.

Java is used as the development language for gvSIG and it is recommended that you familiarise yourself with Java if not already so. Eclipse is used as the project's integrated development environment, so you should be familiar with it too. Tools like Maven or Ant are also used, and familiarity with them is recommended, although not essential, for a first attempt at development with gvSIG.

In addition to these skills, it is highly recommended that the developer be familiar with the application from the user's point of view. You can find user documentation on the gvsig.org web site, which, while not corresponding exactly with the version of gvSIG you will be working with, will nevertheless provide a better understanding of the different pieces of code.

In short, before continuing you should know:

Java:necessary
Eclipse:necessary
Ant:recommended
Maven:recommended
gvSIG application:
 recommended

In addition to this, you should have:

Tip

You can find information on the development list and an overview of all the project lists in the Project Mailing Lists document.

If you have trouble following this document please feel free to ask questions on the project development list. They will help answer any questions that may arise.

Changes to using gvSIG

Prior to gvSIG version 2, the main way of developing with gvSIG was to create a workspace with the official distribution's source, so that making a plugin required all the information necessary to compile the full gvSIG distribution. Although some efforts were made to build plugins without the need for a full gvSIG workspace, it was not up until version 2 that this mechanism functioned properly. The recommendation now is not to insert plugins into a workspace with gvSIG sources.

In version 2, the correct way of developing a new plugin is with a binary installation of gvSIG by creating a workspace containing only our projects, and then deploying our binaries with that installation.

In addition to this, considerable effort has been made in version 2 to make the libraries that use the gvSIG plugin mechanism independent. This allows us to perform much of the development without having to bind to gvSIG, or to compile to test it. We can create small applications that use the libraries of gvSIG and can be run independently.

Complementing this, ??the necessary changes have been made so you do not have modify the code for common operations you might need during development.

If you have already developed for gvSIG 1 you should bear in mind this change in the way of working. Do not create a workspace with the gvSIG sources and compile them if it is not necessary. This only needs to be done if you need to make changes to the sources.

Usually the gvSIG source code does not need to be modified as you can develop your own plugin functionality rather than modifying the gvSIG code. If you need to do this, and these modifications might be useful for other users, then you can submit them as patches for inclusion in future versions of gvSIG.

Basic architecture of gvSIG

org.gvsig.tools

The Tools library is an important part of gvSIG. It provides a number of utilities and services which support the other modules in gvSIG. The main functionality provided by this library relates to:

Although these are the most important services the library provides, it also provides other tools that can be considered structural to the application. These include:

Tip

You can find more detailed information on how the library mechanism works in gvSIG at org.gvsig.tools.library, on the use of locators you can consult org.gvsig.tools.locator, and for managers you can find documentation at org.gvsig.tools.service.

We will focus now on three basic concepts that are repeated throughout the code that we see, and that are linked to utilities that enable a strict separation of the API from the implementation:

These three components play a major role whenever we want to use or create new components, as they are the devices that allow us to access different parts of gvSIG

Andami Plugins Framework

The Andami framework is used to compose the gvSIG application. It provides mainly two types of services, the management and loading of plugins, and the management of windows that make up the user interface.

At this point we will focus briefly on the management of plugins. Andami provides a launcher for the application that initializes the plugins system, and is responsible for loading the plugins that are installed in the application. A plugin is a functional unit that can provide:

Normally in a gvSIG installation you will find a folder gvSIG/extensions. This folder contains the different plugins installed in the application. Each plugin is contained in a folder, which always contains the files:

There is also a theme folder, which contains the configuration of the application's splash, window icons and background colors.

Although the mechanism for adding new functionality to gvSIG is also adding new plugins, these in turn contain one or more extensions that provide the functionality being added. So we will have a plugin containing extensions.

With respect to the management of plugins, the main components are:

We will examine the IExtension interface in more detail. This is the interface that we implement in order to add a new button or menu option. In this interface we find the methods:

Windows

Tip

Although there is currently no documentation related to this for version 2 of gvSIG, in general, existing documentation for gvSIG 1 should be valid. It can be found at Andami windows

Andami, in addition to providing a mechanism for loading and managing plugins, also provides an API for the management of the application's windows. Currently the MDI paradigm is used to manage windows. However, gvSIG's window manager itself can be replaced to provide other forms of display (SDI, tabs,...).

The main entities found in Andami related to windows management are:

In general if we do not need fine control over our windows we can use the ShowWindow method from MDIManager to display a window from a standard JPanel swing.

Some gvSIG plugins

In gvSIG there are a number of plugins that provide the application's base functionality that have some relevance to the other plugins. These are:

These are some of the most important plugins in gvSIG in the sense that they provide important basic functionality necessary for other plugins to function.

Besides these plugins there are many more plugins in the gvSIG distribution that may or may not be necessary depending on what we're going to do with gvSIG.

Some relevant Libraries

When developing with gvSIG it is useful to know the existing plugins, especially the functionality provided by the ApplicationManager. But the important thing is to control which of the libraries we will require in order to implement the functionality we need.

In version 2.0.0 of gvSIG major changes have been introduced, both in how to build gvSIG as well as in the nomenclature used to identify the projects and libraries that are generated. However, this is not a process that has taken place suddenly, it has been happening over a number of years. This has now resulted in a lack of uniformity in the nomenclature of existing components. When it comes to referring to a library we can use the Eclipse project name, the name of the generated jar, or the Maven artifact name. In projects generated recently the chosen rule is that these three names must match, with the name of the Maven artifact being used for all three. Prior to this decision projects had different names for each of these components. For a developer who intends using gvSIG, the important thing is to know the names of the Maven artifact, since they usually need to know for which artifacts dependencies should be set, with the eclipse project name associated with that artifact being less relevant.

The libraries that most meet our needs in gvSIG are:

Construction tools

All construction of gvSIG build in version 2.0 has been performed with Maven. This tool has been adopted as a tool for building the project.

Tip

It would be advisable to read the documentation on Maven that exists in the gvSIG 2.0 development guide, in the "Maven" section where you will find a brief description as well as links to useful resources related to Maven.

This tool was adopted largely because of the management of dependencies that it is capable of performing, one benefit from a number of good practices that Maven gives us.

You can compile and deploy developments from the command line without being tied to a particular integrated development environment (IDE).

It is therefore important, at the very least, that you know the functioning of Maven if you intend carrying out developments on gvSIG.

In addition to Maven, ant scripts are still used for various maintenance or construction tasks as these are two complementary tools.

The project still uses and recommends Eclipse as an IDE. Several specific configuration files have been prepared to facilitate development on it, and its integration with the compilation system of gvSIG using Maven.

Building our first plugin

Approach

At this point we will generate a project that will allow us to see a number of gvSIG's basic features. To do this we will create a small map viewer. The requirements might be:

To start making our project we will use the wizard to generate projects that are included in the gvSIG distribution.

The project creation wizard

The gvSIG distribution includes a plugin that displays an assistant for creating development projects on gvSIG. The extension providing this wizard is disabled by default so the first thing we must do is to activate it.

Tip

To assist you in the creation of development projects you can find documentation in the Creating our project section of gvSIG's Guide for developers.

To do this, go to the gvSIG preferences panel, and in General, Extensions look for "org.gvsig.mkmvnproject.MakeMavenProjectExtension", and activate the extension. You will need to restart gvSIG to effect the change.

After restarting gvSIG you will notice that the "Tools" menu now has a "Development" sub-menu, which contains a Create new plugin option.

It is important that we supply the following information properly:

Having entered this data, select the Basic plugin with spatial support option.

Click Next to run the script and wait for it to finish generating the project. This can take several minutes depending on your Internet connection and your computer.

During the process of building the project you will be asked:

The script for creating our project, in addition to generating the source code and configuring Maven for use, compiles and displays the first version of the project in the Maven local repository, and also generates the corresponding Eclipse projects so that they can be imported into our workspace.

Project structure

Direct translation from Google translator

Once the wizard has generated our project we can get started by opening Eclipse and selecting as our workspace the folder that was indicated in the wizard. This opens an instance of Eclipse with an empty workspace. The first thing to do is to import the two projects that have been created. For this we will not use the import option.

From the File menu select New->Project... (not java project) and in the dialogue that appears select the General->Project option and click Next. Use "org.gvsig.viewer" as the project name to complete the process. Do the same for the "org.gvsig.viewer.app" project.

Tip

You may find it useful to consult information relating to this in the Developer Guide in the gvSIG project structure section and also in Things to consider before developing a plugin.

Let's take a look at the generated code. The projects that have been created are:

We could work with this but since Eclipse is not able to recognise the structure of Maven subprojects it will be much easier to import the child projects as Eclipse projects.

Select the File->import menu option and in the import dialog and select General->Existing Projects Into Workspace and click next. Click "Select root directory" and select the folder "/home/gvsig/workspce/viewer/org.gvsig.viewer/org.gvsig.viewer.lib". In doing this we suggest adding these projects:

These will be selected so just press the button end.

Now repeat the process indicating as "root directory" the following folders:

We have now imported all the projects related to our development into our workspace.

Dependencies between projects

First, let's see what dependencies the assistant has left us with in the org.gvsig.viewer project. Notice the following entry in the dependencyManagement section in the project's pom.xml file:

<dependencies>
  <dependency>
    <groupId>org.gvsig</groupId>
    <artifactId>org.gvsig.core.maven.dependencies</artifactId>
    <version>2.0.1-SNAPSHOT</version>
    <type>pom</type>
    <scope>import</scope>
  </dependency>
</dependencies>

This imports the dependencies of the various gvSIG libraries so that we don't have to worry about the versions of any of the gvSIG base libraries. As this importing is done in the dependencyManagement section, it is for information purposes only, ie a dependency on these libraries is not set.

If we now look at the dependencies section, we find the entry:

<dependency>
  <groupId>org.gvsig</groupId>
  <artifactId>org.gvsig.core.maven.dependencies</artifactId>
  <version>2.0.1-SNAPSHOT</version>
  <type>pom</type>
  <scope>test</scope>
</dependency>

This sets the implementation and test dependencies for all the core libraries of gvSIG so that we won't have to worry about whether all the implementations of the gvSIG APIs are loaded when testing our projects.

In addition we see:

<dependency>
  <groupId>org.gvsig</groupId>
  <artifactId>org.gvsig.tools.lib</artifactId>
  <type>jar</type>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>org.gvsig</groupId>
  <artifactId>org.gvsig.tools.lib</artifactId>
  <type>test-jar</type>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.gvsig</groupId>
  <artifactId>org.gvsig.fmap.geometry</artifactId>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>org.gvsig</groupId>
  <artifactId>org.gvsig.fmap.dal</artifactId>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>org.gvsig</groupId>
  <artifactId>org.gvsig.metadata.lib.basic.api</artifactId>
  <scope>compile</scope>
</dependency>

These are fixed build dependencies with the main gvSIG libraries, and are usually required in almost any project that we make with gvSIG.

This configuration of dependencies is found in the main project. Let's now see what dependencies are required for the subprojects.

The Logic Library

The logic part of our development is divided into two projects:

In the API project we find mostly interfaces. These interfaces make up the API of the logic components to be developed. The class model of the example is shown in the following diagram:

../data/org.gvsig.visor.api.png

Model if the API classes

We have the following entities:

Let's see what we are in the implementation part. Observe that while in the normal API interfaces has been found in the implementation we find classes. Classes that implement the various interfaces that defined in the API. By convention, the implementation of the various interfaces that appear in the API will call the API like prepending the prefix Default.

The class model of implementation for our example is:

../data/org.gvsig.visor.impl.png

Model implementation classes

Let us see the most relevant parts of the implementation.

Presentation libray

Direct translation with Google Translator

As happened with the logic, the presentation also will be divided into two projects, on the one hand and on the other API implementation.

Similar to as with the logic in the presentation, in the draft We only have the API interfaces and abstract classes that define our API. the API of the presenting part is formed by the interface along with manager a set of abstract classes that define the public API of our components, components usually extend to swing JPanel component. These classes are interfaces and abstract because no swing model interfaces for its components. In our example, the only component that is we visual component associated with an apple, the JVisorBlockPanel, which extends from JPanel API level by adding a single method that allows us to obtain the VisorBlock logical component that is associated at any given time.

In the implementation we will find the class DefaultJVisorBlockPanel it receives in its constructor the instance of the VisorBlock to be submitted their data. In general the presentation is not a complication beyond of persons as may be handling swing. The only thing to note is that the presentation should not use anything that is not exposed in the API from our library of logic.

A test application

Direct translation fron google translator

So far we've seen pieces that made up the various loose components that we needed to do our small viewfinder. We will see Now how can we join all those pieces and some more to create a simple viewer let us try everything without having to boot all gvSIG.

To do this, we focus on the org.gvsig.visor.main project. It can find a main class with everything you need to present our map and test our components.

Our program presents a window with a map and a few buttons to zoom or pan tools enable or our information tool on parcels of an apple.

Tip

It may be useful to consult the existing literature on the component MapControl This documentation is not has been updated with the changes that have made in that component in version 2 of gvSIG broad lines but continues to provide the same functionality and help better understand the tool.

To do this we will:

Integrating with gvSIG

Direct translation from google Translator

So far we have seen how to create our components, logic and user interface, using gvSIG libraries to access the geographic data or to present as well as a simple way to create a small application that uses them. Let's see now as integrate implementing these features in gvSIG.

If we look at the projects we have in your workspace you will see that there is still one on which we have not worked, org.gvsig.visor.app.mainplugin . That is where we implemented plugin. Before the plugin code to see a detailed comment. When we described what had to do our extension, we said we had to present a splash customized. Let us first how we can do this.

In the folder "src/main/resources" folder find a theme, and within this one andami-theme.xml file. This file is responsible for specifying the andami framework which splash must dislay as well as must be used a background image in the application MDI or the gvSIG windows icons. Andami, when starts, searchs into the extensions folder anyone wich contains a theme folder and within this file and when it finds it, it uses it. Xml file in our example contains:

<AndamiProperties>
  <ApplicationImages>
    <SplashImages>
      <Splash
      path="splash.png"
      timer="10000"
      x="270" y="240"
      fontsize="18" 
      color="80,170,240"
      version="2.0"/>
    </SplashImages>
    <!--BackgroundImage path="theme/logo_es.png"/-->
    <!--WallpaperType value="CENTERED"/-->
    <Icon path="$GVSIG_INSTALL/theme/icon.png"/>
  </ApplicationImages>
  <ApplicationName value="gvSIG 2.0.0"/>
</AndamiProperties>

By default routes appear in the file will be interpreted on the location of this file, having a variable GVSIG_INSTALL point to the folder where gvSIG is installed. In the example we see how the tag Splash not indicated path to the file "splash.png" Authors used the files in the folder while the plugin tag Icon variable GVSIG_INSTALL is used to refer the file is in the default theme of Andami.

GvSIG can start and check out the splash indicated in our andami-theme.xml.

Having seen how we can change the splash, we take a look at the extension of our plugin.

Now let's see the code for our plugin. We will see that there are only two classes, VisorExtension and PropertiesOfBlockListener VisorExtension. The class that integrates our functionality in gvSIG is VisorExtension. This class extends the Andami class Extension to integrate with the menus and toolbars, and implements the ExclusiveUIExtension interface to control the visibility of other gvSIG extensions.

To control the visibility of the other areas of gvSIG, the interface ExclusiveUIExtension provides methods:

It is very important delegate isEnabled or isVisible methods of each extension and not return true as you may specify the extent of certain specified conditions; to be visible and active checks herself.

The methods that we find in our class VisorExtension that needs to extend to Extension are:

Basically, we have reviewed as is the integration of our functionality in gvSIG. It remains to be seen PropertiesOfBlockListener class we use to create our tool. The code of the listener is basically similar to that used by our test application.

Distributing our project.

direct translation from google translator*

Once we have our development can be deployed on a run that gvSIG gvSIG and see if it works. Now, normally our work not end there. Typically, we have to do to get these plugins to our users, or even before testers to verify that everything works properly.

With version 2.0 of gvSIG we developed a packaging system that allow us to distribute plugins so that users can install easily from the Add-ons Manager gvSIG (this functionality was ported a gvSIG version 1.11.0).

Tip

You can consult the documentation on how to build packages plugin for gvSIG in the section of the development guide, Generate an installation package in paragraph Generation from installation plugin .

The point is how to generate these packages with our plugins. Like with the standard installation of gvSIG had a utility to assist in the creation of our development projects, there is also a utility to generate a plugin packages already installed on gvSIG.

As we had to activate the project creation wizard from the preferences window, activate the same way this utility. We'll go gvSIG preferences panel, and in general, extensions look "org.gvsig.installer.app.extension.creation.MakePluginPackageExtension", and activate the extension. Once activated we gvSIG restart to take effect changes.

When you reboot gvSIG have the option "Create plugin installation package" in the menu Tools->Development. We will use this tool to build the package Installation of our plugin.

The installation package can be generated directly distribute to our users or to have them reach gvSIG to be exposed in the repository gvSIG supplements and available to users directly from the Add-ons Manager through of the URL displayed by default.

Likewise, for when it is ready the final version of gvSIG 2.0 is expected to have a mechanism that allows to easily include these binary packages in the official distribution gvSIG so that we can have a custom installer for our plugins deliver to our customers.

Conclusions

direct translation from google translator

We saw very quickly how to create our project to develop a functionality to gvSIG 2.0. It is not just a gvSIG development in We can actually see that this is an orderly way to develop, separating the different layers of abstraction that can be found in development:

And each clearly marked as part of our API and what is implementation.

Not only provide functionality to gvSIG, if not we offer the functionality so it can be reused by other developments through a well defined API, pudiéndonos benefit other projects that have packaged functionality as a library.

In addition we will benefit from Maven mechanisms that allow us to deploy these libraries to be easily accessible to other developers.

Finally note that this way of working also allows us to deploy our plugins easily as they reduce the dependencies between plugins directly attack the libraries you need.

Related documents