Editor de esquemas de punto de extensión

El editor de esquemas de punto de extensión se puede abrir de dos formas: como producto secundario obtenido al crear un punto de extensión nuevo o abriendo un esquema de punto de extensión existente. Por convenio, los esquemas nuevos tienen un nombre formado por el ID del punto de extensión y la extensión de archivo .exsd. Se colocan en el directorio schema del árbol de directorios del conector.   

Cuando se crea un punto de extensión nuevo en el PDE, también se creará el archivo de esquema inicial y se abrirá el editor de esquemas para editarlo. Puede elegir entre definir el esquema en ese momento o cerrar el editor y definirlo más adelante. Si se elabora un esquema completo del punto de extensión, el PDE podrá ofrecer ayuda automatizada a los usuarios del punto de extensión.

El editor de esquemas del PDE se basa en los mismos conceptos que el editor de manifiestos de conectores. Tiene dos páginas de formulario y una página del fuente. Puesto que el esquema XML es verboso y puede ser difícil de leer en su formato fuente, deberá utilizar las páginas de formulario para la mayoría de las tareas de edición. La página del fuente resulta de utilidad para leer el código fuente resultante.  

Ejemplo: crear un esquema para el punto de extensión "Analizadores de ejemplo"

Anteriormente hemos creado el punto de extensión "Analizadores de ejemplo" y el esquema inicial. Ahora podemos abrir el esquema yendo a la carpeta schema del proyecto y pulsando dos veces el archivo parsers.exsd. Así se abrirá el editor de esquemas.  

Lo que queremos hacer es:

  1. Definir los elementos y los atributos XML válidos para el punto de extensión.
  2. Definir la gramática (modelo del contenido).
  3. Proporcionar fragmentos de código de documentación que se fusionarán en un documento de consulta.

Cada esquema de punto de extensión empieza por una declaración del elemento "extension". Añadiremos un elemento XML nuevo llamado "parser".  

  1. Pulse el botón Elemento nuevo de la sección Elementos de puntos de extensión.
  2. Vaya a la vista Propiedades y cambie el nombre "New_Element" por "parser".
  3. Teniendo todavía seleccionado el elemento nuevo, pulse el botón Atributo nuevo. Así se creará el elemento hijo "new_attribute". En la hoja de propiedades, cambie la propiedad name por "id" y la propiedad use por "required".
  4. Todavía en la hoja de propiedades, pulse el botón "Clonar este atributo", disponible en la barra de herramientas local. Se creará una copia del atributo. Esto resulta de utilidad porque nos permite definir rápidamente todos los atributos sin tener que dejar la hoja de propiedades.  
  5. Cambie el nombre del atributo nuevo por "name".
  6. Vuelva a clonar el atributo. Esta vez, cambie el nombre por "class". Este atributo se utilizará para representar un nombre totalmente calificado de la clase Java que debe implementar una interfaz Java concreta. Debemos especificarlo para que más adelante el PDE pueda aprovecharse de ello. Cambie kind, para que de "string" pase a ser "java". Establezca la propiedad basedOn en com.example.xyz.IParser. (Esta interfaz todavía no existe, pero la crearemos más adelante). 

En este momento, el editor de esquemas debe parecerse al de esta figura:

Editor de esquema de puntos de extensión - Página Definición

Ahora añadiremos un atributo adicional que toma valores a partir de una lista discreta de opciones. Esto significa que necesitaremos crear una restricción de enumeración del tipo string base. Además, estableceremos un valor por omisión para el atributo.  

  1. Teniendo seleccionado el elemento "parser", pulse el botón Atributo nuevo. En la hoja de propiedades, cambie su nombre por "mode".
  2. Pulse en la casilla del valor de la propiedad "restriction" para que se abra diálogo de restricciones.  
  3. Cambie el tipo de restricción "none" por "enumeration".
  4. Añada las tres opciones siguientes: "never", "always" y "manual" (estas son nuestras tres modalidades hipotéticas para la extensión del analizador).

El diálogo debe tener este aspecto:

Diálogo de restricción de tipos

Cuando se cierre el diálogo, cambie el atributo "use" por "default" y el atributo "value" por "always". Así se establece el valor por omisión. Observe que, mientras teclea el valor, la línea de estado muestra un mensaje de error, porque existe la restricción de que los valores válidos solo sean las tres opciones de enumeración. Cuando haya acabado de teclear el valor, el mensaje de error debe desaparecer porque "always" es uno de los valores válidos.

Ahora que ya hemos definido todos los elementos y atributos, tendremos que definir una gramática. Nuestro objetivo es definir que el elemento "extension" pueda tener cualquier número de elementos "parser" a modo de hijos.  

  1. Seleccione el elemento "extension". El correspondiente modelo de contenido inicial muestra un compositor de secuencia vacío.
  2. Seleccione el compositor de secuencia y pulse Nuevo->Consulta->parser en el menú emergente. Así se añadirá la consulta de parser (analizador) al compositor de secuencia.
  3. La cardinalidad por omisión de las consultas es [1,1], lo que significa que no puede haber más que un elemento "parser". Esto no es exactamente lo que queríamos. Seleccionamos la referencia "parser" y cambiamos la propiedad maxOccurs por "unbounded".

Después de definir la gramática, el enfoque de DTD, más abajo de la sección de gramática, muestra a qué se parecería la gramática del elemento seleccionado en la DTD. Esta información se da para ayudar a los desarrolladores que siguen sintiéndose más cómodos con las DTD que con los esquemas XML.

Editor de esquemas de puntos de extensión - gramática del elemento

Ahora que ya hemos definido elementos, atributos y una gramática válidos, necesitamos proporcionar alguna información sobre el punto de extensión. Hay dos tipos de fragmentos de código de la documentación de esquema:

El primer tipo de fragmento de código se proporciona en la página Definición del manifiesto del esquema. A medida que vaya seleccionando elementos y atributos, podrá ir añadiendo textos cortos acerca de ellos en la sección "Descripción". El formato previsto es HTML sin procesar (como con Javadoc) y el texto se copiará tal cual en el documento de consulta final.

  1. Seleccione el atributo "id" del elemento "parser" y escriba lo siguiente en el editor de descripciones:
    nombre exclusivo que se utilizará para hacer referencia a este analizador.
  2. Seleccione el atributo "name" y añada el texto siguiente:
    nombre traducible que se utilizará para presentar este analizador en la UI.
  3. Seleccione el atributo "class" y añada el texto siguiente (fíjese en los códigos HTML):
    nombre totalmente calificado de la clase Java que implementa la interfaz <samp>com.example.xyz.IParser</samp>.
  4. Seleccione el atributo "mode" y añada esto:
    distintivo opcional que indica con qué frecuencia se ejecutará esta instancia de analizador (el valor por omisión es <samp>always</samp>).

Ahora tenemos que proporcionar una descripción corta del propio punto de extensión. Para ello, pasaremos a la página Documentación:

  1. Elija "Visión general" en el cuadro combinado que hay más arriba del editor de texto y añada el texto siguiente:
    Este punto de extensión sirve para conectar analizadores adicionales. En realidad, los analizadores no funcionan: se han utilizando simplemente como ejemplo de esquema de puntos de extensión.
    Pulse Aplicar.
  2. Elija "Ejemplos" en el cuadro combinado y añada este texto:
       El siguiente es un ejemplo de utilización del punto de extensión:
       <p>
       <pre>
          <extension point="com.example.xyz.parsers">
          <parser
             id="com.example.xyz.parser1"
             name="Analizador de ejemplo 1"
             class="com.example.xyz.SampleParser1">
          </parser>
    </extension>
       </pre>
       </p>
    

    Pulse Aplicar.

  3. Seleccione "Información sobre la API" y añada el texto siguiente:
    Los conectores que pretendan ampliar este punto de extensión deben implementar la interfaz <samp>com.example.xyz.IParser</samp>.
    Pulse Aplicar.
  4. Seleccione "Implementación suministrada" y añada el texto siguiente:
    El conector XYZ proporciona la implementación por omisión del analizador.
    Pulse Aplicar.
Nota: deben tenerse en cuenta consideraciones especiales a la hora de proporcionar ejemplos. Por lo general, el PDE tratará el texto proporcionado como HTML sin procesar y no respetará los caracteres de nueva línea ni los espacios en blanco formados por más de un carácter (es decir, espacios en blanco que pueden despreciarse). Esto es lo que cabe esperar en lo que se refiere al texto normal, pero es extraordinariamente molesto cuando se proporcionan ejemplos en los que las tabulaciones y la alineación vertical son significativas para que el ejemplo tenga buen aspecto. El PDE tiene una solución de compromiso para esta situación: si detecta el código HTML <pre>, tomará el contenido tal cual (conservando todos los caracteres sin realizar ninguna modificación) hasta encontrarse con el código de cierre </pre>. Esta es la razón por la que podemos proporcionar un ejemplo como el anterior y confiar en que el documento de consulta final tendrá buen aspecto.

Quizás ya haya observado que, a medida que escribe la documentación, cada vez es mayor el número de elementos que quedan recubiertos con la imagen de un "lápiz" en la vista Esquema del editor. Este pequeño indicador quiere decir que el elemento en cuestión tiene texto asociado (una forma rápida de comprobar si a la documentación le falta algo en algún lugar del documento).

Esquema del editor de esquemas de puntos de extensión

Una vez acabada la documentación, podemos echar una ojeada a los documentos de consulta. Puede hacerlo de dos formas. Mientras trabaja, en todo momento puede obtener una vista previa del documento de consulta si selecciona el elemento Vista previa del documento de consulta, en el menú emergente. Otra posibilidad es configurar las preferencias del PDE (Preferencias>Desarrollo de conectores>Compiladores, en la pestaña Esquema) para crear automáticamente documentación de consulta cada vez que se produzca un cambio en el archivo de esquema. Sea cual sea el procedimiento que siga para crearlo, el documento resultante de este ejemplo tendría este aspecto.

 
Copyright IBM Corporation y otras empresas 2000, 2003