|
ContactCenters V. 0.9.9. |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectumontreal.iro.lecuyer.xmlbind.JAXBParamsConverter<T>
T
- the type of objects processed by the converter.public abstract class JAXBParamsConverter<T>
Convenience base class to marshal and unmarshal objects of a specific class using JAXB. When using JAXB directly, one must create a context, use that context to get an unmarshaller or a marshaller, convert the unmarshalled JAXB element into a value object, or wrap a value object into a JAXB element for marshalling. This class can help in performing these tasks. It also manages the association of a schema to unmarshallers, and marshallers in order to perform validation. It also implements a mechanism to replace JAXB-generated namespace prefixes by user-defined prefixes while marshalling. This does not affect the validity of marshalled XML, but it can increase the readability of the output files.
The methods unmarshal(File)
,
and File)
can be used
to marshal and unmarshal objects.
Alternatively, simple console applications may use
unmarshalOrExit(File)
, and
File)
which prints a detailed message and exits in case of an error while
the regular methods throw exceptions.
This class must be extended with a specific type of parameter object to be
used. This type can be any class derived by the
JAXB-provided xjc
compiler from a XML Schema.
It must be passed as a type parameter when creating this class.
More specifically,
any concrete subclass must implement the getContext()
method used
to create the JAXB context as well as the getSchema()
method to get
the schema object used for validation.
For example, suppose that we have a Schema describing parameters of call centers, with a root element of type CallCenterParams. The JAXB compiler produces a class named CallCenterParams. The user-defined converter class then extends the base class JAXBParamsConverter<CallCenterParams>, and provides an implementation for the two mandatory methods.
Constructor Summary | |
---|---|
JAXBParamsConverter(Class<T> objClass)
Constructs a new converter manipulating objects of class objClass. |
Method Summary | |
---|---|
abstract JAXBContext |
getContext()
Constructs and returns the JAXB context used to read parameters. |
ValidationEventHandler |
getEventHandler()
Returns the validation event handler associated with marshallers and unmarshallers used by this converter. |
Object |
getJAXBObject(Object value)
Constructs and returns a JAXB element with value as a value. |
abstract Map<String,String> |
getNamespacePrefixes()
Returns a map associating prefixes with namespace URI. |
abstract Schema |
getSchema()
Constructs and returns a schema for the document type represented by a concrete subclass. |
T |
getValue(Object jaxbElement)
Converts the JAXB element returned by an unmarshaller into an instance of class T. |
static boolean |
hasErrors(ValidationEvent... evs)
Similar to hasWarnings(ValidationEvent[])
for errors instead of warnings. |
static boolean |
hasFatalErrors(ValidationEvent... evs)
Similar to hasWarnings(ValidationEvent[])
for fatal errors instead of warnings. |
static boolean |
hasWarnings(ValidationEvent... evs)
Determines if the given list of validation events contains at least one event representing a warning. |
void |
initMarshaller(Marshaller m)
Initializes the marshaller before it is used by this object. |
void |
initUnmarshaller(Unmarshaller um)
Initializes the unmarshaller before it is used by this object. |
boolean |
isValidating()
Determines if this converter is validating unmarshalled and marshalled instances. |
static String |
locatorToString(ValidationEventLocator locator)
Formats the given locator locator into a string. |
void |
marshal(T object,
ContentHandler handler1)
Marshals the given object by generating SAX events and sending them to the given content handler. |
void |
marshal(T object,
File res)
Marshals the given value object into the given output file. |
void |
marshal(T object,
Node node)
Similar to File) , for a DOM node. |
void |
marshal(T object,
Result res)
Marshals the given object object to the target set by res. |
void |
marshalAndGZip(T object,
File res)
Marshals the given object to the given file, and gzips the marshalled contents. |
void |
marshalAndGZipOrExit(T object,
File file)
Similar to File) ,
except that the method File)
is called instead of File) . |
void |
marshalOrExit(T object,
File file)
Marshals the object object to the file file, using the File) method, but
if an error occurs, this method prints messages
on the standard error output, and exits the
VM using System.exit(int) . |
Schema |
readSchema()
Tries to use getSchema() to obtain the schema. |
void |
setEventHandler(ValidationEventHandler handler)
Sets the validation event handler to handler. |
void |
setValidating(boolean validating)
Sets the status of the validating indicator to validating. |
T |
unmarshal(File file)
Unmarshals the given input file to an object. |
T |
unmarshal(Node node)
Unmarshals the given node into a JAXB object, and returns the constructed object. |
T |
unmarshal(Source source)
Unmarshals the given source into an object, and returns the constructed object. |
T |
unmarshal(URL url)
Unmarshals the given URL into an object, and returns the constructed object. |
T |
unmarshalGZipped(File file)
Reads the given input file as a GZipped file, using GZIPInputStream ,
and unmarshals the uncompressed XML data. |
T |
unmarshalGZipped(URL url)
Similar to unmarshalGZipped(File) ,
for a URL instead of a file. |
T |
unmarshalOrExit(File file)
Unmarshals the given file using unmarshalGZipped(File) , but
if an error occurs, messages are
printed on the standard error output,
and the method exits the VM
using System.exit(int) . |
static String |
validationEventsToString(ValidationEvent... evs)
Formats and returns a string containing a description for each validation event in the given list. |
static String |
validationEventToString(ValidationEvent ev)
Constructs and returns a string representing the validation event ev. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public JAXBParamsConverter(Class<T> objClass)
objClass
- the class of objects.Method Detail |
---|
public abstract JAXBContext getContext() throws JAXBException
Any concrete subclass should define a static field
of type JAXBContext
.
If the field is non-null, the method returns
its value.
Otherwise, it initializes the field using
JAXBContext.newInstance(String)
,
and returns the resulting context.
The arguments given to JAXB depends on the
JAXB-derived class associated with the concrete subclass.
JAXBException
- if an error occurs while creating the JAXB context.public abstract Schema getSchema() throws SAXException
It is recommended to use SchemaFactory
to create the
Schema
object, and to store it in a static variable for future
use, because loading and parsing the schema might be costly.
If the schema is stored at the same location as class files,
Class.getResourceAsStream(String)
can be used
to obtain a stream for the schema.
SAXException
- if an error occurred during reading or parsing.public abstract Map<String,String> getNamespacePrefixes()
When using namespaces, each XML element and attribute can be qualified
with a namespace URI which is referred to, in the XML document, using a
prefix. These prefixes, which are not unique in contrast with URIs, can be
chosen arbitrarily, but they should be human-readable for clearer
documents. However, by default, JAXB generates its own prefix each time it
finds a new namespace URI during marshalling; there is no standard way to
impose prefixes. This map can be used to bind user-defined prefixes to the
URIs used by the XML document. When this method returns a non-empty map,
the marshalling mechanism of this class uses the
RemappingContentHandler
to perform the namespace prefix mapping in
a way independent from the JAXB implementation.
public Schema readSchema()
getSchema()
to obtain the schema. If this method
throws a SAX exception, the exception is logged, validation is disabled,
and this method returns null. Otherwise, the schema object is
returned. This can be used to work around bugs in some Java implementations
preventing valid schemas to be read; parsing will then continue, without
validation.
public void initUnmarshaller(Unmarshaller um) throws JAXBException
getEventHandler()
. It can be overridden to perform custom
initialization such as setting properties.
um
- the unmarshaller being initialized.
JAXBException
public void initMarshaller(Marshaller m) throws JAXBException
getEventHandler()
to the marshaller, and activates the
Marshaller.JAXB_FORMATTED_OUTPUT
property. It can be overridden to
perform custom initialization such as setting properties.
m
- the marshaller being initialized.
JAXBException
public boolean isValidating()
public void setValidating(boolean validating)
validating
- the new value of the indicator.public ValidationEventHandler getEventHandler()
public void setEventHandler(ValidationEventHandler handler)
handler
- the new validation event handler.public T getValue(Object jaxbElement) throws JAXBException
JAXBIntrospector.getValue(Object)
to obtain the object, and casts it to an instance of class T.
jaxbElement
- the JAXB element.
JAXBException
- if an error occurs during conversion.public Object getJAXBObject(Object value) throws JAXBException
Marshaller
in order to be
serialized to XML.
This method first uses JAXBIntrospector.isElement(Object)
to test
if the given value is an element, and returns the value if the test
succeeds. Otherwise, this method looks for an ObjectFactory
class in the package of the class of the given value.
If such a factory is found, the method searches
a factory method in this factory taking an object corresponding
to the type of the
given value, and calls this method to get a JAXB element encapsulating the
value.
value
- the value to encapsulate.
JAXBException
- if an error occurs during the process.public T unmarshal(File file) throws JAXBException
This method first calls getContext()
to obtain a JAXB context. It
then uses the obtained JAXB context to create an unmarshaller, sets its
schema to the value returned by readSchema()
, and
initializes it by
calling initUnmarshaller(Unmarshaller)
. It then uses the
unmarshaller to process the given file, and calls
getValue(Object)
to obtain the value of the resulting JAXB
element.
file
- the input file.
JAXBException
- if an error occurs during unmarshalling.public T unmarshal(URL url) throws JAXBException
unmarshal(File)
, for a URL.
url
- the URL of the input.
JAXBException
- if an error occurs during unmarshalling.public T unmarshalGZipped(File file) throws JAXBException
GZIPInputStream
,
and unmarshals the uncompressed XML data.
If the given file is not in GZIP format,
this method calls unmarshal(File)
to unmarshal a plain text file.
file
- the file to be read.
JAXBException
- if an error occurs during file reading.public T unmarshalGZipped(URL url) throws JAXBException
unmarshalGZipped(File)
,
for a URL instead of a file.
url
- the URL pointing to the XML data.
JAXBException
- if an error occurs during the unmarshalling process.public T unmarshal(Node node) throws JAXBException
unmarshal(File)
, for a DOM node.
node
- the DOM node to be unmarshalled.
JAXBException
- if an error occurs during unmarshalling.public T unmarshal(Source source) throws JAXBException
unmarshal(File)
, for a source.
source
- the source to be unmarshalled.
JAXBException
- if an error occurs during unmarshalling.public T unmarshalOrExit(File file)
unmarshalGZipped(File)
, but
if an error occurs, messages are
printed on the standard error output,
and the method exits the VM
using System.exit(int)
.
This method is intended to be used
in main methods of command-line
programs.
file
- the input file.
public void marshal(T object, ContentHandler handler1) throws JAXBException
This method calls getJAXBObject(Object)
on the given object to
convert it into a JAXB object. It then creates a marshaller using the
context returned by getContext()
, sets its schema to the value
returned by readSchema()
, initializes it with
initMarshaller(Marshaller)
, and gives it the JAXB object
obtained from the given value. If getNamespacePrefixes()
returns
a non-empty map, the supplied handler is wrapped around a
RemappingContentHandler
in order to take namespace prefixes into
account, and wrapped handler is passed
to the marshaller. Otherwise, the content handler is passed directly
to the marshaller.
object
- the object to marshal.handler1
- the content handler.
JAXBException
- if an exception occurs during marshalling.public void marshal(T object, Result res) throws JAXBException
This method calls getJAXBObject(Object)
to turn the given object
into a JAXB object. If getNamespacePrefixes()
returns an empty
map, this method creates a marshaller the same way as
ContentHandler)
, and uses it
directly to marshal the JAXB
object. Otherwise, it creates a TransformerHandler
, and gives it
to ContentHandler)
.
object
- the object to marshal.res
- the result object.
JAXBException
- if an error occurs during marshalling.public void marshal(T object, File res) throws JAXBException
StreamResult
with the given file object, and calls
Result)
to performing marshalling.
object
- the value to marshal.res
- the output file.
JAXBException
- if an error occurs during marshalling.public void marshalAndGZip(T object, File res) throws JAXBException
object
- the object to be marshalled.res
- the target file.
JAXBException
- if an error occurs during marshalling.public void marshal(T object, Node node) throws JAXBException
File)
, for a DOM node.
object
- the value object to marshal.node
- the output node.
JAXBException
- if an error occurs during marshalling.public void marshalOrExit(T object, File file)
File)
method, but
if an error occurs, this method prints messages
on the standard error output, and exits the
VM using System.exit(int)
.
This method is intended to be used in
main methods of command-line
programs.
object
- the object to marshal.file
- the output file.public void marshalAndGZipOrExit(T object, File file)
File)
,
except that the method File)
is called instead of File)
.
object
- the object to be marshalled.file
- the output file.public static boolean hasWarnings(ValidationEvent... evs)
ValidationEvent.getSeverity()
, and
returns true as soon as one event with
severity ValidationEvent.WARNING
is found.
This returns false if the list is empty,
or if it contains only events representing errors
or fatal errors.
evs
- the tested list.
public static boolean hasErrors(ValidationEvent... evs)
hasWarnings(ValidationEvent[])
for errors instead of warnings.
evs
- the tested list.
public static boolean hasFatalErrors(ValidationEvent... evs)
hasWarnings(ValidationEvent[])
for fatal errors instead of warnings.
evs
- the tested list.
public static String validationEventsToString(ValidationEvent... evs)
validationEventToString(ValidationEvent)
,
and separates each event with two newlines.
evs
- the list of validation events.
public static String validationEventToString(ValidationEvent ev)
locatorToString(ValidationEventLocator)
which converts the location information into
a string.
ev
- the validation event being formatted.
public static String locatorToString(ValidationEventLocator locator)
locator
-
|
ContactCenters V. 0.9.9. |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |