Local repository

Local disk location where Maven stores downloaded dependencies, so that they do not have to be downloaded every time. The structure corresponds to one folder per groupId (if the groupID contains points, a subfolder will be created for each element), a folder with the name of the artifactId and finally, a folder with the version.

The downloaded dependencies are stored in the folder of the version. For example, see the following dependency in a pom.xml:

<dependency>
    <groupId>org.gvsig</groupId>
        <artifactId>org.gvsig.tools</artifactId>
        <version>2.0-SNAPSHOT</version>
</dependency>

This will be stored in the local Maven repository with the path:

MAVEN_REPO/org/gvsig/org.gvsig.tools/2.0-SNAPSHOT/org.gvsig.tools-2.0-SNAPSHOT.jar

The files stored by Maven in the local repository can be of type:

• pom.xml: the configuration and dependencies of the dependency. In this way, Maven will download the entire tree of dependencies that is needed at any given time so that we don’t have to specify the dependencies of a dependency of our project.
• .jar file with compiled classes.
• .jar file with source code.
• .jar file with javadoc.
• etc.

When specifying a dependency for our project, Maven will by default download only the .jar file with the compiled classes. However, we can specify that the .jar with the source code and / or the javadoc must be downloaded as well.

Remote repositories

Remote repositories are dependency servers where Maven will look when it cannot find a dependency in the local repository.

Common remote repositories that can be accessed via standard protocols are HTTP/S, FTP, SSH, etc.

The Maven project itself has a dependency repository, accessible by HTTP, which is configured by default. In the pom.xml files you can add other external repositories, or repositories of your own project. For example, gvSIG has its own repository, which is registered by default for the gvSIG projects, in addition to the official repositories.

The gvSIG repository is currently accessible through HTTP as read-only, and through SCP in editing mode. This repository contains mainly the files that are generated by the gvSIG projects, as well as any external dependencies that are not available in the official repository.

Maven and Eclipse

One of the most interesting features of Maven is its ability to work with multi-module projects and the options for executing pre-defined targets to perform certain clearly defined tasks, such as code compilation and packaging.

Unfortunately, the current version of Eclipse does not include the necessary mechanisms to support multi-module projects, so that integration with the Maven mechanisms are complex and require the use of certain strategies to simulate such behavior.

Maven uses a Project Object Model (POM) to describe the software project to be built, the structure of the project and its sub-modules, their dependencies on other modules and external components, and the build order of the elements. Using these defined characteristics, you can get Eclipse to use the information in the POMs to simulate multi-module behavior.

Working with Maven in Eclipse

When working with Eclipse, as mentioned above, we will have to follow certain guidelines that will allow us to make use of the functionality Maven offers.

The first thing to note is the naming convention of the directories. The names applied to directories are not random, as they indicate the hierarchical structure of the project. Thus, the name of the parent project will be the name of the artifact_id, and its submodules will include the parent name (for example, if the parent project is org.gvsig.example, the submodule Example1 must be kept in the directory org.gvsig.example/org.gvsig.example.example1, and Example2 in org.gvsig.example/org.gvsig.example.example2. If Example1 has a submodule Example1a, it would be stored in org.gvsig.example/org.gvsig.example.example1/org.gvsig.example.example1a and so on). This gives the project a tree structure:

• org.gvsig.ejemplo
  • org.gvsig.ejemplo.ejemplo1
    • org.gvsig.ejemplo.ejemplo1.ejemplo1a
  • org.gvsig.ejemplo.ejemplo2

The parent nodes are not recognized as Java projects by Eclipse, because they are simply containers of the submodules. These projects contain the POM file with its definition and description of the submodules. In this way, you can launch commands at the parent module to run on that level and all its child nodes automatically (install, compile, etc.).

On the other hand, the child nodes (or leaves of the tree) are Java projects, with their usual project structure. These nodes can take advantage of the parent configuration (dependencies, properties, attributes, ...) if that parent is specified in the POM, simplifying its configuration.

Developing a gvSIG project

When we develop a gvSIG project there should be a strict separation between the API and the implementation of that API. To accomplish this, a basic template for gvSIG projects has been prepared which takes advantage of the Maven capabilities to manage multi-module projects. This template will guide us on how to organize the project, keeping strictly separated the logic of the extension from the user interface, and the API of the logic from its implementation, and the API of the interface from its implementation, in different Eclipse projects and separate jars.

The basic structure of a project will be:

• library
  • tags
  • branches
  • trunk
    • org.gvsig.example
      • org.gvsig.example.lib
        • org.gvsig.example.lib.api
        • org.gvsig.example.lib.spi
        • org.gvsig.example.lib.impl
      • org.gvsig.example.prov
        • org.gvsig.example.prov.provider1
      • org.gvsig.example.swing
        • org.gvsig.example.swing.api
        • org.gvsig.example.swing.impl
      • org.gvsig.example.main
• extensión
  • tags
  • branches
  • trunk
    • org.gvsig.example.app
      • org.gvsig.example.app.extensión

Compared to gvSIG projects prior to the 2.0 version, this project structure would seem rather complex, but we will look into it with more detail.

The first thing to note is that the project is oriented as a multi-module SVN project compared to what we used to see in the development of gvSIG 1.X. On the one hand we have the development of the library and on the other, the extension(s) for gvSIG. This has been organized like this because normally the changes in the logic of our extension usually have a life cycle that is clearly separated from the integration into gvSIG. After development of the extension has been completed, it is easier to do the modifications from one gvSIG version to the next in the parts of the code that contains the integration with gvSIG, while the logic remains unchanged except for some bug corrections. To achieve this independence, the SVN repository is separated into two main groups:

• Library

  This contains the logic and user interface that are independent of gvSIG as an application. This does not mean that they can’t depend on some gvSIG libraries such as the ones for data access, geometry or mapcontext. If they need to depend on those libraries, they can be used.

• Extension.

  This is the part of the code that depends on the gvSIG application, Andami and other gvSIG extensions. This is where the Extension classes are located, as well as the configuration of our Andami plug-in.

In the library we will find the following:

• org.gvsig.example.lib

  This provides the API, SPI, and the implementation of the API.

• org.gvsig.example.prov

  If our library needs to interact with a service provider, this is where the different implementations of these service providers would be located.

• org.gvsig.example.swing

  If our project includes a user interface for the library's logic, it would be located here only. The projects located into org.gvsig.example.lib must not depend on the user interface and, therefore, not on this project.

• org.gvsig.example.main

  You may find it strange to find a main module within the library, but it is actually quite useful. This is a module that provides a test application that you can use to launch the user interface and the logic of the library without having to start gvSIG to test it. This allows for a more agile development of our project, postponing the integration with gvSIG until it is in a more advanced stage of development.

And finally we come to the separation of some of these modules into API, SPI and implementation. This separation can be found in org.gvsig.example.lib and org.gvsig.example.swing.

Imagine that we are developing a network analysis extension for gvSIG. What projects would we be working with?

In principle, our project would not require special service providers. It would consist of the logic, the user interface, and the actual plugin for gvSIG. We would have the following projects:

• org.gvsig.networkAnalysis.lib.api
• org.gvsig.networkAnalysis.lib.impl
• org.gvsig.networkAnalysis.swing.api
• org.gvsig.networkAnalysis.swing.impl
• org.gvsig.networkAnalysis.main
• org.gvsig.networkAnalysis.app.extensión

Basically we would have these six projects, and each of them would generate its own jar, corresponding to the name of the project. Each of the projects will be will be located in its corresponding folder, and it is important that they have the correct name. This is because when you import these projects into Eclipse, we find that the folder tree is flattened; but thanks to the naming convention, these projects retain their consistency in our workspace.

Although it seems obvious, it should be pointed out which dependencies between those projects are acceptable. The implementation will depend on the API, but not vice versa. Also, our API should be concise and complete. Complete because the client of this API should not need to know the implementation in order to use it, and concise because the details of the implementation do not need to be exposed; the less details are exposed, the easier and safer the maintenance will be.

On the other hand, there is the user interface. This, whether the implementation or its API, should have no dependencies on the implementation of the library, or the logic. It should only depend on its API.

And finally, the test implementation and the extension can only depend on the API of the library and the user interface API.

It should also be noted that pom.xml files are found in each of the different folder. So there is a pom.xml in org.gvsig.example that allows us to interact with all the submodules of our project, and it contains the general configuration of the project. For example, through the pom.xml we can directly build the Eclipse projects for each of our modules. In turn, org.gvsig.example.swing and org.gvsig.example.lib have their own pom.xml files with their specific configuration. Finally, each of the final projects will have their own pom.xml file. Each of these pom.xml will be configured indicating the pom of the higher level folder as the parent pom to inherit the common configurations.

We have mentioned API several times. But what do we mean by API? How do we define it?

The question is not as obvious as it seems. When you ask several developers how they define an API module we can end up with very different answers. So, in gvSIG, how do we define an API? Normally, the API consists of a set of Java interfaces. There may be an abstract class that provides a default implementation for something that should be extended by the API user, but it never contains a class with its implementation. As usual, there are exceptions to this. By their nature, exceptions that trigger this API will be implemented in the API. This set of interfaces, packaged in a project and its jar, is the only dependency that the API user must depend on.

When using swing there will be differences. Swing lacks interfaces to handle graphic components, and therefore when it comes to defining the API of the swing part of our project, instead of using interfaces, we use abstract classes that extend the different swing components, adding abstract methods from our project domain. Usually there are abstract classes that extend JPanel, and these define the user interfaces associated with components of our project.

What does the implementation consist of?

Well, there we have a set of classes that implement the interfaces defined in the API. Normally there will be a manager which will serve as entry point to the functionality of our project and its configuration.

It is helpful to review the tools that org.gvsig.tools provides to manage the separation between API and implementation using the Library, Locators and Manager, and the tools that are available for the management of service providers, so that new projects will not need to reinvent each time how to implement these tools, and to harmonize their use throughout gvSIG.

We must also consider the recommendations when naming the classes and interfaces. The project structure described here is designed to follow a naming system such as described in the document nomenclature for classes and interfaces. So the API interfaces are named using meaningful names from the extension domain, without using any kind of prefix or suffix, while the classes that are found in the implementation project and which implement the API interfaces, are named by adding Default as a prefix to the name of the interface that they implement.

Before moving on to the creation of a gvSIG project according to the structure described above, it is recommended to review the documentation about org.gvsig.tools.service that describes in more detail the classes and interfaces to create, and how they are stored in a Maven subproject.

Forewords

This document describes a list of coding conventions that are required for code submissions to the project. By default, the coding conventions for most Open Source Projects should follow the existing coding conventions in the code that you are working on. For example, if the bracket is on the same line as the if statement, then you should write all your code to have that convention.

If you commit code that does not follow these conventions and you are caught, you are responsible for also fixing your own code.

Below is a list of coding conventions that are specific to gvSIG, everything else not specificially mentioned here should follow the official Sun Java Coding Conventions

Why code conventions

As explained in the Sun Java Coding Conventions:

Code conventions are important to programmers for a number of reasons:

• 80% of the lifetime cost of a piece of software goes to maintenance.
• Hardly any software is maintained for its whole life by the original author.
• Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
• If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

How to apply?

Having coding conventions is nice but having a way to ensure they are applied is even better ... :-)

The gvSIG maven configuration has a checkstyle target which performs coding conventions using the Checkstyle tool.

Please run this target before committing any code.

Also the eclipse configuration needed to format the source code taking into account the code conventions defined in the current document will be available in the org.gvsig.maven.base.build project, from the gvsig-tools OSOR project.

If the project you are working with has a prepare-workspace.xml file which you have used to configure your workspace, you will have those files already downloaded and available into the folder:

WORKSPACE/org.gvsig.maven.base.build/eclipse-configs

Otherwise, you may download all the files through the repository URL:

https://devel.gvsig.org/svn/gvsig-tools/org.gvsig.maven.base/trunk/org.gvsig.maven.base/org.gvsig.maven.base.build/src/main/resources/org.gvsig.maven.base.build/eclipse-configs/

To import those configurations perform the following:

1. Clean up:
   • Go to Window > Preferences > Java > Code Style > Clean Up and click the button Import.
   • In the file system explorer, select the clean_up.xml file.

1. Code templates:
   • Go to Window > Preferences > Java > Code Style > Code Templates and click the button Import.
   • In the file system explorer, select the code_templates.xml file.
   • Activate the option Automatically add comments for new methods and types.

1. Formatter:
   • Go to Window > Preferences > Java > Code Style > Formatter and click the button Import.
   • In the file system explorer, select the formatter.xml file.

1. Organize imports:
   • Go to Window > Preferences > Java > Code Style > Organize Imports and click the button Import.
   • In the file system explorer, select the organize_imports.importorder file.

gvSIG specific coding conventions

Introduction

This document defines rules for naming classes and interfaces that allow a common style for gvSIG components to be maintained.

The importance of consistency in naming is obvious if one considers a complete Javadoc implementation. From the point of view of the reader, using a variety of naming conventions would create confusion and complicate the understanding of the component.

Criteria to follow

public interface List {}
public abstract class AbstractList extends AbstractCollection implements List {}

public interface ListModel {}
public abstract class AbstractListModel implements ListModel, Serializable {}
public class DefaultListModel extends AbstractListModel {}

public abstract class StreamRequestHandler {}
public class BaseHTTPRequestHandler extends StreamRequestHandler {}

public interface Plane {}
public abstract class AbstractPlane implements Plane {}
 
// Both are correct (but not equal)
public class PlaneImpl implements Plane {} 
public class PlaneImpl extends AbstractPlane {}

Application Conditions

This criterion is applicable to new developments undertaken for gvSIG 2.0 and will be part of the official gvSIG distribution as well as for all developments financed in whole or in part by the CIT.

Preliminary considerations

Due to the variability and lack of unity in the names of packages used in gvSIG 1.X, it has been decided to standardize these, thereby giving the project an identity that over-rides that of the company doing the development.

Criteria to follow

When creating java packages that will be part of an official gvSIG release, or that will carry the official endorsement of the gvSIG project, the following package is appended:

org.gvsig

No mention is made in the package of the company doing the development.

Normally, the package name org.gvsig is followed by a package name identifying the logical or functional block that it contains.

Application Conditions

These criteria will be applied to new developments to be made to gvSIG 2.0, and will be part of the official gvSIG distribution as well as for all developments financed in whole or in part by the CIT.

Features of SLF4J

• SLF4J is an abstraction layer independent of any actual logging system.
• Allows the end user to attach the desired implementation at deployment time.
• Allows gradual migration from Jakarta Commons Logging (JCL), because it has a JCL API wrapper in its own API.
• There is a parameterized logging system that reduces the overhead of assessing the message strings, especially when debug messages are enabled.

// Those lines produce the same results. The second one has parameters that reduce the overhead when debugging is disabled
LOG.debug("The new entry is "+entry+"."); 
LOG.debug("The new entry is {}.", entry);

• Support for Mapped Diagnostic Context (MDC), if the logging system operating under SLF4J supports it. At the moment only Log4j and logback do so.
• Logging systems may choose to implement the SLF4J interface directly as logback and SimpleLogger, or write SLF4J adapters for a given implementation as in the cases of Log4jLoggerAdapter and JDK14LoggerAdapter.
• Does not delegate to a specific class loading system (class loader) for delegating to a specific logging system, ie statically configured at compile time, only allowed to use one and only one logging system. Simply add the logging system API's jar to the CLASSPATH, together with slf4j-api.jar. This avoids the problems of class loading and memory loss suffered by Jakarta JCL.
• SLF4J also has an interface very similar to the JCL and Log4j APIs currently in use, so the implementation effort is significantly reduced.
• gvSIG continues to use the same logging toolkit (Log4j) so there will be practically no changes at run time.
• You gain in flexibility, robustness and efficiency through the ability to change the logging component without modifying the gvSIG source code, either for all versions of gvSIG or for specific versions.
• It's the standard that has been collected in OSGI projects because projects that are already using commons-logging can be adapted easily due to the popularity that this framework has gained.

Using SLF4J in gvSIG

gvSIG 2.0 is ready to work with SLF4J, using LOG4J as implementation, and can be used directly from any gvSIG extension.

To use SLF4J from a Java class just include the following statements:

1.- Import the necessary classes:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

2.- Declare and initialize the Logger:

public class MyClass
{
    private static final Logger LOG = LoggerFactory.getLogger(MyClass.class);
    ...

3.- We use the Logger within the code of the class when we want to display a log message, depending on the type: error, warning, information, debug or trace:

LOG.warn(String message);
LOG.warn(String message,Object arg1);
LOG.warn(String message,Object[] arg1);
LOG.warn(String message, Throwable arg1);
LOG.info(String message);
LOG.info(String message,Object arg1);
LOG.info(String message,Object[] arg1);
LOG.info(String message, Throwable arg1);
LOG.error(String message);
LOG.error(String message,Object arg1);
LOG.error(String message,Object[] arg1);
LOG.error(String message, Throwable arg1);
LOG.debug(String message);
LOG.debug(String message,Object arg1);
LOG.debug(String message,Object[] arg1);
LOG.debug(String message, Throwable arg1);
LOG.trace(String message);
LOG.trace(String message,Object arg1);
LOG.trace(String message,Object[] arg1);
LOG.trace(String message, Throwable arg1);

The following methods are provided to check the activation of messages for each level:

LOG.isErrorEnabled();
LOG.isWarnEnabled();
LOG.isInfoEnabled();
LOG.isDebugEnabled();
LOG.isTraceEnabled();

In addition, the messages can also be customized in SLF4J by inserting variables into the String of the log message, as in the following example:

private Integer temperature;

public void setTemperature(Integer temperature) {

    LOG.debug("Setting temperature to {}. Old temperature was {}.", temperature, this.temperature);

    this.temperature = temperature;

    if(temperature.intValue() > 50) {
      LOG.info("Temperature has risen above 50 degrees.");
    }
}

This stops us from having to concatenate Strings, which reduces the cost of using the instructions for logging. This is because, although the log level that we are using is disabled (for example, debug), the method call will be made anyway, including the concatenation of strings to build the message, if any.

However, if the obtaining of any of the parameters to be passed to the message log proves costly, it is convenient to use the consultation methods to avoid such implementation. For example:

private Integer temperature;

public void setTemperature(Integer temperature) {

    LOG.debug("Setting temperature to {}. Old temperature was {}.", temperature, this.temperature);

    this.temperature = temperature;
    addToTemperatureLog(temperature);

    if (LOG.isDebugEnabled()) {
        LOG.debug("The current average temperature is {} Celsius", calculateAverageTemperature());
    }
}

Introduction

In parallel to the release of version 2.0 of gvSIG we have been doing some refactoring work on the projects that are part of the core of gvSIG 2. They have been designed to provide to the maven structure to all projects that form the main gvSIG workspace, and also to provide a maven multimodule that encompasses all these ones, wherein the projects and folders structure were coindicent. It has also been removed the need to generate multiple maven project artifacts, it's also been removed dependencies between API and implementation of some projects, included the ones that had dependencies with other projects.

The changes that have taken place affect mainly poms and, to a lesser degree, the source code.

We have tried to keep compatibility at the APIs level, not changing any in order to avoid incompatibility with the version 2.0. This way the gvSIG plugins compiled for version 2.0 still work with the new version of gvSIG.

The most relevant changes to be found are:

• Changes in the poms.
  • Changes in IDs maven artifacts.
  • Removed the use of classifiers to generate several artifacts from a given project.
  • The hierarchy of poms' project had been changed.
  • Is reduced to the minimum the use of profiles
  • Some variables used in the poms have been renamed or are no longer defined, and others that were defined within a profile have come to be defined within project because of the deleted profile.
• The distribution.xml file was renamed and its location had changed.
• Changes in the names of plugins
• Changes in the names of packages / plugins of gvSIG.
• There are projects that come out of the gvsig-desktop SVN and from the main gvSIG workspace.
• Changes in the source code... these are typically due to error fixing or because the API has been extended to add new functionality.
• Update of the gvSIG license from GPL version 2 to version 3.

We will describe the changes and how they affect the developer who needs to migrate from version 2.0 to version 2.1.

Changes on poms: artifactsId y classifiers

Changes on maven artifactId are mainly because the restriction that a project should not produce more of an artifact. When this happened in the past, a parent project was created with a subproject by artifact generated. For example, before we had a project called "libFMap_dal/org.gvsig.fmap.dal" that generated the jars:

• org.gvsig.fmap.dal-2.0.jar
• org.gvsig.fmap.dal-2.0-impl.jar
• org.gvsig.fmap.dal-2.0-spi.jar

Now this project has been splited into the following projects:

• org.gvsig.fmap.dal

  • org.gvsig.fmap.dal.api
  • org.gvsig.fmap.dal.impl
  • org.gvsig.fmap.dal.spi

The code source that were formerly in a single project had been splited into three projects, each generating its corresponding jar.

Besides these changes in the artifactId, which are mainly in the libraries of the project, we have also changed some artifactId of the projects' type plugin. The name and structure of the gvSIG plugins that were in the SVN gvsig-desktop had been normalized.

We can see the artifactId that have changed in the following table:

Changes on poms: the project's hierarchy

The hierarchy of projects in version 2.0 was little intuitive. We had a number of projects such as:

• org.gvsig.maven.base.build
• org.gvsig.maven.base.extension.pom
• org.gvsig.maven.base.jni.pom
• org.gvsig.maven.base.pom
• gvsig-base-extension-pom
• gvsig-base-library-pom
• gvsig-base-library-jni-pom
• gvsig-base-pom
• gvsig-base
• gvsig-standard
• org.gvsig.core.maven.dependencies

Among them it was difficult to navigate or control the hierarchy that existed between them and from which we had to extend to create the new project, contributing that hierarchy's folder do not correspond with the one of the project.

What has been done was to redistribute the functionality that was in those projects in six new projects, aligning its structure with the one of the folders. The projects are:

└── org.gvsig.desktop
    ├── org.gvsig.desktop.compat.cdc
    │
    ├── org.gvsig.desktop.framework
    │
    ├── org.gvsig.desktop.installer
    │
    ├── org.gvsig.desktop.library
    │
    └── org.gvsig.desktop.plugin

These projects represent the different types of project that we will find in gvSIG. In each of them we can find:

• org.gvsig.desktop All gvSIG projects are extended from that one, and thus we will have to extend also to create our new projects. It sets some maven plugins and versions of the gvSIG libraries, as well as that of the core libraries of gvSIG.
• org.gvsig.desktop.plugin contains all the settings needed to compile, package and install our plugin of gvSIG. Also, they are children of this project, and therefore may be found in the same folder of the SVN, all projects which type is plugin that are part of the gvSIG core.
• org.gvsig.desktop.compat.cdc, contains the gvSIG project settings to be compatible with java-cdc.
• org.gvsig.desktop.library, has the settings for the libraries of gvSIG. These projects had only a few settings because the needed configuration for a library is basically contained in org.gvsig.desktop, so basically acts as a container for these.
• org.gvsig.desktop.framework, acts as a container of andami and andami.updater project.
• org.gvsig.desktop.installer, contains the settings needed to generate the gvSIG binaries.

A small comment for those who will compile fully gvSIG desktop. In the version 2.0 to compile gvSIG we downloaded the build folder and from there we began to work. With version 2.1 this changes. Now the build folder does not exist any more. To compile gvSIG desktop we will download the org.gvsig.desktop, and simply execute one "mvn install" from there. If we are working with Eclipse, we will need to have installed the eclipse plugin m2e plugin.

Well, with "mvn install" the entire gvSIG will be compiled.... And where are the binaries of gvSIG?

Well, it depends. If this is the first time you compile gvSIG, these remain in the target/product folder. When you compile gvSIG it is checked whether it exists in the "home" of the user the file called ".gvsig-devel.properties" in which it is indicated where to deploy gvSIG. If it does not exist it will be created indicating it will be deployed on the folder called "org.gvsig.desktop/target/product" from which we launched the compilation.

Changes on poms: profiles and properties

In the gvSIG poms there were defined a number of properties with several uses. In the current configuration, the only relevant properties are:

Basically, on the table above, we'll see that it is only used the gvsig.product.folder.path variable, which indicates where our gvSIG plugins and the variables gvsig.package.info are deployed, which are used to configure the package associated with the plugin. Need to comment, that although in the project org.gvsig.desktop.plugin those variables are initialized by default, in each plugin they must be overwritten with the appropriate values ​​to that plugin, and noted that these properties already existed in the 2.0 version, but have been renamed. Previously they were called something like "package.info ..." and now they have the prefix "gvsig ...." but still have the same meaning they had in version 2.0.

In relation to the use of "profiles" in the maven projects, the general rule is that these have disappeared. The main use of these within gvSIG was in order to:

• Distinguish between javacdc and javase compatible compilation. Now we use simply a different configuration for some projects than others, having the projects that must be CDC compatible one common ancestor that have that configuration.
• Throwing some specific Eclipse settings tasks. It is no longer used "launchers" to run or compile special projects. In its place we'll use instead directly the m2e eclipse plugin.
• Configure and activate special options that can deploy gvSIG plugins properly. This is not necessary any more as it has been integrated into the "package" and "install" maven phase.

The use of profiles for these tasks has been removed from the gvSIG projects, so it should not be necessary to use them. However, before deleting the profiles from your project, check that properties are not declared on them that will be used from somewhere else, such as the properties "package.info" used to the configuration of the "package.info".

Se ha introducido el uso de perfiles para identificar de forma correcta a los proyectos que despliegan plugins de gvSIG. De forma que los plugins de maven especificos de procesar plugins de gvSIG solo se activan cuando se encuntra en fichero "buildNumber.properties" en la carpeta del proyecto.

Changes on poms: package e install of a gvSIG's plugin

With the new configuration on the basis projects, when we have a gvSIG project of the type plugin, it should be extended from org.gvsig.desktop.plugin. With that we'll inherit all the settings required to package and install the plugin.

A "mvn package" will let the resulting package in the target folder of our project.

In order to deploy the plugin against the gvSIG installation we'll need to do something else. We'll have to go to our user folder in linux $HOME and see that we have a ".gvsig-devel.properties" file which has a declared variable "gvsig.product.folder.path". Its value should be at the gvSIG installation where the plugin must be deployed. If this occurs, an "mvm install" will deploy the plugin in that folder.

The distribution.xml file and plugin's resources

When compiling a library project, all the resources will often go to the jar associated to this library. However when compiling a gvSIG plugin project the resources can get into the jar or into the folder in which the plugin is installed. In the 2.1 version of gvSIG, resources are separated. Resources that are going to be left in the jar will be on the folder src/main/resources, in order to be included on the natural cycle of Maven including them on the jar. And the resources that go to the plugin folder will be left in the folder src/main/plugin-resources, keeping on that folder the structure that will have on the plugin folder once installed, thus making easier the package and deployment of the plugin.

Along with the change of location of some resources, the file "distribution.xml" has also been changed, which has been moved to src/main/assembly/gvsig-plugin-package.xml eliminating the distribution file. It has changed the way in which it is packaged, before it was used as "format", "dir" and now it is used "zip". The package is no longer made directly on the folder where the plugin is deployed, but on a zip file in the target folder of the plugin, maintaining the structure that has the package of the plugin. It will be in the install phase when the plugin will be deployed on gvSIG installation.

Previously the file package.info was generated in the root of your project, but now this will be generated in the target folder.

If we want to continue packing as in version 2.0, we should overwrite the configuration of the plugin maven-assembly-plugin to continue invoking the distribution.xml file.

Changes on the plugin's names

The next table shows the changes applied to plugin's name.

To keep the impact of this change as low as possible, in addition to the changes responsible for the management and implementation of the plugins, it has been created a new property in the "config.xml" file of the plugins that allow us to declare alternative names for the plugin. Thus, the plugins that have been renamed declared as an alternate name or alias the old name. This allows that plugins that had declared dependencies to plugins that have been renamed, can continue working out correctly. Likewise, the management functions of PluginsManager and PluginService plugings are able to deal adequately with the plugin name on version 2.0. Also when those functions are asked for a plugin using the name relatred to the 2.0 version, they correctly return the folder associated with that plugin, or its instance even if the plugin was renamed.

The way in which a plugin specifies an alternative name or alias shpould be using the "alternativeNames" tag in "config.xml" file:

<plugin-config>
  ...
  <alternativeNames name="org.gvsig.app"/>
  <icon src="gvsig-logo-icon" text="gvSIG"/>
  <libraries library-dir="lib"/>
  ...
</plugin-config>

Despite the changes in the source to reduce the impact, this change will affect plugins that interact directly with other plugins' folder, without going through the API in order to get the associated file to the plugin's folder.

Projects that are not any more on the main gvSIG workspace

In addition to changes in the structure of the main SVN gvSIG projects, there are some projects coming out in order to have its own project on the gvSIG infrastructure with its own SVN. Some of them were already separated projects in the gvSIG SVN, and others were part of one or more projects. In general these projects are composed by data providers for some formats along with its supporting libraries and plugin that installs them. Projects that are new to the gvSIG development infrastructure are:

• org.gvsig.dwg
• org.gvsig.dgn
• org.gvsig.dxf
• org.gvsig.postgresql
• org.gvsig.mysql

Changes applied to source code

In addition to the changes inherent to error corrections, changes were made because of the refactoring itself. On the following lines you'll find a short review of these modifications:

• Removed implementation of GeneralPathX from the API of geometries, r40388
• Added to geometry library the support of spatial index, r40387, r40363
• Removed dependencies of the implementation of geometries on the operations library r40386, r40364, r40359,
• Added support to specify the SRS in the conversion to wkb on the GeometryManager, r40366
• Added methods useful in GeometryManager to create curve, surface, and MultiSurface Multicurve, r40393
• Added useful methods in OrientablePrimitive to add vertexs using x, y, z instead of Point, r40393
• Marked as deprecated all the methods of the GeometryManager that work with GeneralPathX, and commented in its javadoc what is to be used in place r40393
• Moved the code that was in appgvsig dependent of the implementation projections to the library org.gvsig.projection.cresques.ui. It has remained the same package names to avoid breaking compatibility with what we already had. r40392, r40398, r40398 and R40400
• In the libraries that were compatible with java 1.4 some pieces of code were corrected, r40358, r40357, r40360, r40370, r40362
• Removed dependencies with JTS where there were methods on the geometries' API that offered the same functionality, r40394, r40391
• It was replaced in several points the use of GeneralPathX for the use of the geometries' API, r40394, r40389
• At several points it has been replaced direct invocation to the geometries' libary operations for the use instead of its methods r40373, r40372, r40368, r40394, r40367
• Replaced in several points the invocation to the implementation of geometries by the use of the API's methods r40373, r40372, r40396.
• Replaced the use of the Quadtree in jts by the handling of spatial indexes from the geometry library, r40371

Changes on the gvSIG license

We have been reviewing the licenses of individual libraries used by gvSIG, and we detected some incompatibilities with some of them regarding the gvSIG license (til now the GPL 2). Many of these incompatibilities are solved in the next version of the GPL, so it was decided to upgrade the gvSIG license version to the GPL 3. For developers, this change may involve not only the upgrade of version, but the modification of all the gvSIG sources to upgrade headers to GPLv3.

Setting all together

Well ... and all that I have told ...

How does it affect developers who want to migrate their gvSIG plugin to version 2.1?

If you have it compiled for the 2.0 version and want to distribute it, it should be able to do it without extra effort.

If you want to compile for the 2.1 version to take advantage of some of the features that are added, you would have to:

• Modify the poms to put as the father of these to org.gvsig.desktop or

  org.gvsig.desktop.plugin.

• If in the poms the properties "package.info" is defined or used, we

  should rename them to "gvsig.package.info".

• If we have defined properties in some poms' profile, they should pass them to the project's properties.

• Delete the profiles that are not specific to our project

• In the poms of projects that are gvSIG plugins add the

  following maven plugins:

  <build>
    <plugins>
      ...
  
      <plugin>
      <artifactId>maven-assembly-plugin</artifactId>
          <executions>
            <execution>
              <id>gvsig-plugin-package</id>
              <phase>package</phase>
              <goals>
                  <goal>single</goal>
              </goals>
            </execution>
          </executions>
      </plugin>
  
      <plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <executions>
          <execution>
            <id>gvsig-plugin-install</id>
            <phase>install</phase>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
  
      ...
  
    </plugins>
  </build>
  

• The file src/main/assembly/gvsig-plugin-package.xml will be created with content similar to:

  <assembly>
    <id>gvsig-plugin-package</id>
    <formats>
      <format>zip</format>
    </formats>
    <baseDirectory>${project.artifactId}</baseDirectory>
    <includeBaseDirectory>true</includeBaseDirectory>
    <files>
      <file>
        <source>target/${project.artifactId}-${project.version}.jar</source>
        <outputDirectory>lib</outputDirectory>
      </file>
      <file>
        <source>target/package.info</source>
      </file>
    </files>
  
    <fileSets>
      <fileSet>
        <directory>src/main/resources-plugin</directory>
        <outputDirectory>.</outputDirectory>
      </fileSet>
    </fileSets>
  
    <dependencySets>
      <dependencySet>
        <useProjectArtifact>false</useProjectArtifact>
        <useTransitiveDependencies>false</useTransitiveDependencies>
        <outputDirectory>lib</outputDirectory>
        <includes>
          <include>...</include>
        </includes>
      </dependencySet>
    </dependencySets>
  
  </assembly>
  

Replacing the line:

<include>...</include>

For the "distribution.xml" corresponding lines in which we should identify the dependencies that must be carry on by the gvSIG plugin into its "lib" file. This list will not include the jar from our plugin as this is copied in another section of the assembly. In case you do not have to move dependencies we can eliminate the entire section "dependencySet" from the assembly and once updated the file "gvsig-plugin-package.xml" remove the folder "distribution".

• We will update our project artifactId agree to the table "Changes in the artifactId" included in this document.
• We will make sure that we do not include version numbers in the dependencies, at least in those that are already provide by gvSIG, so that these are taken from the parent pom org.gvsig.desktop in order to stay all consistent.
• Will remove the file "buildNumber.properties" from all projects that will not generate gvSIG plugins (before it was necessary that were created on the the ancestors althought they were not used).

And after that, with a little of luck, we run a "mvn clean" of the project to verify that you can resolve all dependencies, and "mvn install" to compile and deploy it.