Locator

Para gvSIG, el patrón del Locator se aplicará con una implementación basada en el uso de los puntos de extensión. Para los módulos o librerías, se usará además un mecanismo de inicialización que permita registrar las implementaciones que aporte en su Locator.

Para la implementación del Locator se ha creado un interfaz, que define los métodos de uso general, una implementación abstracta, basada en el uso de los puntos de extensión, y una clase base:

El interfaz del Locator se han definido métodos que permiten registrar clases, o factorías, así cómo obtener instancias de los mismos. Hay que tener en cuenta que el comportamiento del Locator no es como factoría, por lo que se espera que el método get devuelva cada vez la misma instancia de objeto. Es decir, actúa como un contenedor de referencias a objetos que funcionan como Singleton.

La implementación abstracta la aporta la clase AbstractLocator, y la implentación básica BaseLocator. La idea es que cada librería implemente su Locator extendiendo esta clase, aportando métodos que registren y obtengan referencias a sus tipos de objetos directamente. Más adelante, se muestra un ejemplo de implementación que aporta este tipo de métodos. Además, cada implementación de Locator deberá hacerse empleando el patrón Singleton, para facilitar el acceso al Locator.

El uso del Locator nos aporta algunas ventajas adicionales, como son:

• Las implementaciones no incorporan nada en lo que respecta a cómo se crean o se obtienen, lo que mejora su extensibilidad y la creación de tests unitarios. Además, se facilita la programación con interfaces y la definición de APIs.
• Soporte a implementaciones alternativas: como por ejemplo para Java SE y Java ME, o cuando haya una implementación básica, y el usuario pueda instalar una implementación extendida.
• Soporte de múltiples implementaciones: si existen distintas implementaciones para un mismo interfaz o componente, que se usan dependiendo de distintas opciones, como acciones del usuario, tipos de datos, etc.

Ejemplo de uso

A continuación se plantea un ejemplo, basado en la librería libCompat. Esta librería plantea el caso de implementaciones alternativas para Java SE y Java ME, por lo que requerirá una estructura de proyectos que permita organizar la librería en tres componentes de instalación:

libCompat:

Será la librería de API. Contendrá los APIs de la librería, en forma de interfaces de las distintas utilidades que aporta (StringUtils, FileUtils, etc.), así como un CompatLocator que dé acceso a las implementaciones correspondientes de dichas utilidades. También puede contener algunas implementaciones Base o Abstractas, que se empleen de forma común en las implementaciones por entorno.

libCompatSE:

Incluirá las implementaciones para Java SE.

libCompatME:

Proporciona las implementaciones para Java ME.

A continuación se muestran ejemplos de código, centrándonos en el uso de una de las utilidades de libCompat: StringUtils.

Primero, en libCompat se incluirá la definición del interfaz de StringUtils:

package org.gvsig.compat.lang;

public interface StringUtils {

    String[] split(String input, String regex);

    ...
}

En libCompatSE, tendremos una implementación:

package org.gvsig.compat.se.lang;

import org.gvsig.compat.lang.StringUtils;

public class StandardStringUtils implements StringUtils {

    public String[] split(String input, String regex) {
        return input == null ? null : input.split(regex);
    }

    ...
}

En libCompatME, la implementación alternativa:

package org.gvsig.compat.me.lang;

import java.util.regex.Pattern;
import org.gvsig.compat.lang.StringUtils;    

public class MobileStringUtils implements StringUtils {

    public String[] split(String input, String regex) {
        return input == null ? null : Pattern.compile(regex).split(input, 0);
    }

    ...
}

En libCompat tenemos la implementación del Locator de la librería, que quedaría como sigue:

package org.gvsig.compat;

import org.gvsig.compat.lang.StringUtils;

public class CompatLocator extends BaseLocator {

    /** The name of the StringUtils reference. */
    public static final String STRINGUTILS_NAME = "StringUtils";

    /** Unique instance. */
    private static final CompatLocator instance = new CompatLocator();

    /**
     * Return the singleton instance.
     * @return the singleton instance
     */
    public static CompatLocator getInstance() {
        return instance;
    }

    /**
     * Return a reference to StringUtils.
     * @return a reference to StringUtils
     * @throws LocatorException
     *             if there is no access to the class or the class cannot be
     *             instantiated
     * @see Locator#get(String)
     */
    public static StringUtils getStringUtils() throws LocatorException {
        return (StringUtils) getInstance().get(STRINGUTILS_NAME);
    }
    
    /**
     * Registers the Class implementing the StringUtils interface.
     * @param clazz
     *            implementing the StringUtils interface
     */
    public static void registerStringUtils(Class clazz) {
        getInstance()
          .register(STRINGUTILS_NAME, STRINGUTILS_DESCRIPTION, clazz);
    }
}

En esta implementación de Locator, se han añadido métodos estáticos que facilitan el uso del mismo, y manejan referencias de los tipos de la librería en concreto, como el StringUtils. Así, por ejemplo, los clientes no tienen porqué usar el método get(name) genérico del Locator, sino que pueden usar un método getStringUtils() directamente.

Una clase cliente que quiera usar, por ejemplo, el StringUtils, podrá hacerlo de la siguiente forma:

public class SampleClient {
  private StringUtils stringUtils = CompatLocator.getStringUtils();

  public void doSomething() {
     String text = "one,two,three";

     String[] words = stringUtils.split(text, ",");
  
     ...
  }
}

Sólo quedaría por ver cómo se registran las implementaciones a usar en el Locator. Para ello emplearemos el mecanismo de inicialización de librerias del paquete org.gvsig.tools.library .

libCompatSE y libCompatME tendrán cada una su Library que registre la implementación correspondiente de StringUtils.

SECompatLibrary:

package org.gvsig.compat.se;

import org.gvsig.compat.CompatLocator;

/**
 * Initialization of the libCompat library, Java Standard Edition
 * implementation.
 * @author <a href="mailto:cordin@disid.com">Cèsar Ordiñana</a>
 */
public class SECompatLibrary extends BaseLibrary {
    protected void doInitialize() {
        super.initialize();
        CompatLocator.registerStringUtils(StandardStringUtils.class);
    }
    protected void doPostInitialize() {
    }
}

MECompatLibrary:

package org.gvsig.compat.me;

import org.gvsig.compat.CompatLocator;

/**
 * Initialization of the libCompat library, Java Mobile Edition implementation.
 * @author <a href="mailto:cordin@disid.com">Cèsar Ordiñana</a>
 */
public class MECompatLibrary extends BaseLibrary {
    protected void doInitialize() {
        super.initialize();
        CompatLocator.registerStringUtils(MobileStringUtils.class);
    }
    protected void doPostInitialize() {
    }
}

La librería de API libCompat, tiene un Library que comprueba si se ha registrado alguna de las implementaciones, lo que permite validar rápidamente si ha habido algun problema de configuración y no se ha registrado ninguna implementación para StringUtils:

CompatLibrary:

package org.gvsig.compat;

import org.gvsig.compat.lang.StringUtils;

/**
 * Initialization of the libCompat library.
 * @author <a href="mailto:cordin@disid.com">Cèsar Ordiñana</a>
 */
public class CompatLibrary extends BaseLibrary {
    protected void doInitialize() {
    }
    protected void doPostInitialize() {
        super.postInitialize();
        // Validate there is any implementation registered.
        StringUtils stringUtils = CompatLocator.getStringUtils();
        if (stringUtils == null) {
            throw new ReferenceNotRegisteredException(CompatLocator.STRINGUTILS_NAME,
                CompatLocator.getInstance());
        }
    }
}

Nota

Como norma general, al emplear el mecanismo de inicialización de librerías de libTools deberemos seguir un par de normas básica para no tener problemas de orden y dependencias en la inicialización:

• El registro de implementaciones en los Locator se hará siempre en el método doInitialize().
• El acceso a referencias a través de algún Locator en un Library, se hará siempre en el método doPostInitialize().

Con esto nos aseguraremos que, siempre que se acceda a una referencia a través de un Locator, se habrá registrado la implementación correspondiente.

Tests Unitarios

Dado que con el uso de los Locator estamos reforzando el uso de interfaces, y la separación de implementaciones alternativas u opcionales, podemos aprovechar esto a la hora de realizar los tests unitarios.

La forma de aprovecharlo consiste en crear los tests unitarios que comprueben el funcionamiento correcto a nivel de API, dentro del proyecto que incluya la definición de los interfaces. Dichos tests pueden crearse como clases abstractas, que definan métodos para crear los objetos que implementan los interfaces a probar. Así, cada implementación particular podrá crear sus tests unitarios, simplemente heredando de los tests del API, e implementando el método de creación de sus clases propias.

Con esta estructura de tests unitarios podemos definir los tests unitarios a nivel de API, y lanzarlos de forma sencilla para cada implementación.

Basándonos en el ejemplo anterior, la distribución de tests unitarios quedaría de la siguiente forma en las tres librerías del ejemplo:

libCompat:

public abstract class StringUtilsTestAbstract extends TestCase {

    private StringUtils utils;

    protected void setUp() throws Exception {
        super.setUp();
        utils = createUtils();
    }

    protected abstract StringUtils createUtils();

    public void testReplaceAll() {
        String testString = "En un lugar de la Mancha";
        String resultString = "En_un_lugar_de_la_Mancha";
        String regex = " ";
        String replacement = "_";

        assertEquals(resultString, 
            utils.replaceAll(testString, regex, replacement));
    }

}

libCompatSE:

public class StandardStringUtilsTest extends StringUtilsTestAbstract {
    protected StringUtils createUtils() {
        return new StandardStringUtils();
    }
}

libCompatME:

public class MobileStringUtilsTest extends StringUtilsTestAbstract {
    protected StringUtils createUtils() {
        return new MobileStringUtils();
    }
}

Notas adicionales

• Las excepciones del Locator y del Library son de tipo RuntimeException por lo que, aunque declaradas en su API, no obligan a ser capturadas mediante un try ... catch. A nivel de aplicación, si que habrá que hacer un tratamiento de estas excepciones, para mostrar al usuario algún tipo de información sobre el error producido.

  No se han definido excepciones normales, ya que son errores graves y no se puedan tratar desde código. Así no obligamos a capturarlas en cada lugar dónde se use un Locator o Library, y se pueden tratar en un nivel superior.

org.gvsig.fortunecookie.lib.api

Para definir el API crearemos básicamente dos interfaces, FortuneCookieManager y FortuneCookieService.

• FortuneCookieManager. Presenta un interface simple que se encarga de instanciar un FortuneCookieService, y devolvérselo al cliente para que trabaje con él.

  Además de hacer de factoría, podría llevar la gestión de configuración general de la librería.

• FortuneCookieService. Define el API a usar para obtener un fortune cookie. En nuestro ejemplo sólo vamos a tener un método: getMessage.

public interface FortuneCookieManager {

  public FortuneCookieService getFortuneCookieService();
  
}

public interface FortuneCookieService {

  public String getMessage();
  
}

Además de esto deberemos tener en cuenta el manejo de excepciones, así como la creación del locator y library correspondiente para poder acceder a estos servicios. Así tendremos:

• FortuneCookieLibrary. Extenderá la clase AbtractLibrary e implementará los métodos "do*", normalmente dejándolos vacíos. En la parte del API el library en general no realiza ninguna operación.
• FortuneCookieLocator. Derivará de la clase AbstractLocator e implementará lo necesario para poder recuperar una implementación del FortuneCookieManager que esté disponible. Consulte la documentación sobre el locator para más informacion sobre él.

La compilación de este proyecto nos generará una librería org.gvsig.fortunecookie.lib.api.jar (falta el número de versión), que contendrá la definición del API de nuestro desarrollo. Esta librería es la que necesitarán nuestros proyectos en tiempo de compilación para acceder a nuestro servicio. Recordad que trabajando con maven podemos especificar dependencias indicando si son de tiempo de compilación, ejecución o testing.

org.gvsig.fortunecookie.lib.impl

Por otro lado tendremos el proyecto en el que residirá la implementación de nuestro API. Siguiendo las recomendaciones en el nombrado de clases para gvSIG 2.0, nos encontraremos con las clases:

• DefaultFortuneCookieManager. Esta clase implementará el interface FortuneCookieManager, encargándose de la creación de las instancias de nuestro FortuneCookieService.
• DefaultFortuneCookieService. Esta es la clase que contendrá la lógica usada para conseguir los mensajes de nuestras fortune cookie.

public class DefaultFortuneCookieManager implements FortuneCookieManager {

  public FortuneCookieService getFortuneCookieService() {
    return new DefaultFortuneCookieService(this);
  }

}

public class DefaultFortuneCookieService implements FortuneCookieService {

  private DefaultFortuneCookieManager manager;
  private String msg;
  
  public DefaultFortuneCookieService(DefaultFortuneCookieManager manager) {
    this.manager = manager;
    this.msg = null;
  }
  
  public String getMessage() {
  
    if( this.msg != null ) {
      return this.msg;
    }
    ...
    //Here we would generate the message
    ...
    return this.msg;
  }

}

Y al igual que en el proyecto del API aquí tendríamos el library correspondiente, que se encargaría de registrar la implementación de nuestro manager para que pudiese ser recuperada por el locator del API.

Hay que tener en cuenta que el manager actúa a modo de singleton, de forma que una vez recuperada una instancia de él siempre nos devolverá la misma instancia, siendo global a la aplicación que consuma nuestro servicio. Esto, en el ejemplo de nuestras fortune cookies, no tiene especial relevancia, pero en otros escenarios más complejos puede llegar a tenerla.

La compilación de este proyecto nos generará una librería org.gvsig.fortunecookie.lib.impl.jar con una implementación de nuestro API. Conviene recordar que las dependencias entre estos dos proyectos, API e implementación, son, que la implementación depende del API pero nunca al revés.

Conclusión

Como conclusión conviene observar que las utilidades de org.gvsig.tools.service no nos han ofrecido ningún mecanismo especial para llevar a cabo nuestro proyecto. Al final han sido una serie de prácticas recomendadas lo único que hemos aplicado. Esto en gran parte debido a que el escenario de API mas una implementación en bloque de la lógica de ese API no requiere de más infraestructura.

Esquema general

El siguiente diagrama nos muestra las relaciones de estos interfaces y clases con nuestro escenario de fortune cookie.

Esquema general de clases de FortuneCookie.

org.gvsig.fortunecookie.lib.api

En este proyecto nos encontraremos con la parte de API de nuestra librería.

Tendremos:

• FortuneCookieManager
• FortuneCookieService.
• FortuneCookieLocator
• FortuneCookieLibrary

Esta parte básicamente sigue presentando un aspecto similar al del ejemplo simple. Si lo pensamos tiene su lógica, ya que se identifica con los servicios que ofrece nuestra librería y estos deberían ser independientes de como estén implementados.

org.gvsig.fortunecookie.lib.spi

El SPI constituye el contrato que ofrece nuestra librería hacia sus proveedores de servicios, así que como tal es similar a la definición del API. Estará constituido principalmente por una serie de interfaces y ocAsíonalmente alguna clase abstract que facilite la implementación de un proveedor.

Nos encontraremos con:

• FortuneCookieProvider. Se tratará del interface que deben cumplir los proveedores de servicios que usará nuestra librería.

• FortuneCookieProviderServices. Representa a los servicios adicionales que debe proveer nuestro FortuneCookieService de cara a un proveedor. Hay que tener en cuenta que los proveedores no deben tener acceso a la implementación de la librería. Al igual que un cliente de ésta sólo tendrá acceso a su API un proveedor sólo tendrá acceso a su SPI, así que, si debemos proveer de algún servicio a nuestro proveedor deberemos exponerlo a través de esta interface.

• FortuneCookieProviderFactory. Por cada tipo de proveedor que tenga nuestra librería necesitaremos una factoría que nos proporcione instancias de ese tipo de proveedores, así que parece razonable que exista un interface que nos proporcione el contrato que deban cumplir esas factorías.

  Normalmente, no deberemos preocuparnos por este interface, ya que la librería provee del interface ProviderFactory que nos suministrará todos los servicios que precisemos relacionados con la factoría de proveedores.

• FortuneCookieProviderManager. Necesitaremos mantener un registro de las factorías de proveedores con las que vamos a trabajar, así que crearemos un manager específico para gestionar todo lo que tenga que ver con nuestros proveedores.

org.gvsig.fortunecookie.lib.impl

Ahora veamos que nos quedará en la parte de implementación:

• DefaultFortuneCookieManager, similar al que ya teníamos en nuestro escenario simple sin proveedores.

  La principal diferencia con respecto al del escenario anterior estará en que este necesita gestionar proveedores, así que simplemente tendrá una referencia al FortuneCookieProviderManager y algún método para recuperarla.

• DefaultFortuneCookieProviderManager, que tendrá la implementación por defecto del manager encargado de la gestión de nuestros proveedores de servicios.

• DefaultFortuneCookieService, que al igual que en el escenario simple presentará la implementación del servicio que ofrece nuestra librería a sus clientes. La principal diferencia respecto la anterior versión estará en que para alguna de sus funciones, en lugar de implementarlas directamente, delegará en un proveedor que le será suministrado en el momento de su contrucción.

• DefaultFortuneCookieProviderServices. Esta clase implementará los servicios que nuestra librería expone hacia los proveedores de esta.

• DefaultFortuneCookieLibrary, que al igual que en nuestro escenario simple, se encargará de registrar esta implementación.

org.gvsig.fortunecookie.lib.prov.web

Por ultimo deberemos disponer de alguna implementación de un proveedor de servicios de nuestra librería. En nuestro ejemplo, nos encontraremos:

• FortuneCookieWebProvider, que nos brindará los servicios de obtención de nuestras fortune cookies obteniéndolas a través de un servicio web.
• FortuneCookieWebProviderFactory, que será la implementación de la factoría para la construcción de FortuneCookieWebProvider.
• FortuneCookieWebLibrary, que se encargará de registrar este proveedor como un proveedor de servicios de nuestra librería.

Y por cada proveedor de servicios de nuestra librería aparecería su implementación, su factory y su library, habiendo tantos como proveedores de servicios distintos tengamos.

Esquema general

Así como en el caso del escenario simple, en el que solo tenemos un API y su implementación la librería org.gvsig.tools no nos ofrecía utilidades para su implementación debido a la simplicidad de este, en el caso de que hayan proveedores de servicios de nuestra librería sí que nos ofrece todo un entorno de trabajo para facilitarnos la tarea. Encontraremos interfaces de los que extender en nuestra definición del API y SPI, y clases abstractas que extender a la hora de contruir nuestra implementación o nuestros proveedores, librándonos de las faenas de registro de los proveedores, o de recuperar instancias de estos cuando los precisemos.

El siguiente diagrama nos muestra las relaciones de estos interfaces y clases con nuestro escenario de fortune cookie.

Esquema general de clases de FortuneCookie.

En el esquema podemos observar ocho bloques bien diferenciados. Cuatro con los interfaces y clases que ofrece org.gvsig.tools.service y otros cuatro que deberá aportar nuestro desarrollo.

Los siguientes bloques los aporta org.gvsig.tools.service para facilitarnos nuestro desarrollo y homogeneizar la implementación de este escenario:

• General API. Este bloque contiene los interfaces que nos ayudaran a definir el API de nuestro desarrollo.
• General SPI. Aquí encontraremos los interfaces que nos facilitarán el definir el SPI de nuestro producto.
• General API impl. Nos aporta una serie de clases abtractas de cara a ser extendidas por la implementación de nuestra librería para definir el API de esta.
• General SPI impl. Nos aporta una serie de clases abtractas de cara a ser extendidas por la implementación de nuestra librería para definir el SPI de esta.

Los otros cuatro bloques representan código que deberemos aportar en nuestra librería. Estos serían:

• Domain specific API. En nuestro ejemplo sería org.gvsig.fortunecookie.lib.api, y estaría formado por los interfaces que definen el API de nuestra librería.
• Domain specific SPI. Aqui tendríamos la parte de definición del SPI de nuestra librería. Estaría relacionado con el código que encontraríamos en org.gvsig.fortunecookie.lib.api.
• Default implementación. Estaría formado por la implementación de la lógica de nuestra librería.
• Concrete provider. Representa las clases que habría que crear para disponer de un proveedor de datos para nuestra librería.

Parámetros de un proveedor de servicios

Entes de pasar a resumir los pasos que deberíamos dar para implementar este tipo de escenario, comentaremos algo sobre la construcción de los proveedores de servicios de nuestra librería.

Normalmente cada proveedor de servicios, aunque exponga un contrato común a todos los proveedores de servicios hacia nuestra implementación, precisará de una serie de parámetros diferentes para cada proveedor. Así, siguiendo con nuestro ejemplo, FortuneCookieWebProvider podría precisar de la url de acceso al servicio web que nos proporcione los distintos mensajes, pero podríamos disponer de otro proveedor, FortuneCookieDBProvider, que fuese a buscar los mensajes a una BBDD, y entre sus parámetros precise una cadena de conexión a la BBDD y un nombre de tabla de la que extraer los mensajes. Y también podríamos disponer de FortuneCookieXMLFileProvider que recibiese la ruta de un fichero XML.

Básicamente cada proveedor, ofrece un interface común a nuestra aplicación, getMessage, pero precisa de unos parámetros particulares para su creación.

Para uniformizar esto, la factoría del proveedor dispondrá un método que nos devuelva un DynObject en el que depositar estos parámetros y que luego utilizará el proveedor para poder trabajar.

Así un cliente de nuestra librería, para empezar a trabajar con un servicio de los que ofrezca nuestro desarrollo, lo primero que tendrá que hacer es pedirle al FortuneCookieManager que le dé un DynObject en el que almacenar los parámetros del proveedor con el que vayamos a trabajar a traves del método getProviderParameters(String providerName), para luego invocar a getFortuneCookieService pasándole esos parámetros.

Contruyendo nuestro proyecto paso a paso

A través de este apartado se irán enumerando las directrices a seguir para poder generar nuestro proyecto y comenzar el desarrollo.

En un primer paso, deberemos preparar el sistema de directorios para poder albergar el proyecto. Para ello, realizaremos las siguientes tareas:

1. Crear el directorio raíz que contendrá el proyecto. Siguiendo con la nomenclatura descrita hasta el momento, el proyecto deberá comenzar con org.gvsig. más el nombre del proyecto (en nuestro caso org.gvsig.fortunecookies).

2. Crear el subdirectorio LIB dentro del directorio raíz (en nuestro caso sería org.gvsig.fortunecookies.lib)

3. Creamos y editamos el fichero POM en org.gvsig.fortunecookies

   • Añadimos el módulo LIB como hijo del directorio raíz, para que lo incluya en el proyecto

4. Creamos el proyecto API (org.gvsig.fortunecookies.lib.api) en org.gvsig.fortunecookies/org.gvsig.fortunecookies.lib

   • Abrimos la consola y nos dirigimos al directorio en el que queremos generar el proyecto (org.gvsig.fortunecookies/org.gvsig.fortunecookies.lib).
   • Ejecutamos la orden de Maven ->

   mvn  archetype:generate   \ 
   -DarchetypeGroupId=org.gvsig   \ 
   -DarchetypeArtifactId=org.gvsig.library-archetype \ 
   -DgroupId=org.gvsig   \ 
   -DartifactId=org.gvsig.fortunecookies.lib.api   \ 
   -Dversion=1.0   \ 
   -Dpackage=org.gvsig.fortunecookies.lib.api
   

   • Indicamos como arquetipo la opción 17 y confirmamos la opción indicando Yes (valores por defecto)

5. Creamos y editamos el fichero POM en org.gvsig.fortunecookies/org.gvsig.fortunecookies.lib

   • Especificamos el módulo padre
   • Añadimos el módulo API como hijo del directorio org.gvsig.fortunecookies.lib, para que lo incluya en el proyecto

6. Editamos el fichero POM de org.gvsig.fortunecookies/org.gvsig.fortunecookies.lib/org.gvsig.fortunecookies.lib.api

   • Especificamos que el módulo padre es org.gvsig.fortunecookies.lib

7. A través de la consola nos dirigimos al directorio raíz y lanzamos la orden Maven -> mvn eclipse:eclipse. Debiendo obtener una respuesta que muestre el correcto establecimiento de las dependencias entre los 3 módulos implicados

8. Repetir desde el paso 4 realizado para generar el proyecto org.gvsig.fortunecookies.lib.api para crear org.gvsig.fortunecookies.lib.spi (si se requiere) y org.gvsig.fortunecookies.lib.impl.

9. Si vamos a tener SPI, requeriremos de un provider que nos suministre los datos que necesitemos. Para ello, generaremos un paquete como org.gvsig.fortunecookies.lib creado en el punto 2 (que en este caso llamaremos org.gvsig.fortunecookies.prov), y añadiremos tantos providers como la aplicación utilice (en caso de tener varias fuentes de datos diferentes), que en nuestro caso se llamarán org.gvsig.fortunecookies.prov.webprovider y org.gvsig.fortunecookies.prov.fileprovider (la creación de éstos será igual que la de org.gvsig.fortunecookies.lib.api).

En este punto ya tenemos preparado nuestro proyecto para empezar a centrarnos en el desarrollo. En este segundo paso, tras configurar nuestro workspace con Eclipse, comenzaremos con la implementación del proyecto.

public interface FortuneCookieService extends Service{

    public String getMessage() throws FortuneCookieMessageException;
}

public interface FortuneCookieManager extends Manager {

        public DynObject createServiceParameters(String serviceName) throws ServiceException;
        }

org.gvsig.fortunecookies.FortuneCookieLibrary

public interface FortuneCookieProvider {

                public String getMessage() throws Exception;
        }

public interface FortuneCookieProviderServices extends ProviderServices{

        public DynObject getParameters();
}

public class DefaultFortuneCookieService extends AbstractService implements FortuneCookie{
        private String message;
        private DefaultFortuneCookieManager manager;

        public DefaultFortuneCookieService(DefaultFortuneCookieManager manager, DynObject parameters,
                ProviderServices providerServices) throws ServiceException {
                this.manager = manager;
                this.message = null;
                super.init(parameters, providerServices);
        }

        /*
         * (non-Javadoc)
         * @see org.gvsig.tools.service.Service#getProviderManager()
         * 
         * This method must be implemented in all Services
         */
        protected ProviderManager getProviderManager() {
                return this.manager.getProviderManager();
        }

        /*
         * (non-Javadoc)
         * @see org.gvsig.tools.service.Service#getManager()
         * 
         * This method must be implemented in all Services
         */
        public Manager getManager() {
                return this.manager;
        }

        public String getMessage() throws FortuneCookieMessageException {
                if(message==null){
                        FortuneCookieProvider provider = (FortuneCookieProvider)this.getProvider();
                        try {
                                this.message = provider.getMessage();
                        } catch (Exception e) {
                                throw new FortuneCookieMessageException(e);
                        }
                }
                return this.message;
        }

}

public class DefaultFortuneCookieManager extends AbstractManager implements FortuneCookieManager {

        public DefaultFortuneCookieManager() {
                super(new DefaultProviderManager());
        }

        /*
         * (non-Javadoc)
         * @see org.gvsig.tools.service.Manager#getService(org.gvsig.tools.dynobject.DynObject)
         * 
         * This method must be implemented in all Managers
         */
        public Service getService(DynObject parameters) throws ServiceException {
                DefaultFortuneCookieProviderServices providerServices = new DefaultFortuneCookieProviderServices();
                DefaultFortuneCookie cookie = new DefaultFortuneCookie(this, parameters , providerServices);
                return cookie;
        }
}

public class DefaultFortuneCookieProviderServices extends AbstractProviderServices{
}

public class FortuneCookieDefaultImplLibrary extends AbstractLibrary{

                     protected void doInitialize() throws LibraryException {
                             FortuneCookieLocator.registerManager(DefaultFortuneCookieManager.class);
                     }

                     protected void doPostInitialize() throws LibraryException {
                     }
      }

org.gvsig.fortunecookies.impl.FortuneCookieDefaultImplLibrary

public class FortuneCookieFileProviderLibrary extends AbstractLibrary{

              protected void doInitialize() throws LibraryException {
              }

              protected void doPostInitialize() throws LibraryException {
                      ProviderManager mgr = (ProviderManager) FortuneCookieLocator.getManager();
                      mgr.addProviderFactory(new FortuneCookieProviderFactory());
              }
}

      public class FortuneCookieProviderFactory implements ProviderFactory{
                    public static final String PROVIDER_NAME = "Provider";
                    public static final String PROVIDER_NAME_PARAMS = "FortuneCookieParams";
                    public static final String PROVIDER_NAME_PARAMS_DESCRIPTION = "";

                    private DynClass dynclass;

                    public Provider create(DynObject parameters, ProviderServices services) throws ServiceException {
                            return new FortuneCookieProvider(services);
                    }

                    public DynObject createParameters() {
                            DynObject dynobject = ToolsLocator.getDynObjectManager().createDynObject(dynclass);
                            ...
                            //Here allocate the necessary parameters
                            ...
                            return dynobject;
                    }

                    public String getName() {
                            return PROVIDER_NAME;
                    }

                    public void initialize() {
                            dynclass = ToolsLocator.getDynObjectManager().createDynClass(PROVIDER_NAME_PARAMS, PROVIDER_NAME_PARAMS_DESCRIPTION);
                            ...
                            //Here allocate the necessary parameters
                            ...
                    }
}

      public class DefaultFortuneCookieProvider extends AbstractProvider implements FortuneCookieProvider{

              public String getMessage() throws Exception {
                      ...
                      //Here would define the method to get the message
                      ...
              }
}

org.gvsig.fortunecookie.swing.api

Al igual que en la librería, en este API se definen el conjunto de operaciones o servicios que ofrecen las interfaces de usuario (en este caso sólo está el JFortuneCookiePanel, aunque podrían haber más). Dentro de este paquete tendremos los siguientes componentes:

• JFortuneCookiePanel. Desarrolla el API del panel principal que se mostrará con la información de una instancia de FortuneCookieService. Entre los servicios que podemos requerir será el de getFortuneCookie que nos devuelve la instancia de FortuneCookieService que está representada en ese JPanel.

  En general se tratara de una clase abstract que extiende a JPanel sin aportarle nada mas que metodos abstractos. Siguiendo las mismas pautas que se han seguido en la parte de logica deberia ser un interface que extendiese al interface de swing del JPanel, pero como no disponemos de ese interface en swing lo simularemos creando ka clase abstract.

• FortuneCookieUIManager. Se encarga de instanciar los distintos interfaces de usuario, y devolvérselos al cliente para que trabaje con ellos. Además de hacer de factoría.

  Dispondra de metodos como getJFortuneCookiePanel que nos devolveran una instancia de JFortuneCookiePanel.

• FortuneCookieSwingLocator. Al igual que en el Locator del Library (FortuneCookieLocator), derivará de la clase AbstractLocator e implementará lo necesario para poder recuperar una implementación del FortuneCookieSwingManager que esté disponible.

• FortuneCookieSwingLibrary. Extenderá la clase AbtractLibrary e implementará los métodos "do*", normalmente dejándolos vacíos. En la parte del API (al igual que ocurría con el FortuneCookieLibrary), no realiza ninguna operación.

org.gvsig.fortunecookie.swing.impl

Presenta la lógica que desarrolla la funcionalidad de las operaciones que nos proporciona el API.

• DefaultJFortuneCookiePanel. Extendera de JFortuneCookiePanel y aportara la implementacion del panel que nos muestra un FortuneCookieServices.
• DefaultFortuneCookieUIManager. Esta clase implementará el interface FortuneCookieUIManager, encargándose de la creación de las instancias de nuestros interfaces JFortuneCookiePanel.
• DefaultFortuneCookieSwingImplLibrary. Al igual que en el proyecto del API aquí tendríamos este library, que se encargaría de registrar la implementación de nuestro manager para que pudiese ser recuperada por el Locator del API de esta parte de Swing.

La compilación de este proyecto nos generará una librería org.gvsig.fortunecookie.lib.api.jar y org.gvsig.fortunecookie.lib.impl.jar (faltará el número de versión, que forma parte de cada uno de los nombres)

Aunque aqui hemos usado JPanel como clase base para los componentes base que ofrece nuestra libreria, puede darse el caso de que en lugar de JPanel sea mas conveniente usar otro componente de swing como base de los nuestro, y asi Usar por ejemplo un JComponent o uno mas concreto como el JEditPane. Cuando decidamos usar componentes concretos de swing deberemos tener en cuenta que vamos a exponer el componente entero como parte del API de nuestra libreria, de forma que el cambio de este en futuras implementaciones causara una perdida de compativilidad importante. Solo deberiamos usar un comppnente de swing concreto cuando este claro que este forma parte del API que vamos a exponer y no como un efecto secundario de la implementacion que aportamos.