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