El API JAXB

Este cap�tulo describe brevemente como usar JAXB para:

  • Unir el esquema a las clases Java.
  • Construir representaciones de datos que siguen las reglas definidas en el esquema.
  • Usar los Datos en una aplicaci�n.

.�Introducci�n

Para comenzar a construir una aplicaci�n JAXB todo los que necesitamos es un esquema XML. La versi�n 1,0 de JAXB requiere que el esquema sea un DTD, seg�n lo definido en la especificaci�n XML 1,0, pero versiones posteriores probablemente utilizar�n otros lenguajes del esquema.

Despu�s de obtener nuestro DTD, construimos y usamos una aplicaci�n JAXB con estos pasos:

  1. Escribir el esquema de uni�n, un documento XML que contiene instrucciones de c�mo unir un esquema a las clases. Por ejemplo, el esquema de uni�n podr�a contener una instrucci�n sobre a qu� tipo primitivo se debe unir un valor de atributo en la clase generada.
  2. Generar los ficheros fuente de Java usando el compilador de esquema, que toma el DTD y el esquema de uni�n como entrada de informaci�n. Despu�s de compilar el c�digo fuente, podemos escribir una aplicaci�n basada en las clases que resulten.
  3. Con nuestr aplicaci�n, podemos construir un �rbol de objetos Java que representen datos XML que son v�lidos con el DTD:
    • ejemplarizando las clases generadas, o
    • invocaci�n m�todo unmarshal de una clase generada y pasarlo en el documento. El m�todo unmarshal toma un documento v�lido XML y construye una representaci�n de �rbol de objetos. El �rbol de objetos se llama un �rbol de contenido.
  4. Usar nuestra aplicaci�n para acceder a los daros del �rbol de contenidos para acceder a los datos del �rbol de contenido y modificar los datos del �rbol.
  5. Tambi�n podemos generar un documento XML desde el �rbol de contenido llamando al m�todo marshal sobre el objeto ra�z del �rbol.

Las tres siguientes secciones entran en m�s detalle sobre la construcci�n y utilizaci�n de aplicacions JAXB. La secci�n Unir un Esquema a las Clases describe los pasos 1 y 2. La secci�n Construir Representaciones de Datos describe el paso 3. La secci�n Trabajar con Datos describe los pasos 4 y 5.

.�Unir un Esquema a las Clases

Para unir un DTD a las clases, utilizamos el lenguaje de uni�n y el compilador de esquema, ambos incluidos con JAXB. El lenguaje de uni�n es un lenguaje basado en XML que utilizamos para escribir al esquema de uni�n, el que contiene las instrucciones para unir el DTD a las clases. El compilador del esquema genera un conjunto de ficheros fuente Java dedese el DTD basandose en las instrucciones que proporciononamos en el esquema de uni�n. Despu�s de que se generen los ficheros fuente Java, podemos compilarlos usando el compilador de Java como lo har�amos con cualquier aplicaci�n Java.

No necesitamos proporcionar una instrucci�n de uni�n para cada declaraci�n del DTD para generar las clases Java. El compilador de esquema hace ciertas asunciones basadas en el DTD si nuestro esquema de uni�n no especifica completamente c�mo deber�a unirse cada declaraci�n del DTD al c�digo. Por ejemplo, el compilador de esquema utiliza un algoritmo general de mapeo de nombres para unir nombres XML a nombres que son aceptables en el lenguaje de programaci�n Java. En este caso, podemos utilizar el esquema de uni�n para hacer que el compilador de esquema genere nombres diferentes. Hay muchas otros personalizaciones que podemos hacer con el esquema de uni�n, incluyendo:

  • Nombrar el paquete, las clases derivadas y los m�todos.
  • Asignar tipos a los m�todos dentro de las clases derivadas.
  • Elegir los elementos a unir a las clases.
  • Decidir c�mo unir cada declaraci�n de atributo y de elemento a una propieddad en la clase de contenido apropiada.
  • Crear constructores personalizador, interfaces, y enumeraciones.
  • Elegir el tipo de cada valor de atributo o especificaci�n de contenido.

Puedes encontrar m�s informacion sobre como escribir un esquema de uni�n en el cap�tulo Unir un Esquema a las Clases. La Difura 3-1 ilustra el proceso de generaci�n de las clases:

A menos que lo especifiquemos de otra manera en nuestro esquema de uni�n, el compilador de esquema genera una clase para cada elemento cuyo contenido contenga otros elementos. Dentro de una clase, el compilador de esquema genera las propiedades, que son los m�todos que utilizamos para tener acceso al contenido de los elementos hijos y a los valores de atributos. Estos m�todos devuelven y aceptan diversos tipos, dependiendo de tipo de declaraci�n en el esquema. Por ejemplo, los elementos con contenido #PCDATA est�n limitados a las propiedades que aceptan y devuelven valores String. Como un ejemplo de unir un esquema a las clases, consideremos una versi�n simplificada del DTD del cap�tulo anterior:

<!ELEMENT book (title, author, chapter+) > 
<!ELEMENT title (#PCDATA) > 
<!ELEMENT author (#PCDATA)> 
<!ELEMENT chapter (#PCDATA) >

En muchos casos, el compilador de esquema puede generar una uni�n apropiada incluso cuando el esquema de uni�n no incluye una instrucci�n de uni�n para una declaraci�n determinada del DTD. De hecho, para generar las clases del DTD book, todo lo que necesitamos en nuestro esquema de uni�n es:

<xml-java-binding-schema> 
    <element name="book" type="class" root="true" /> 
</xml-java-binding-schema>

Para estos DTD y esquema de uni�n, el compilador de esquema genera una clase Book con este contructor y estas propiedades:

public Book(); 
public String getTitle(); 
public void setTitle(String x); 
public String getAuthor(); 
public void setAuthor(String x); 
public List getChapter(); 
public void deleteChapter(); 
public void emptyChapter();

Recuerda que el elemento chapter en el modelo de contenido book ten�a un + como indicador de ocurrencia:

<!ELEMENT book (title, author, chapter+) >

Observa que este ejemplar de elemento chapter en el contenido del elemento book est� unido a una List de propiedades. Anteriormenteo dijimos que todos los elementos simples est�n limitados a las propiedades de String. Esta declaraci�n sigue siendo v�lida para el elemento chapter. La lista que devuelve getChapter es una lista de valores String, cada uno de los cuales representa un ejemplar distinto del elemento chapter. Observa tambi�n que el esquema de uni�n no hizo referencia al indicador de ocurrencia despu�s del ejemplar del elemento chapter. �ste es un ejemplo de c�mo el compilador de esquema considera las especificaciones del DTD as� como las instrucciones de uni�n del esquema de uni�n al generar las clases.

Las uniones por defecto que el compilador de esquema asume generalmente son adecuadas para DTDs simple como el ejemplo book. Un DTDs m�s complicado muy probablemente requerir� instrucciones de uni�n m�s completas. Por ejemplo, consideremo el DTD book con un modelo de elecci�n adicional que contiene los elementos simples prologue y preface:

<!ELEMENT book (title, author, (prologue | preface), chapter+) > 
... 
<!ELEMENT prologue (#PCDATA) > 
<!ELEMENT preface (#PCDATA) >

Usando el mismo esquema de uni�n con este nuevo DTd, el compilador de esquema producir�a este constructor y esta propiedad:

public void Book(); 
public List getContent(); 
public void deleteContent(); 
public void emptyContent();

En este ejemplo, la propiedad representa el modelo de contenido completo del elemento book. Esta clase de propiedades no es muy �til si deseamos tener acceso a un trozo determinado del contenido. Esta es la raz�n por la cual escribiremos un esquema de uni�n. Con el esquema de uni�n, podemos hacer muchas personalizaciones para requisitos particulares de nuestrasclases, incluyendo la definici�n de la forma en que los grupos de modelo est�n unidos a las clases, creando interfaces, y convirtiendo tipos. El cap�tulo Unir un Esquema a las Clases muestra c�mo especificar estas personalizaciones para requisitos particulares en el esquema de uni�n. Un esquema de uni�n que podr�amos escribir para este DTD ser�a:

<xml-java-binding-schema> 
    <element name="book" type="class" root="true"> 
        <content> <element-ref name="title" /> 
            <element-ref name="author" /> 
            <choice property="prologue-or-preface" /> 
        </content> 
    </element> 
</xml-java-binding-schema>

La declarac�n choice une el modelo de grupo choice a un objeto property dentro de la clase Book. Los elementos prologue y preface son unidos a clases separadas. Las declaraciones element-ref declarations unir�n los elementos a propiedades dentro de la clase Book.

Bas�ndose tanto en el esquema como el DTD, el compilador de esquema asume que el nombre de la clase deseada es Book y que los elemento simples se unen de acuerdo a estas declaracioens de uni�n:

<element name="title" type="value" /> 
<element name="author" type="value" /> 
<element name="prologue" type="class" /> 
<element name="preface" type="class" /> 
<element name="chapter" type="value" />

Desde el DTD y el esquema de uni�n, el compilador de esquema genera una clase Book con este constructor y estas propiedades:

public void Book(); 
public String getTitle(); 
public void setTitle(String x); 
public String getAuthor(); 
public void setAuthor(String x); 
public List getChapter(); 
public void deleteChapter(); 
public void emptyChapter(); 
public MarshallableObject getPrologueOrPreface(); 
public void setPrologueOrPreface(MarshallableObject x);

La propiedad prologue-or-preface devuelve y acepta un MarshallableObject, que representa objetos que pueden ser empaquetados y desempaquetados. La raz�n por la que este tipo de propiedad no es un String es porque no podemos determinarse si el String es un pr�logo o un prefacio; con MarshallableObject, si podemos porque ser� un objeto prologue o un objeto preface.

Los grupos modelo del elemento ra�z en estos ejemplos de DTDs son m�s simples que el que se han mostrado en el ejemplo del cap�tulo anterior. La especificaci�n de modelo de grupo XML 1,0 es muy compleja, reflejando el n�mero infinito de formas en que los datos pueden ser ordenados y representados. El siguiente cap�tulo explica m�s detalladamente c�mo unir modelos de grupo m�s complicados.

.�Construir Representaciones de Datos

Las clases Java que genera el compilador de esquema implementan y extienden las clases e interfaces del marco de trabajo de uni�n. Este marco de trabajo es el API de tiempo de ejecuci�n que usan las clases generadas para soportar tres operaciones primarias:

  • Desempaquetar: el proceso de producir u �rbol de contenidos desde un documento XML.
  • Validaci�m: el proceso de verificar que la representaci�n de objetos Java est� conforme a las reglas especificadas en el DTD.
  • Empaquetar: el proceso de producir un documento XML desde objetos Java.

Para realizar estas operaciones, cada clase generada contiene m�todos para empaquetar datos, validar contenidos, y extienden m�todos del marco de trabajo de uni�n que realizan el empaquetamiento.

.�Desempaquetar

Con los m�todos unmarshal, podemos construir un �rbol objetos Java desde documentos XML que son ejemplares del esquema usado para generar las clases. El �rbol de objetos construido con JAXB se llama un �rbol de contenido. Cada objeto del �rbol corresponde a un elemento del documento XML. De forma semejantemente, cada objeto del �rbol es un ejemplar de una clase del conjunto de clases generadas. Tambi�n podemos construir un �rbol de contenido ejemplarizando objetos de las clases porque el �rbol de contenido une el documento y las clases. El cap�tulo Construir Representaciones de Datos demuestra c�mo utilizar el desmpaquetamiento y la ejemplarizaci�n para construir un �rbol de contenido. tree.

.�Validaci�n

El proceso de desempaquetamietno realiza validaci�n mientras est� construyendo el �rbol de contenido, por eso es imposible desempaquetar un documento XML a un �rbol de contenido que es inv�lido con respecto al DTD. Podemos realizar validaci�n en caulquier momento despu�s de haber construido el �rbol de contenido usando ls m�todos validate o validateThis en cada clase generada. El m�todo validate valida completamente el sub�rbol enraizado en el objeto ra�z sobre el que le hemos llamado; el m�todo validateThis s�lo valida un objeto del �rbol.

.�Empaquetar

Tanto si constru�mos el �rbol de contenido usando desempaquetamietno o ejemplarizaci�n , podemos empaquetar el �rbol a un nuevo documento XML usando lo m�todo marshal. Esto significa que JAXB tambi�n permite que creemos nuevos documentos XML que son v�lidos con respecto al DTD fuente. Las proceso de empaquetado comprueba si el �rbol de contenido se ha validado antes de empaquetarlo en caso de que hayamos realizado cambios a los objetos del �rbol. As� pues, igual que es imposible desempaquetar un documento inv�lido, es imposible empaquetar un �rbol de contenido inv�lido.

La Figura 3-2 ilustra dos formas para construir representaciones de datos.

Continuando con el ejemplo book, podemos desempaquetar este documento usando la clase Book que generamos:

<book> 
    <title>Duke: My Life and Times</title> 
    <author>Duke</author> 
    <chapter>The First Six Years ... </chapter> 
</book>

El m�todo unmarshal devolver� un objeto Book, digamos dukeBook , que es la ra�z del �rbol de contenido. Una vez que tenemos el �rbol, podemos empezar a trabajar con los datos.

.�Trabajar con Datos

Podemos trabajar con los objetos del �rbol de contenido igual que lo har�amos con cualquier objeto Java. De esta forma, JAXB proporciona un interfaz de programaci�n Java de datos XML, que podemos utilizar para integrar datos XML en las aplicaciones Java.

para tener acceso al contenido del �rbol, utilizamo las propieades de las clases generadas. Por ejemplo, para obtener el nombre del autor del dukeBook: "My Life and Times", simplemente simplemente llamamos a getAuthor en el objeto dukeBook. Digamos que el libro de Duke fue realmente escrio por un escritor fantasma. Para alisar las cosas, podr�amos llamar a setAuthor("Duke et. el al.") en el objeto dukeBook. Para validar el �rbol modificado, podemos llamar a validate sobre dukeBook, y empaquetarlo en un nuevo documento XML, llamando a dukeBook.marshal().

Para proporcionar funcionalidades especificaas de la aplicaci�n, podemos extender las clases en vez de s�lo utilizarlas directamente. Por ejemplo, adem�s de para acceder a un trozo de datos, tambi�n podr�amos querer realizar alg�n c�lculo con los datos o, en el caso de dukeBook, agregar los datos a un cat�logo. Podemos proporcionar estas funcionalidades en una subclase de una clase derivada. El cap�tulo Construir Representaciones de Datos utiliza el ejemplo libro de cheques descrito anteriormente en el Escenario 1: La secci�n "Balance del Libro de Cheques" utiliza las clases generadas directamente para acceder directamente a los datos de la transacci�n y c�mo ampliarlos para balancear nuestro libro de cheques.

.�Limitaciones

Como es versi�n de JAXB es una versi�n early-access, tiene algunas limtiaciones, que se corregir�n en versiones futuras. Algunas de estas limitaciones incluyen:

  • Soporte para un s�lo lenguaje de esquema:

    Mientras se desarrollan m�s lenguajes de esquema y se definen las especificaciones existentes del lenguaje de esquema, los desarrolladores de JAXB intentar�n soportar m�s lenguajes de esquema en versiones posteriores. Por ahora, el sublenguaje del DTD XML 1,0 es una opci�n natural para un lenguaje de esquema porque es el lenguaje de esquema m�s ampliamente utilizado y permite que JAXB sirva a un mayor n�mero de desarrolladores.

  • No soporta espacios de nombres XML:

    Las DTDs XML y los Espacios de Nombres XML no funcionan bien Juntos. Como esta versi�n de JAXB requiere un DTD, los Espacios de nombres no est�n soportados.

  • No hay soporte para lo tipos Internal subsets, NOTATIONs, ENTITY, ENTITIES, y NOTATION enumerados del sublenguaje XML DTD 1.0:

    Estos constructores no aparecen muy frecuentemente en DTDs, por eso los desarrolladores eligieron no soportarlos para simplificar la especificaci�n del Lenguaje de Uni�n.

COMPARTE ESTE ARTÍCULO

COMPARTIR EN FACEBOOK
COMPARTIR EN TWITTER
COMPARTIR EN LINKEDIN
COMPARTIR EN WHATSAPP
SIGUIENTE ARTÍCULO