Editor de esquemas de punto de extensión

El editor de esquemas de puntos de extensión puede abrirse de dos formas: como subproducto de la creación de un punto de extensión nuevo o abriendo un esquema de punto de extensión existente.  Por convenio, los esquemas nuevos tienen el mismo nombre que el id del punto de extensión con la extensión de archivo .xsd. Se colocan en el directorio schema del árbol de directorios del conector.  

Cuando en el PDE se crea un punto de extensión nuevo, también se creará el archivo de esquemas inicial y el editor de esquemas se abrirá para editarlo. El esquema puede definirse entonces, o puede cerrarse el editor y definirlo más tarde. Crear un esquema de punto de extensión completo permite que el PDE ofrezca 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 fuente.  Puesto que el esquema de XML es prolijo y puede ser difícil de leer en su formato fuente, debería utilizar las páginas de formulario para casi todas las tareas de edición.  La página fuente es útil 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 efectuando una pulsación doble en el archivo parsers.xsd.  Esto abrirá el editor de esquemas.

Lo que queremos hacer es:

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

Cada esquema de punto de extensión se inicia con una declaración del elemento "extension".  Añadiremos un elemento de XML nuevo llamado "analizador".

  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 su nombre de "Elemento_nuevo" a "analizador"
  3. Con el elemento nuevo seleccionado, pulse el botón Atributo nuevo. Esto creará "atributo_nuevo" como su hijo. En la hoja de propiedades cambie su nombre por "id" y use por "required".
  4. Estando en la hoja de propiedades, pulse el botón "Replicar este atributo", disponible en la barra de herramientas local. Esto creará una copia del atributo.  Esto es útil porque nos permite definir rápidamente todos los atributos sin tener que dejar la hoja de propiedades.
  5. Cambie el nombre del atributo nuevo en "nombre."
  6. Vuelva a replicar el atributo. Esta vez, cambie el nombre a "clase."  Este atributo se utilizará para representar un nombre totalmente calificado de la clase de Java que debe implementar una interfaz de Java determinada. Esto debe especificarse para que más tarde el PDE pueda aprovecharse de ello. Cambie tipo de "string" a "java."  Establezca la propiedad basedOn como com.example.xyz.IParser.  (Esta interfaz todavía no existe, pero la crearemos más adelante).

Hasta ahora, el editor de esquemas debería parecerse a este:

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

  1. Con el elemento "analizador" seleccionado, pulse   el botón Atributo nuevo. Cambie su nombre en la hoja de propiedades por "modalidad".

  2. Pulse en la celda valor de la propiedad "restricción" y aparecerá el cuadro de diálogo de restricciones. 

  3. Cambie el tipo de restricción de "ninguna" a "enumeración."

  4. Añada las tres opciones siguientes: "nunca", "siempre" y "manual."  (Estas son nuestras tres modalidades hipotéticas para la ampliación del analizador).

El cuadro de diálogo debería tener este aspecto:

Cuando se cierra el cuadro de diálogo, cambie el atributo "use" a "default" y el atributo "valor" a "siempre".  Esto establece el valor por omisión.  Observe que la línea de estado muestra un mensaje de error mientras se escribe el valor, puesto que restringe los valores válidos a las tres opciones de enumeración. Después de escribir el valor, el mensaje de error debería desaparecer porque "siempre" es un valor válido.

Ahora que ya hemos definido todos los elementos y atributos, necesitamos definir una gramática. Nuestro objetivo es definir que el elemento "ampliación" pueda tener como hijos cualquier número de elementos "analizador". 

  1. Seleccione el elemento "ampliación". Su modelo de contenido inicial muestra un compositor de secuencia vacío.

  2. Seleccione el compositor de secuencia y seleccione Nuevo->Consulta->analizador del menú emergente. Esto añadirá la consulta de analizador al compositor de secuencia.

  3. La cardinalidad por omisión de las consultas es [1,1] lo que significa que puede haber exactamente un elemento "analizador". Esto no es exactamente lo que queremos. Seleccionamos la consulta "analizador" y cambiamos la propiedad minOccurs en la hoja de propiedades a 0, y maxOccurs a "unbounded."

Tras definir la gramática, la aproximación de DTD bajo la sección de la gramática muestra a qué se parecería la gramática del elemento seleccionado en 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 de XML.

Ahora que se han 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 documentación de esquema:

El primer tipo de fragmento se proporciona en la página Definición del manifiesto de esquema. A medida que se seleccionan elementos y atributos, pueden irse 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 "analizador" y escriba lo siguiente en el editor de Descripción:
    un nombre exclusivo que se utilizará para hacer referencia a este analizador.

  2. Seleccione el atributo "nombre" y añada el texto siguiente:
    un nombre convertible que se utilizará para presentar este analizador en la UI.

  3. Seleccione el atributo "clase" y añada el texto siguiente (atención a los códigos HTML):
    un nombre totalmente calificado de la clase de Java que implementa la interfaz <samp>com.example.xyz.IParser</samp>.

  4. Seleccione el atributo "modalidad" y añada esto:
    un distintivo opcional que indica con qué frecuencia se ejecutará esta instancia de analizador (el valor por omisión es <samp>siempre</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" del cuadro combinado que hay sobre el editor de texto y añada el texto siguiente:
    Este punto de extensión se utiliza para conectar analizadores adicionales. Los analizadores en realidad no funcionan: se han utilizando simplemente como ejemplo de esquema de puntos de extensión.
    Pulse Aplicar.

  2. Elija "Ejemplos" del 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 de la API" y añada el texto siguiente:
    Los conectores que quieran 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: debe 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 o los espacios en blanco formados por más de un carácter (es decir, espacios en blanco que pueden omitirse). Esto es lo que se espera en lo que se refiere al texto normal, pero es extraordinariamente molesto cuando se proporcionan ejemplos, en los que los tabuladores y la alineación vertical es significativa para que el ejemplo tenga buen aspecto. El PDE tiene una solución de compromiso para esta situación: si detecta el identificador HTML <pre>, conservará el contenido tal cual (conservando todos los caracteres sin realizar modificación ninguna) hasta encontrarse con el identificador </pre>. Esta es la razón por la que podemos proporcionar el ejemplo anterior y confiar en que el documento de consulta final tendrá buena apariencia.

Quizás ya se haya dado cuenta de que conforme escribe la documentación, cada vez más elementos del editor vista Diseño adoptan la imagen de un "lápiz". Este pequeño indicador indica 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).

Una vez se ha terminado con la documentación, podemos echar una ojeada a la documentación de consulta, parsers.html, que se encuentra en la carpeta "doc". Está creado por un constructor del PDE registrado para reaccionar ante cualquier cambio en los archivos del esquema de punto de extensión. El documento resultante de este ejemplo se parece a este.