Package org.zkoss.zkex.xml

Class PersistenceService

java.lang.Object
org.zkoss.zkex.xml.PersistenceService
public class PersistenceService extends Object
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 initialiser 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)serialisation, even OutOfMemoryErrors.

This class is designed to be thread safe, i.e. when an object is persistet, it is put into a synchronized (object) { ... } block.

Author:
Christian Schlichtherle
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static int
    BUFSIZE
    The buffer size for I/O used in the store and load methods.
    static final int
    DEFAULT_BUFSIZE
    10KB - the default buffer size for buffered I/O.
    static final String
    XML_CHARSET
    "UTF-8" - the character encoding used by XMLEncoder and XMLDecoder.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    PersistenceService()
    You cannot instantiate this class.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected static void
    installPersistenceDelegates(Encoder encoder)
    Installs all persistence delegates registered via {@link #setPersistenceDelegate(Class, PersistenceDelegate)} in encoder.
    static Object
    load(byte[] encoded)
    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.
    static Object
    load(File file)
    Loads a single object, which may form the root of an entire object graph, from XML content in the given file file.
    static Object
    load(InputStream xmlIn)
    Loads a single object, which may form the root of an entire object graph, from XML content in the given input stream xmlIn.
    static Object
    load(String encoded)
    Loads a single object, which may form the root of an entire object graph, from XML content in the string encoded.
    static final void
    setPersistenceDelegate(Class clazz, PersistenceDelegate persistenceDelegate)
    Associates a PersistenceDelegate to the given class type.
    static void
    store(Object root, File file)
    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.
    static void
    store(Object root, OutputStream xmlOut)
    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.
    static byte[]
    store2ByteArray(Object root)
    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.
    static String
    store2String(Object root)
    Stores the object root, which may form the root of an entire object graph, as XML content into a string for long term persistence.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • 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 DEFAULT_BUFSIZE.

    • XML_CHARSET

      static final String XML_CHARSET
      "UTF-8" - the character encoding used by XMLEncoder and XMLDecoder.
      See Also:

    • DEFAULT_BUFSIZE

      static final int DEFAULT_BUFSIZE
      10KB - the default buffer size for buffered I/O.
      See Also:

  • Constructor Details

    • PersistenceService

      protected PersistenceService()
      You cannot instantiate this class.

  • Method Details

    • 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, the best place to put this call in is a static initializer block for the corresponding class.

      Here is an example: 

            class PersistentObject {
          static {
              PersistenceService.setPersistenceDelegate(
                  PersistentObject.class,
                  new DefaultPersistenceDelegate(
                      new String[] { "property" }));
          }

          public int property;

          public PersistentObject(int property) {
              this.property = property;
          }
      }

      Note that you should not use this method for any class which's source code you can control. The preferred way to associate a persistence delegate with a class is to write a BeanInfo class which's BeanDescriptor 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:

    • 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:
      RuntimeException - if encoder is null.

    • store

      public static void store(Object root, OutputStream xmlOut) throws NullPointerException, 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 serialisation. Its cause is always set.

    • store

      public static void store(Object root, File file) throws NullPointerException, 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 serialisation. Its cause is always set.

    • 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 serialisation. Its cause is always set.

    • 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 serialisation. Its cause is always set.

    • load

      public static Object load(InputStream xmlIn) throws NullPointerException, 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 serialisation. Its cause is always set.

    • load

      public static Object load(File file) throws NullPointerException, 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 serialisation. Its cause is always set.

    • load

      public static Object load(byte[] encoded) throws NullPointerException, 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 serialisation. Its cause is always set.

    • load

      public static Object load(String encoded) throws NullPointerException, 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 serialisation. Its cause is always set.