edu.nrao.sss.util
Class JaxbUtility

java.lang.Object
  edu.nrao.sss.util.JaxbUtility

public class JaxbUtility
extends Object

A utility for converting an object to XML and vice versa.

This class will be used primarily in the toXml and fromXml methods of other classes.

How Schema Files are Located and Used

If a transformation method (one that turns XML into an object or vice versa) takes a Schema parameter, that schema will be the one used for validation. If, however, the Schema parameter is null, this utility will either attempt to find a default schema or bypass schema validation, depending on the state of the lookForDefaultSchema property of this utility.

The location of the default schema files is given by this utility's schemaBaseUrl property. If this property has been set to null, then the default location for the schema files will be the location on the classpath of the targeted class.

The name of the primary default schema file, regardless of its default location, is theClass.getSimpleName() + ".xsd". If a primary default schema file cannot be found, a secondary default is used. The name of the secondary default file is packageName.xsd where packageName is the "simple" package name. For example, the simple package name of edu.nrao.sss.model.source is "source", thus the schema file would be "source.xsd".

New 2008-12-30: If, in the example above, "source.xsd" is not found, an attempt will be made to find "model.xsd", "sss.xsd", and so on up the line. If none of those files exist a log entry will be created and a null schema will be used. Depending no the particular usage this could result in an exception or marshalling / unmarshalling without schema verification.

Note that a default schema file is sought only when the lookForDefaultSchema property is true. If we seek a default schema file but fail to find it, what happens next depends on the value of the failIfDefaultSchemaNotFound property. If that property is false, transformation occurs without validation. If it is true, the transformation methods will throw JaxbExceptions.

At this time the schemaBaseUrl can be set only programatically. A possible future enhancement would allow the specification of this value via a properties file.

Version Info:

$Revision: 2276 $

$Date: 2009-04-29 10:34:57 -0600 (Wed, 29 Apr 2009) $

$Author: dharland $

Since:

2006-09-05

Author:

David M. Harland

Constructor Summary

JaxbUtility()
Creates a new instance.

Method Summary

URL	getBaseUrlForSchemaFiles() Returns the base URL that this utility will use for locating schema files.
Schema	getSchema(String relativeUrl, Class<?> c) Attempts to build and return a Schema based on the given URL to use for objects of the given class.
Schema	getSchemaFor(Class<?> c) Attempts to build and return a Schema to use for objects of the given class.
static JaxbUtility	getSharedInstance() Returns a shared, pre-constructed, instance of this utility.
String	objectToXmlString(Object o) Returns an XML string for the given object.
String	objectToXmlString(Object o, Schema schema) Returns an XML string for the given object, using schema for validation.
String	objectToXmlString(Object o, String schemaFileName) Returns an XML string for the given object, using the schema found in the given file for validation.
<T> T	readObjectAsXmlFrom(InputStream stream, Class<T> c, Schema schema) Creates and returns a new object based on the data read from an XML source.
<T> T	readObjectAsXmlFrom(Reader reader, Class<T> c, Schema schema) Creates and returns a new object based on the data read from an XML source.
void	setBaseUrlForSchemaFiles(URL baseUrl) Sets the base URL that this utility will use for locating schema files.
void	setFailIfDefaultSchemaNotFound(boolean fail) Tells this utility whether or not failure to find a default schema should result in failure of the transformation methods.
void	setLookForDefaultSchema(boolean look) Tells this utility whether or not it should look for a default schema if one is not specified.
void	writeObjectAsXmlTo(Writer writer, Object o, Schema schema) Writes o as XML to writer, using schema for validation.
<T> T	xmlFileToObject(String fileName, Class<T> c) Creates and returns a new object based on the data in an XML file.
<T> T	xmlFileToObject(String fileName, Class<T> c, Schema schema) Creates and returns a new object based on the data in an XML file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JaxbUtility

public JaxbUtility()

Creates a new instance.

Method Detail

getSharedInstance

public static JaxbUtility getSharedInstance()

Returns a shared, pre-constructed, instance of this utility.

setLookForDefaultSchema

public void setLookForDefaultSchema(boolean look)

Tells this utility whether or not it should look for a default schema if one is not specified. A schema is not specified if a method that takes no schema argument is called, or if a method with a schema argument is called, but the passed, or resulting, schema is null.

The default value of this property is true.

See the note, How Schema Files are Located and Used, at the top of this class for more information about schema acquisition and usage.

Parameters:

look - true if this utility should seek out a default schema.

setFailIfDefaultSchemaNotFound

public void setFailIfDefaultSchemaNotFound(boolean fail)

Tells this utility whether or not failure to find a default schema should result in failure of the transformation methods. If this property is true, those methods will fail with JaxbExceptions. If this property is false, those methods will perform transformations without validation.

The default value of this property is true.

Parameters:

fail - signals the transformations to fail if a default schema is sought but not found.

setBaseUrlForSchemaFiles

public void setBaseUrlForSchemaFiles(URL baseUrl)

Sets the base URL that this utility will use for locating schema files. To configure this utility so that the default schema files are found on the classpath, use a parameter of null.

The default value of this property is https://e2e.nrao.edu/schemas/.

See the note, How Schema Files are Located and Used, at the top of this class for more information about schema acquisition and usage.

Parameters:

baseUrl - the base URL that this utility will use for locating schema files. A value of null may be used to tell this utility to look for default schema files on the classpath.

getBaseUrlForSchemaFiles

public URL getBaseUrlForSchemaFiles()

Returns the base URL that this utility will use for locating schema files.

See the note, How Schema Files are Located and Used, at the top of this class for more information about schema acquisition and usage.

Returns:

the base URL that this utility will use for locating schema files.

getSchemaFor

public Schema getSchemaFor(Class<?> c)
                    throws JAXBException

Attempts to build and return a Schema to use for objects of the given class. This method does not look at the value of the lookForDefaultSchema property.

Parameters:

c - the class for which a schema is desired.

Returns:

a schema to use for objects of type c, or null if no such schema could be found.

Throws:

JAXBException - if a schema file was found for c but something went wrong in the process of turning the file into a Schema object.

See Also:

getSchema(String, Class)

getSchema

public Schema getSchema(String relativeUrl,
                        Class<?> c)
                 throws FileNotFoundException,
                        SAXException

Attempts to build and return a Schema based on the given URL to use for objects of the given class. The class c is used only if the base URL used by this utility is null.

Parameters:

relativeUrl - typically the name of the schema file

c - the class used to locate the schema file, but only in the event that the base URL used by this utility is null.

Returns:

a schema, or null if one could not be created.

Throws:

FileNotFoundException - if URL can't be found.

SAXException - if URL found but can't be turned into schema.

writeObjectAsXmlTo

public void writeObjectAsXmlTo(Writer writer,
                               Object o,
                               Schema schema)
                        throws JAXBException

Writes o as XML to writer, using schema for validation.

If schema is non-null, it is used to validate the contents of this object while converting it to XML. If schema is null, one of two approaches will be taken, depending on the state of the lookForDefaultSchema property:

1. If false, the object o will be transformed into XML without validation against a schema.
2. If true, this utility will attempt to locate a default schema (see setLookForDefaultSchema(boolean). If found, it will be used to validate the object o during the transformation to XML. If not found, the object o will be transformed into XML without validation against a schema.

If there are any problems encountered during the transformation to XML, a JAXBException will be thrown.

Parameters:

writer - the device to which XML is written. If this value is null, no action is taken.

o - the object to be expressed in XML. If this value is null, no action is taken.

schema - the holder of the rules for validating the XML output. If this value is null, and if setLookForDefaultSchema(boolean) was called most recently with a value of true, an attempt will be made to locate a default schema.

Throws:

JAXBException - if any problems are encountered during the transformation to XML.

readObjectAsXmlFrom

public <T> T readObjectAsXmlFrom(Reader reader,
                                 Class<T> c,
                                 Schema schema)
                      throws JAXBException,
                             XMLStreamException

Creates and returns a new object based on the data read from an XML source.

See writeObjectAsXmlTo(Writer, Object, Schema) to understand how the schema parameter is treated.

Type Parameters:

T - the runtime type of the returned object.

Parameters:

reader - the source of the XML data. If this value is null, null is returned.

c - the class of which the returned object is an instance. If this value is null, null is returned.

schema - the schema used to verify the XML file.

Returns:

an object based on the data in an XML file.

Throws:

XMLStreamException - if the XML is not well-formed, or for some other "unexpected processing conditions".

JAXBException - if anything else goes wrong during the transformation.

readObjectAsXmlFrom

public <T> T readObjectAsXmlFrom(InputStream stream,
                                 Class<T> c,
                                 Schema schema)
                      throws JAXBException,
                             XMLStreamException

Creates and returns a new object based on the data read from an XML source.

See writeObjectAsXmlTo(Writer, Object, Schema) to understand how the schema parameter is treated.

Type Parameters:

T - the runtime type of the returned object.

Parameters:

stream - the source of the XML data. If this value is null, null is returned.

c - the class of which the returned object is an instance. If this value is null, null is returned.

schema - the schema used to verify the XML file.

Returns:

an object based on the data in an XML file.

Throws:

XMLStreamException - if the XML is not well-formed, or for some other "unexpected processing conditions".

JAXBException - if anything else goes wrong during the transformation.

objectToXmlString

public String objectToXmlString(Object o,
                                Schema schema)
                         throws JAXBException

Returns an XML string for the given object, using schema for validation.

This is a convenience method that is equivalent to calling writeObjectAsXmlTo(Writer, Object, Schema) and using the Writer to get a String. See that method for more details about schema and exception handling.

Parameters:

o - the object to be expressed in XML.

schema - the holder of the rules for validating the XML output.

Returns:

an XML representation of the object o.

Throws:

JAXBException - if any problems are encountered during the transformation to XML.

objectToXmlString

public String objectToXmlString(Object o)
                         throws JAXBException

Returns an XML string for the given object. This is a convenience method that is equivalent to calling objectToXmlString(o, (Schema)null).

Parameters:

o - the object to be expressed in XML.

Returns:

an XML representation of the object o.

Throws:

JAXBException

objectToXmlString

public String objectToXmlString(Object o,
                                String schemaFileName)
                         throws JAXBException,
                                FileNotFoundException

Returns an XML string for the given object, using the schema found in the given file for validation.

This is a convenience method that behaves like objectToXmlString(Object, Schema), after schemaFileName has been turned into a schema. The location of the schema file is determined by o.getClass().getResource(schemaFileName). If the schema file cannot be found, a FileNotFoundException is thrown.

Parameters:

o - the object to be expressed in XML.

schemaFileName - the name of the file that holds the schema used to validate the XML transformation.

Returns:

an XML representation of the object o.

Throws:

FileNotFoundException - if the schema file cannot be found.

JAXBException - if any problems are encountered during the transformation to XML.

xmlFileToObject

public <T> T xmlFileToObject(String fileName,
                             Class<T> c,
                             Schema schema)
                  throws JAXBException,
                         XMLStreamException,
                         FileNotFoundException

Creates and returns a new object based on the data in an XML file.

This is a convenience method that is equivalent to calling readObjectAsXmlFrom(Reader, Class, Schema) after turning fileName into a Reader. See that method for more details about schema and exception handling.

Type Parameters:

T - the runtime type of the returned object.

Parameters:

fileName - the name of an XML file.

c - the class of which the returned object is an instance.

schema - the schema used to verify the XML file.

Returns:

an object based on the data in an XML file.

Throws:

FileNotFoundException - if the XML file could not be found.

XMLStreamException - if there is a problem opening the XML file, if the XML is not well-formed, or for some other "unexpected processing conditions".

JAXBException - if anything else goes wrong during the transformation.

xmlFileToObject

public <T> T xmlFileToObject(String fileName,
                             Class<T> c)
                  throws JAXBException,
                         XMLStreamException,
                         FileNotFoundException

Creates and returns a new object based on the data in an XML file. This is a convenience method that is equivalent to calling xmlFileToObject(fileName, c, (Schema)null).

Type Parameters:

T - the runtime type of the returned object.

Parameters:

fileName - the name of an XML file.

c - the class of which the returned object is an instance.

Returns:

an object based on the data in an XML file.

Throws:

FileNotFoundException - if the XML file could not be found.

XMLStreamException - if there is a problem opening the XML file, if the XML is not well-formed, or for some other "unexpected processing conditions".

JAXBException - if anything else goes wrong during the