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.