Package org.zkoss.zkex.xml

Class PersistenceService

  • public class PersistenceService
extends java.lang.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:
    XMLEncoder, XMLDecoder, PersistenceDelegate, DefaultPersistenceDelegate, Sun Developer Network Site: Using XMLEncoder

    • 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 int DEFAULT_BUFSIZE
      10KB - the default buffer size for buffered I/O.
      static java.lang.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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      protected static void installPersistenceDelegates​(java.beans.Encoder encoder)
      Installs all persistence delegates registered via {@link #setPersistenceDelegate(Class, PersistenceDelegate)} in encoder.
      static java.lang.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 java.lang.Object load​(java.io.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 java.lang.Object load​(java.io.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 java.lang.Object load​(java.lang.String encoded)
      Loads a single object, which may form the root of an entire object graph, from XML content in the string encoded.
      static void setPersistenceDelegate​(java.lang.Class clazz, java.beans.PersistenceDelegate persistenceDelegate)
      Associates a PersistenceDelegate to the given class type.
      static void store​(java.lang.Object root, java.io.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​(java.lang.Object root, java.io.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​(java.lang.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 java.lang.String store2String​(java.lang.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 Detail

      • 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

        public static final java.lang.String XML_CHARSET
        "UTF-8" - the character encoding used by XMLEncoder and XMLDecoder.
        See Also:
        Constant Field Values

      • DEFAULT_BUFSIZE

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

    • Constructor Detail

      • PersistenceService

        protected PersistenceService()
        You cannot instantiate this class.

    • Method Detail

      • setPersistenceDelegate

        public static final void setPersistenceDelegate​(java.lang.Class clazz,
                                                java.beans.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:
        XMLEncoder, PersistenceDelegate, DefaultPersistenceDelegate

      • installPersistenceDelegates

        protected static void installPersistenceDelegates​(java.beans.Encoder encoder)
        Installs all persistence delegates registered via {@link #setPersistenceDelegate(Class, PersistenceDelegate)} in encoder.
        Parameters:
        encoder - The encoder - may not be null.
        Throws:
        java.lang.RuntimeException - if encoder is null.

      • store

        public static void store​(java.lang.Object root,
                         java.io.OutputStream xmlOut)
                  throws java.lang.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:
        java.lang.NullPointerException - If xmlOut is }null}.
        PersistenceServiceException - If any throwable was thrown during serialisation. Its cause is always set.

      • store

        public static void store​(java.lang.Object root,
                         java.io.File file)
                  throws java.lang.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:
        java.lang.NullPointerException - If file is }null}.
        PersistenceServiceException - If any throwable was thrown during serialisation. Its cause is always set.

      • store2ByteArray

        public static byte[] store2ByteArray​(java.lang.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 java.lang.String store2String​(java.lang.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 java.lang.Object load​(java.io.InputStream xmlIn)
                             throws java.lang.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:
        java.lang.NullPointerException - If xmlIn is null.
        PersistenceServiceException - If any throwable was thrown during serialisation. Its cause is always set.

      • load

        public static java.lang.Object load​(java.io.File file)
                             throws java.lang.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:
        java.lang.NullPointerException - If file is null.
        PersistenceServiceException - If any throwable was thrown during serialisation. Its cause is always set.

      • load

        public static java.lang.Object load​(byte[] encoded)
                             throws java.lang.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:
        java.lang.NullPointerException - If encoded is null.
        PersistenceServiceException - If any throwable was thrown during serialisation. Its cause is always set.

      • load

        public static java.lang.Object load​(java.lang.String encoded)
                             throws java.lang.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:
        java.lang.NullPointerException - If encoded is null.
        PersistenceServiceException - If any throwable was thrown during serialisation. Its cause is always set.