com.phloc.commons.jaxb.utils

Class AbstractJAXBMarshaller<JAXBTYPE>

java.lang.Object

com.phloc.commons.jaxb.utils.AbstractJAXBMarshaller<JAXBTYPE>

@NotThreadSafe
public abstract class AbstractJAXBMarshaller<JAXBTYPE>
extends Object

This is the abstract reader and writer base class for JAXB enabled document types.

Author:

Philip Helger

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEFAULT_FORMATTED Deprecated.
static boolean	DEFAULT_READ_SECURE
static boolean	DEFAULT_WRITE_FORMATTED

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractJAXBMarshaller(Class<JAXBTYPE> aType, IReadableResource... aXSDs) Constructor.
protected	AbstractJAXBMarshaller(Class<JAXBTYPE> aType, IReadableResource aXSD) Constructor.
protected	AbstractJAXBMarshaller(Class<JAXBTYPE> aType, List<? extends IReadableResource> aXSDs) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
EChange	clearLastValidationErrors() Clear the latest parsing errors.
protected Schema	createValidationSchema()
protected void	customizeMarshaller(Marshaller aMarshaller) Customize the passed marshaller before marshalling something.
protected void	customizeUnmarshaller(Unmarshaller aUnmarshaller) Customize the passed unmarshaller before unmarshalling (reading) something.
String	getAsXMLString(JAXBTYPE aObject) Utility method to directly convert the passed domain object to an XML string.
CollectingValidationEventHandler	getCollectingValidationEventHandler() Get the last created collecting validation event handler.
IResourceErrorGroup	getLastValidationErrors() Get the parsing errors from the last read/write actions.
ValidationEventHandler	getLastValidationEventHandler() Get the last created validation event handler.
List<IReadableResource>	getOriginalXSDs()
IValidationEventHandlerFactory	getValidationEventHandlerFactory()
protected void	handleReadException(JAXBException ex)
protected void	handleWriteException(JAXBException ex)
boolean	isReadSecure()
boolean	isWriteFormatted()
JAXBTYPE	read(File aFile) Read a document from the specified file.
JAXBTYPE	read(InputStream aIS) Read a document from the specified input stream.
JAXBTYPE	read(IReadableResource aResource) Read a document from the specified resource.
JAXBTYPE	read(Node aNode) Read a document from the specified DOM node.
JAXBTYPE	read(Source aSource) Read a document from the specified source.
JAXBTYPE	read(String sXML) Read a document from the specified String.
EChange	setReadSecure(boolean bReadSecure) Enable or disable secure reading.
void	setValidationEventHandlerFactory(IValidationEventHandlerFactory aVEHFactory) Set another factory to be used to create ValidationEventHandler objects.
EChange	setWriteFormatted(boolean bWriteFormatted) Change the way formatting happens when calling write.
protected boolean	useJAXBContextCache() Should the JAXBContextCache be used?
protected abstract JAXBElement<JAXBTYPE>	wrapObject(JAXBTYPE aObject) Wrap the passed domain object into a JAXBElement for marshalling.
Document	write(JAXBTYPE aObject) Convert the passed object to a new DOM document
ESuccess	write(JAXBTYPE aObject, File aResultFile) Write the passed object to a File.
ESuccess	write(JAXBTYPE aObject, IWritableResource aResource) Write the passed object to an IWritableResource.
ESuccess	write(JAXBTYPE aObject, Result aResult) Convert the passed object to XML.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_READ_SECURE

public static final boolean DEFAULT_READ_SECURE

See Also:

Constant Field Values

DEFAULT_WRITE_FORMATTED

public static final boolean DEFAULT_WRITE_FORMATTED

See Also:

Constant Field Values

DEFAULT_FORMATTED

@Deprecated
public static final boolean DEFAULT_FORMATTED

Deprecated.

See Also:

Constant Field Values

Constructor Detail

AbstractJAXBMarshaller

protected AbstractJAXBMarshaller(@Nonnull
                      Class<JAXBTYPE> aType,
                      @Nullable
                      IReadableResource aXSD)

Constructor.

Parameters:

aType - The class of the JAXB document implementation type. May not be null.

aXSD - The XSD used to validate document. May be null indicating that no XSD check is needed.

AbstractJAXBMarshaller

protected AbstractJAXBMarshaller(@Nonnull
                      Class<JAXBTYPE> aType,
                      @Nullable
                      List<? extends IReadableResource> aXSDs)

Constructor.

Parameters:

aType - The class of the JAXB document implementation type. May not be null.

aXSDs - The XSDs used to validate document. May be null or empty indicating, that no XSD check is needed.

AbstractJAXBMarshaller

protected AbstractJAXBMarshaller(@Nonnull
                      Class<JAXBTYPE> aType,
                      @Nullable
                      IReadableResource... aXSDs)

Constructor.

Parameters:

aType - The class of the JAXB document implementation type. May not be null.

aXSDs - The XSDs used to validate document. May be null or empty indicating, that no XSD check is needed.

Method Detail

setValidationEventHandlerFactory

public final void setValidationEventHandlerFactory(@Nullable
                                    IValidationEventHandlerFactory aVEHFactory)

Set another factory to be used to create ValidationEventHandler objects. By default a CollectingLoggingValidationEventHandlerFactory is used.

Parameters:

aVEHFactory - The new factory to be used. May be null.

getValidationEventHandlerFactory

@Nullable
public final IValidationEventHandlerFactory getValidationEventHandlerFactory()

Returns:

The currently used validation event handler factory. By default an instance of CollectingLoggingValidationEventHandlerFactory is used. May be null if explicitly set.

getLastValidationEventHandler

@Nullable
public final ValidationEventHandler getLastValidationEventHandler()

Get the last created validation event handler. This may be required when collecting all errors using a CollectingValidationEventHandler.

Returns:

The last created validation event handler. Or null if none was created so far.

getCollectingValidationEventHandler

@Nullable
public final CollectingValidationEventHandler getCollectingValidationEventHandler()

Get the last created collecting validation event handler. This may be required when collecting all errors.

Returns:

The last created collecting validation event handler. Or null if none was created so far.

getLastValidationErrors

@Nullable
public final IResourceErrorGroup getLastValidationErrors()

Get the parsing errors from the last read/write actions. Works only if the last created validation event handler is a CollectingValidationEventHandler or wraps one.

Returns:

All events for evaluation or null in case no CollectingValidationEventHandler is present.

clearLastValidationErrors

@Nonnull
public final EChange clearLastValidationErrors()

Clear the latest parsing errors. Works only if the last created validation event handler is a CollectingValidationEventHandler or wraps one.

Returns:

EChange.CHANGED if a CollectingValidationEventHandler was found, and at least one element was removed from it.

setReadSecure

@Nonnull
public final EChange setReadSecure(boolean bReadSecure)

Enable or disable secure reading. Secure reading means that documents are checked for XXE and XML bombs (infinite entity expansions). By default secure reading is enabled.

Parameters:

bReadSecure - true to read secure, false to disable secure reading.

Returns:

EChange

isReadSecure

public final boolean isReadSecure()

setWriteFormatted

@Nonnull
public final EChange setWriteFormatted(boolean bWriteFormatted)

Change the way formatting happens when calling write.

Parameters:

bWriteFormatted - true to write formatted output.

Returns:

EChange

isWriteFormatted

public final boolean isWriteFormatted()

getOriginalXSDs

@Nonnull
@Nonempty
@ReturnsMutableCopy
public final List<IReadableResource> getOriginalXSDs()

Returns:

A list of all XSD resources used for validation. Never null.

useJAXBContextCache

@OverrideOnDemand
protected boolean useJAXBContextCache()

Should the JAXBContextCache be used? Since creating the JAXB context is quite cost intensive this is recommended.

Returns:

true if the JAXBContextCache should be used, false otherwise. It's true by default.

createValidationSchema

@Nullable
@OverrideOnDemand
protected Schema createValidationSchema()

Returns:

The validation schema to be used. May be null indicating that no validation is required.

read

@Nullable
public final JAXBTYPE read(@Nonnull
                     File aFile)

Read a document from the specified file. The secure reading feature has affect when using this method.

Parameters:

aFile - The file to read. May not be null.

Returns:

null in case reading fails.

read

@Nullable
public final JAXBTYPE read(@Nonnull
                     IReadableResource aResource)

Read a document from the specified resource. The secure reading feature has affect when using this method.

Parameters:

aResource - The resource to read. May not be null.

Returns:

null in case reading fails.

read

@Nullable
public final JAXBTYPE read(@Nonnull
                     InputStream aIS)

Read a document from the specified input stream. The secure reading feature has affect when using this method.

Parameters:

aIS - The input stream to read. May not be null.

Returns:

null in case reading fails.

read

@Nullable
public final JAXBTYPE read(@Nonnull
                     String sXML)

Read a document from the specified String. The secure reading feature has affect when using this method.

Parameters:

sXML - The XML string to read. May not be null.

Returns:

null in case reading fails.

read

@Nullable
public final JAXBTYPE read(@Nonnull
                     Node aNode)

Read a document from the specified DOM node. The secure reading feature has NO affect when using this method because no parsing happens! To ensure secure reading the Node must first be serialized to a String and be parsed again!

Parameters:

aNode - The DOM node to read. May not be null.

Returns:

null in case reading fails.

customizeUnmarshaller

@OverrideOnDemand
protected void customizeUnmarshaller(@Nonnull
                                          Unmarshaller aUnmarshaller)

Customize the passed unmarshaller before unmarshalling (reading) something.

Parameters:

aUnmarshaller - The object to customize. Never null.

handleReadException

@OverrideOnDemand
protected void handleReadException(@Nonnull
                                        JAXBException ex)

read

@Nullable
public final JAXBTYPE read(@Nonnull
                     Source aSource)

Read a document from the specified source. The secure reading feature has NO affect when using this method because the parameter type is too generic.

Parameters:

aSource - The source to read. May not be null.

Returns:

null in case reading fails.

wrapObject

@Nonnull
protected abstract JAXBElement<JAXBTYPE> wrapObject(@Nonnull
                                       JAXBTYPE aObject)

Wrap the passed domain object into a JAXBElement for marshalling. This can usually be done using the respective's package ObjectFactory implementation.

Parameters:

aObject - The object to be wrapped.

Returns:

The JAXBElement wrapping the document.

write

@Nullable
public final Document write(@Nonnull
                      JAXBTYPE aObject)

Convert the passed object to a new DOM document

Parameters:

aObject - The object to be converted. May not be null.

Returns:

null if converting the document failed.

write

@Nonnull
public final ESuccess write(@Nonnull
                     JAXBTYPE aObject,
                     @Nonnull
                     File aResultFile)

Write the passed object to a File.

Parameters:

aObject - The object to be written. May not be null.

aResultFile - The result file to be written to. May not be null.

Returns:

ESuccess

write

@Nonnull
public final ESuccess write(@Nonnull
                     JAXBTYPE aObject,
                     @Nonnull
                     IWritableResource aResource)

Write the passed object to an IWritableResource.

Parameters:

aObject - The object to be written. May not be null.

aResource - The result resource to be written to. May not be null.

Returns:

ESuccess

customizeMarshaller

@OverrideOnDemand
protected void customizeMarshaller(@Nonnull
                                        Marshaller aMarshaller)

Customize the passed marshaller before marshalling something.

Parameters:

aMarshaller - The object to customize. Never null.

handleWriteException

@OverrideOnDemand
protected void handleWriteException(@Nonnull
                                         JAXBException ex)

write

@Nonnull
public final ESuccess write(@Nonnull
                     JAXBTYPE aObject,
                     @Nonnull
                     Result aResult)

Convert the passed object to XML.

Parameters:

aObject - The object to be converted. May not be null.

aResult - The result object holder. May not be null.

Returns:

ESuccess

getAsXMLString

@Nullable
public final String getAsXMLString(@Nonnull
                             JAXBTYPE aObject)

Utility method to directly convert the passed domain object to an XML string.

Parameters:

aObject - The domain object to be converted. May not be null.

Returns:

null if the passed domain object could not be converted because of validation errors.