christophedelory.xml
Class XmlSerializer

java.lang.Object
  christophedelory.xml.XmlSerializer

public final class XmlSerializer
extends Object

A collection of utilities when manipulating the Castor framework. The 3d-party Castor package achieves the Java-XML data binding.

Version:

$Revision: 55 $

Author:

Christophe Delory

Method Summary

static XmlSerializer	getMapping(String packageName) Retrieves the XML serializer instance associated to the specified package name.
Marshaller	getMarshaller() Returns the associated Castor marshaller.
Unmarshaller	getUnmarshaller() Returns the associated Castor unmarshaller.
void	marshal(Object o, File file, boolean asDocument) Writes the specified object as an XML stream to an output file.
void	marshal(Object o, String fileName, boolean asDocument) Writes the specified object as an XML stream to an output file.
void	marshal(Object o, Writer out, boolean asDocument) Writes the specified object as an XML stream to an output writer.
Object	unmarshal(File file) Unmarshalls an object from an input file, according to the underlying mapping.
Object	unmarshal(InputStream in) Unmarshalls an object from an input stream, according to the underlying mapping.
Object	unmarshal(Reader reader) Unmarshalls an object from a reader, according to the underlying mapping.
Object	unmarshal(String fileName) Unmarshalls an object from an input file, according to the underlying mapping.
Object	unmarshal(URL url) Unmarshalls an object from an input URL, according to the underlying mapping.

Methods inherited from class java.lang.Object

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

Method Detail

getMapping

public static XmlSerializer getMapping(String packageName)
                                throws IOException,
                                       MappingException

Retrieves the XML serializer instance associated to the specified package name. The full Castor mapping file name will be packageName/mapping.xml. Thus the separator character used in packageName shall be the slash ("/").

Parameters:

packageName - the package name. May be null.

Returns:

a XmlSerializer instance. Shall not be null.

Throws:

FileNotFoundException - if the mapping file cannot be found.

IOException - an error occured when reading the mapping file.

MappingException - the mapping file is invalid.

SecurityException - if a security manager exists and its checkPermission method denies access to the class loader for the class.

unmarshal

public Object unmarshal(String fileName)
                 throws Exception

Unmarshalls an object from an input file, according to the underlying mapping.

Parameters:

fileName - an XML file name. Shall not be null.

Throws:

MappingException - an exception indicating an invalid mapping error.

FileNotFoundException - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.

SecurityException - if a security manager exists and its checkRead method denies read access to the file.

MarshalException - when there is an error during the unmarshalling process.

ValidationException - when there is a validation error.

NullPointerException - if fileName is null.

Exception

See Also:

unmarshal(InputStream), Mapping

unmarshal

public Object unmarshal(File file)
                 throws Exception

Unmarshalls an object from an input file, according to the underlying mapping.

Parameters:

file - an XML file.

Throws:

MappingException - an exception indicating an invalid mapping error.

FileNotFoundException - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.

SecurityException - if a security manager exists and its checkRead method denies read access to the file.

MarshalException - when there is an error during the unmarshalling process.

ValidationException - when there is a validation error.

NullPointerException - if file is null.

Exception

See Also:

unmarshal(InputStream), Mapping

unmarshal

public Object unmarshal(URL url)
                 throws Exception

Unmarshalls an object from an input URL, according to the underlying mapping.

Parameters:

url - an URL.

Throws:

MappingException - an exception indicating an invalid mapping error.

IOException - if an I/O exception occurs.

MarshalException - when there is an error during the unmarshalling process.

ValidationException - when there is a validation error.

NullPointerException - if url is null.

Exception

See Also:

unmarshal(InputStream), Mapping

unmarshal

public Object unmarshal(InputStream in)
                 throws Exception

Unmarshalls an object from an input stream, according to the underlying mapping.

Parameters:

in - an input stream.

Throws:

MappingException - an exception indicating an invalid mapping error.

MarshalException - when there is an error during the unmarshalling process.

ValidationException - when there is a validation error.

NullPointerException - if in is null.

Exception

See Also:

Mapping

unmarshal

public Object unmarshal(Reader reader)
                 throws Exception

Unmarshalls an object from a reader, according to the underlying mapping.

Parameters:

reader - a reader.

Throws:

MappingException - an exception indicating an invalid mapping error.

MarshalException - when there is an error during the unmarshalling process.

ValidationException - when there is a validation error.

NullPointerException - if reader is null.

Exception

See Also:

Mapping

marshal

public void marshal(Object o,
                    String fileName,
                    boolean asDocument)
             throws Exception

Writes the specified object as an XML stream to an output file.

Parameters:

o - the object to serialize.

fileName - an XML file name.

asDocument - if true, indicates to marshal as a complete XML document, which includes the XML declaration, and if necessary the DOCTYPE declaration.

Throws:

IOException - if the named file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason.

IOException - if any I/O error occurred.

MappingException - an exception indicating an invalid mapping error.

MarshalException - a marshalling exception.

ValidationException - an XML validation error occurred.

NullPointerException - if o is null.

NullPointerException - if fileName is null.

Exception

See Also:

marshal(Object,Writer,boolean), Mapping

marshal

public void marshal(Object o,
                    File file,
                    boolean asDocument)
             throws Exception

Writes the specified object as an XML stream to an output file.

Parameters:

o - the object to serialize.

file - an XML file.

asDocument - if true, indicates to marshal as a complete XML document, which includes the XML declaration, and if necessary the DOCTYPE declaration.

Throws:

IOException - if the named file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason.

IOException - if any I/O error occurred.

MappingException - an exception indicating an invalid mapping error.

MarshalException - a marshalling exception.

ValidationException - an XML validation error occurred.

NullPointerException - if o is null.

NullPointerException - if file is null.

Exception

See Also:

marshal(Object,Writer,boolean), Mapping

marshal

public void marshal(Object o,
                    Writer out,
                    boolean asDocument)
             throws Exception

Writes the specified object as an XML stream to an output writer.

Parameters:

o - the object to serialize.

out - the writer.

asDocument - if true, indicates to marshal as a complete XML document, which includes the XML declaration, and if necessary the DOCTYPE declaration.

Throws:

MappingException - an exception indicating an invalid mapping error.

MarshalException - a marshalling exception.

ValidationException - an XML validation error occurred.

NullPointerException - if o is null.

NullPointerException - if out is null.

Exception

See Also:

Mapping

getMarshaller

public Marshaller getMarshaller()

Returns the associated Castor marshaller.

Returns:

a Castor marshaller. Shall not be null.

getUnmarshaller

public Unmarshaller getUnmarshaller()

Returns the associated Castor unmarshaller.

Returns:

a Castor unmarshaller. Shall not be null.