java.lang.Object
- org.zkoss.chart.lic.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:

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 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(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 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 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 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(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:
    
    XMLEncoder, PersistenceDelegate, DefaultPersistenceDelegate
  - 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.

Class PersistenceService

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BUFSIZE

XML_CHARSET

DEFAULT_BUFSIZE

Constructor Detail

PersistenceService

Method Detail

setPersistenceDelegate

installPersistenceDelegates

store

store

store2ByteArray

store2String

load

load

load

load