JAXB Data Import & Export

JAXB for Import & Export

To reduce duplication of configuration and increase usability of the uPortal data file formats XML Schemas and JAXB are being used for importing and exporting portal data. This ability is meant to slowly replace the existing Cernunnos scripts used for importing and exporting data. The portal framework for this process includes the following parts:

1. One XSD for each portal data type that describes the external XML form of the data. (ex: stylesheet-descriptor-4.0.xsd)
2. Use of an XJC maven plugin to auto-generate the corresponding JAXB annotated Java classes for each portal data XSD.
3. A generic import/export service that handles marshalling and unmarshalling of the portal data XML and location of the correct portal data import/export implementation to handle the data.
4. A service interface that is implemented once for each portal data type that handles converting the data between its internal and external forms and interfacing with the appropriate portal DAOs.

Important Interfaces

1. JaxbDataImportExportService implements IDataImportExportService
   1. List all available data types that can be exported
   2. List all available data for each type
   3. Import from an XML Source
   4. Upgrade then import from an XML Source
   5. Export to an XML Result
2. IDataImporterExporter
   1. Maps between XJC generated classes and the portal data type
   2. Provides a list of data available to export to the IDataImportExportService
   3. Provides JAXB marshaller and unmarshaller objects to use for converting the data to and from XML
3. IDataUpgrader
   1. Transforms an XML Source into a Result, updating the data format in the process

The Import Process

1. JaxbDataImportExportService.importData(source) is called with an XML file
   1. A key is generated based on the root element name along with the script and version attribute values.
   2. If a IDataImporterExporter that handles the data key is found
      1. Get the unmarshaller and conver the XML to an object graph
      2. Pass the object graph to the {{IDataImporterExporter} to import
   3. If no importer but a IDataUpgrader that handles the data key is found
      1. Transform the Source XML into a Result and then recurse on the result data
   4. If no handler is found throw an exception

The Export Process

1. JaxbDataImportExportService.exportData(String typeId, String dataId)
   1. The typeId is used to lookup a IDataImporterExporter implementation
2. IDataImporterExporter.exportData(dataId) is called by JaxbDataImportExportService
   1. Retrieve the data from the portal DAO using the id
   2. Map all of the data from the internal data object to the external data object and return it
3. JaxbDataImportExportService marshalls the external data object to XML and returns the result.

Setting up a New Portal Data Type

1. Create a new XSD that describes the external data format. This format MUST NOT reference any generated ID and be human editable.
2. List the XSD directory in the xjc plugin uportal-war/pom.xml maven-jaxb2-plugin
3. List the XSD in uportal-war/src/main/binding/bindings.xjb and define a package name under org.jasig.portal.io.xml for the generated classes
4. Create an extension of AbstractJaxbIDataImporterExporter that does the following
   1. Describes the data via the IPortalDataType interface
   2. List all available data in the portal via the IPortalData interface
   3. Can map the XJC generated classes to and from the internal portal object model for the data