de.schlichtherle.xml
Class PersistenceService

java.lang.Object
  de.schlichtherle.xml.PersistenceService

All Implemented Interfaces:

XMLConstants

public class PersistenceService
extends Object
implements XMLConstants

Provides a collection of static methods to support comfortable loading and storing of objects as XML data.

This class uses the classes XMLEncoder and XMLDecoder to encode and decode an object to and from an XML file for long term persistence. It allows you to provide custom PersistenceDelegate instances for the serialisation of any classes which do not implement the JavaBean design pattern and are not supported by XMLEncoder as a default.

For the latter case, PersistenceService offers the setPersistenceDelegate(Class, PersistenceDelegate) method which could be called from a static initializer block in the class which would like to use PersistenceService's store and load methods.

Note that the Java API already provides some default persistence delegates for some classes of its API which are not JavaBeans. If in doubt, simply test the class before writing a custom PersistenceDelegate. If you see exceptions happening, you most probably need to provide a PersistenceDelegate and use the setPersistenceDelegate method to install it.

Note that the store and load methods in this class have been designed to deal with any kind of Throwables throughout the course of (de)serialization, even OutOfMemoryErrors.

This class is thread.safe.

Author:

Christian Schlichtherle

See Also:

XMLEncoder, XMLDecoder, PersistenceDelegate, DefaultPersistenceDelegate, Sun Developer Network Site: Using XMLEncoder

allPDs

private static final HashMap allPDs

This map maps from Class instances to PersistenceDelegate instances. Its elements are installed in the XMLEncoder prior to encoding an object.

BUFSIZE

public static int BUFSIZE

The buffer size for I/O used in the store and load methods. You may customise this to your needs - the default is XMLConstants.DEFAULT_BUFSIZE.

PersistenceService

private PersistenceService()

You cannot instantiate this class.

createExceptionListener

private static final ExceptionListener createExceptionListener()

Returns an ExceptionListener. This custom exception listener enforces zero tolerance when encoding or decoding objects to or from XML files in order not to compromise the integrity of an object.

getRenamedFile

private static File getRenamedFile(File plainFile)

installPersistenceDelegates

protected static void installPersistenceDelegates(Encoder encoder)

Installs all persistence delegates registered via {@link #setPersistenceDelegate(Class, PersistenceDelegate)} in encoder.

Parameters:

encoder - the encoder - may not be null.

Throws:

NullPointerException - if encoder is null.

load

public static Object load(byte[] encoded)
                   throws PersistenceServiceException

Loads a single object, which may form the root of an entire object graph, from XML content in the UTF-8 encoded byte array encoded.

Please note the following:

• This method will not tolerate any I/O or other deserialisation exceptions!

Parameters:

encoded - the XML with UTF-8 charset encoded byte array representation of the root of an object graph - may not be null.

Returns:

The root of the loaded object graph - may be null.

Throws:

NullPointerException - if encoded is null.

PersistenceServiceException - if any throwable was thrown during serialization.

load

public static Object load(File file)
                   throws PersistenceServiceException

Loads a single object, which may form the root of an entire object graph, from XML content in the given file file.

Please note the following:

• This method will not tolerate any I/O or other deserialisation exceptions!

Parameters:

file - the file to load the XML content from - may not be null.

Returns:

The root of the loaded object graph - may be null.

Throws:

NullPointerException - if file is null.

PersistenceServiceException - if any throwable was thrown during serialization.

load

public static Object load(InputStream xmlIn)
                   throws PersistenceServiceException

Loads a single object, which may form the root of an entire object graph, from XML content in the given input stream xmlIn.

Please note the following:

• The stream is connected to a new BufferedInputStream with BUFSIZE as its buffer size and is always closed (even if an exception is thrown).
• This method will not tolerate any I/O or other deserialisation exceptions!

Parameters:

xmlIn - the unbuffered stream to input the XML content - may not be null.

Returns:

The root of the loaded object graph - may be null.

Throws:

NullPointerException - if xmlIn is null.

PersistenceServiceException - if any throwable was thrown during serialization.

load

public static Object load(String encoded)
                   throws PersistenceServiceException

Loads a single object, which may form the root of an entire object graph, from XML content in the string encoded.

Please note the following:

• This method will not tolerate any I/O or other deserialisation exceptions!

Parameters:

encoded - the XML string encoded representation of the root of an object graph - may not be null.

Returns:

The root of the loaded object graph - may be null.

Throws:

NullPointerException - if encoded is null.

PersistenceServiceException - if any throwable was thrown during serialization.

setPersistenceDelegate

public static final void setPersistenceDelegate(Class clazz,
                                                PersistenceDelegate persistenceDelegate)

Associates a PersistenceDelegate to the given class type.

This must be called prior to the store methods for each class which's instances are to be persisted. Thus, a good place to make this call is in a static initializer block for the corresponding class. Here is an example: <pre> class PersistentObject { static { PersistenceService.setPersistenceDelegate( PersistentObject.class, new DefaultPersistenceDelegate( new String[] { "property" })); } public int property; public PersistentObject(int property) { this.property = property; } } </pre>

Note that you should not use this method for any class where you can control the source code. The preferred way to associate a persistence delegate with a class is to write a BeanInfo class with a BeanDescriptor which has an attribute set with "persistenceDelegate" as its name and the respective persistence delegate as its value (see Encoder.getPersistenceDelegate(java.lang.Class)). However, this method is still useful in case you can't control the source code, as then at least you can still associate a persistence delegate to this class.

See Also:

XMLEncoder, PersistenceDelegate, DefaultPersistenceDelegate

store

public static void store(Object root,
                         File file)
                  throws PersistenceServiceException

Stores the object root, which may form the root of an entire object graph, as XML content to the file file for long term persistence. This method supports writing to a file located in a ZIP or JAR file.

Please note the following:

• This method will not tolerate any I/O or other serialisation exceptions!
• This is a transaction, i.e. the method either completely succeeds with saving the file or the file is restored to its original state.

Parameters:

root - the object to store - may be null.

file - the file to output the XML content to - may not be null.

Throws:

NullPointerException - if file is null.

PersistenceServiceException - if any throwable was thrown during serialization.

store

public static void store(Object root,
                         OutputStream xmlOut)
                  throws PersistenceServiceException

Stores the object root, which may form the root of an entire object graph, as XML content to the output stream xmlOut for long term persistence.

Please note the following:

• This method will not tolerate any I/O or other serialisation exceptions!
• The underlying stream is always closed (even if an exception is thrown).

Parameters:

root - the object to store - may be null.

xmlOut - the unbuffered stream to output the XML content - may not be null.

Throws:

NullPointerException - if xmlOut is }null}.

PersistenceServiceException - if any throwable was thrown during serialization.

store2ByteArray

public static byte[] store2ByteArray(Object root)
                              throws PersistenceServiceException

Stores the object root, which may form the root of an entire object graph, as XML content into a UTF-8 encoded byte array for long term persistence.

Please note the following:

• This method will not tolerate any I/O or other serialisation exceptions!

Parameters:

root - the object to store - may be null.

Returns:

The XML with UTF-8 charset encoded byte array representation of root - null is never returned.

Throws:

PersistenceServiceException - if any throwable was thrown during serialization.

store2String

public static String store2String(Object root)
                           throws PersistenceServiceException

Stores the object root, which may form the root of an entire object graph, as XML content into a string for long term persistence.

Please note the following:

• This method will not tolerate any I/O or other serialisation exceptions!

Parameters:

root - the object to store - may be null.

Returns:

The XML string encoded representation of root - null is never returned.

Throws:

PersistenceServiceException - if any throwable was thrown during serialization.