:Version: 1.0

.. contents::

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:

.. list-table:: Changes on the artifactId
   :header-rows: 1

   * - artifactId (2.0)
     - classifier (2.0)
     - artifactId (2.1)

   * - org.gvsig.projection
     - 
     - org.gvsig.projection.api

   * - org.gvsig.projection
     - cresques-impl
     - org.gvsig.projection.cresques.impl

   * - org.gvsig.projection
     - cresques-ui
     - org.gvsig.projection.cresques.ui

   * - org.gvsig.fmap.mapcontext
     - 
     - org.gvsig.fmap.mapcontext.api

   * - org.gvsig.fmap.mapcontext
     - impl
     - org.gvsig.fmap.mapcontext.impl

   * - org.gvsig.fmap.mapcontext
     - operation
     - org.gvsig.fmap.mapcontext.operation

   * - org.gvsig.fmap.dal
     -
     - org.gvsig.fmap.dal.api

   * - org.gvsig.fmap.dal
     - spi
     - org.gvsig.fmap.dal.spi

   * - org.gvsig.fmap.dal
     - impl
     - org.gvsig.fmap.dal.impl

   * - org.gvsig.fmap.dal.db
     - 
     - org.gvsig.fmap.dal.db.lib

   * - org.gvsig.fmap.dal.db
     - jdbc
     - org.gvsig.fmap.dal.db.jdbc

   * - org.gvsig.fmap.dal.index.spatial
     - gt2
     - org.gvsig.fmap.dal.index.spatial.gt2

   * - org.gvsig.fmap.dal.index.spatial
     - jts
     - org.gvsig.fmap.dal.index.spatial.jts

   * - org.gvsig.fmap.dal.index.spatial
     - jsi
     - org.gvsig.fmap.dal.index.spatial.jsi

   * - org.gvsig.fmap.dal.file
     -  
     - org.gvsig.fmap.dal.file.lib

   * - org.gvsig.fmap.dal.file
     - store.dbf
     - org.gvsig.fmap.dal.file.dbf

   * - org.gvsig.fmap.dal.file
     - store.shp
     - org.gvsig.fmap.dal.file.shp

   * - org.gvsig.fmap.geometry
     - 
     - org.gvsig.fmap.geometry.api

   * - org.gvsig.fmap.geometry
     - impl
     - org.gvsig.fmap.geometry.impl

   * - org.gvsig.fmap.geometry
     - operation
     - org.gvsig.fmap.geometry.operation

   * - org.gvsig:org.gvsig.compat
     - 
     - org.gvsig.compat.api

   * - org.gvsig:org.gvsig.compat
     - se
     - org.gvsig.compat.se

   * - org.gvsig.app
     - 
     - org.gvsig.app.mainplugin

   * - org.gvsig.coreplugin
     - 
     - org.gvsig.coreplugin.app.mainplugin

   * - org.gvsig.geodb
     - 
     - org.gvsig.geodb.app.mainplugin

   * - org.gvsig.editing
     - 
     - org.gvsig.editing.app.mainplugin

   * - org.gvsig.exportto.app.extension
     - 
     - org.gvsig.exportto.app.mainplugin

   * - org.gvsig.help
     - 
     - org.gvsig.help.app.mainplugin

   * - org.gvsig.i18n.extension
     - 
     - org.gvsig.i18n.app.mainplugin

   * - org.gvsig.annotation.app.extension
     - 
     - org.gvsig.annotation.app.mainplugin

   * - org.gvsig.newlayer.app.extension
     - 
     - org.gvsig.newlayer.app.mainplugin




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:


.. list-table:: Properties used in the poms
   :header-rows: 1

   * - Name
     - Description
     - Value
     - Defined in

   * - gvsig.product.folder.path
     - Folder were gvSIG and its plugins compiled will be deployed.
     - ${basedir}/target/product
     - org.gvsig.desktop

   * - gvsig.desktop.children.version
     - Version of the project org.gvsig.desktop and of all their children that are on the gvsig-desktop SVN. 
     - 2.0.10-SNAPSHOT
     - org.gvsig.desktop

   * - gvsig.package.info.state
     -
     - Devel
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.official
     -
     - false
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.operatingSystem
     -
     - All
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.architecture
     -
     - All
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.javaVM
     -
     - j1_5
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.gvSIGVersion
     -
     - 2.0.0
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.poolURL
     -
     - http://downloads.gvsig.org/download/gvsig-desktop/pool
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.dependencies
     -
     - required: org.gvsig.app.mainplugin -ge 2.1.0
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.owner
     -
     - gvSIG Association
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.sourcesURL
     -
     - ${project.scm.url}
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.webURL
     -
     - http://www.gvsig.com
     - org.gvsig.desktop.plugin

   * - gvsig.package.info.categories
     -
     -
     - org.gvsig.desktop.plugin



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. 

.. list-table:: Changes to plugin's names.
   :header-rows: 1

   * - gvSIG 2.0
     - gvSIG 2.1

   * - org.gvsig.app
     - org.gvsig.app.mainplugin

   * - org.gvsig.coreplugin
     - org.gvsig.coreplugin.app.mainplugin

   * - org.gvsig.geodb
     - org.gvsig.geodb.app.mainplugin

   * - org.gvsig.editing
     - org.gvsig.editing.app.mainplugin

   * - org.gvsig.exportto.app.extension
     - org.gvsig.exportto.app.mainplugin

   * - org.gvsig.help
     - org.gvsig.help.app.mainplugin

   * - org.gvsig.i18n.extension
     - org.gvsig.i18n.app.mainplugin

   * - org.gvsig.annotation.app.extension
     - org.gvsig.annotation.app.mainplugin

   * - org.gvsig.newlayer.app.extension
     - org.gvsig.newlayer.app.mainplugin

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::

  
    ...
    
    
    
    ...
  

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::

    
      
        ...

        
        maven-assembly-plugin
            
              
                gvsig-plugin-package
                package
                
                    single
                
              
            
        

        
          maven-antrun-plugin
          
            
              gvsig-plugin-install
              install
              
                run
              
            
          
        

        ...

      
    

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

    
      gvsig-plugin-package
      
        zip
      
      ${project.artifactId}
      true
      
        
          target/${project.artifactId}-${project.version}.jar
          lib
        
        
          target/package.info
        
      

      
        
          src/main/resources-plugin
          .
        
      

      
        
          false
          false
          lib
          
            ...
          
        
      

    

Replacing the line::

    ...

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. 


.. list-table:: Registro de cambios
   :header-rows: 1

   * - versión
     - Descripción

   * - 2.0
     - En *introduccion*, el punto que dice "Los proyectos de tipo 
       *plugin de gvSIG*" se ha eliminado.
    
   * - 2.0
     - En *introduccion*, el punto que que habla de la eliminacion de perfiles
       ha sifo modificado.
       
   * - 2.0
     - En *Cambios en los poms: perfiles y propiedades*, donde hacia referencia
       a la propiedad "gvsig.package.info.baseDownloadURL" ahora hace referencia
       a "gvsig.package.info.poolURL" cambiando tambien su valor.
       
   * - 2.0
     - En *Cambios en los poms: perfiles y propiedades*, Se ha añadido al final
       un parrafo comentando la introduccion de perfiles para la comilacion
       de los plugins de gvSIG.
       
   * - 2.0
     - La seccion *Cambios en los poms: package e install de un plugin de gvSIG*, 
       Ha sido simplificada.
       
   * - 2.0
     - En *Poniendolo todo junto*, el punto "En los poms de los proyectos que 
       sean plugins de gvSIG añadiremos" se elimina.