com.im.df.api.util.xml
Class BasicPersister<T>

java.lang.Object
  com.im.df.api.util.xml.BasicPersister<T>

All Implemented Interfaces:

BasicPersisterInit, StateFactory, StateFactory.Reader, StateFactory.Writer, Cloneable

public class BasicPersister<T>
extends Object
implements StateFactory, BasicPersisterInit, StateFactory.Reader, StateFactory.Writer, Cloneable

Additional property attributes: staticType - FQN of the type (default: property.getPropertyType) items - FQN of the item type (default: Object) keys - FQN of the key type values - FQN of the key type

Nested Class Summary

Nested classes/interfaces inherited from interface com.im.df.api.util.xml.StateFactory

StateFactory.EnvReporter, StateFactory.FinishableBean, StateFactory.Reader, StateFactory.Writer

Constructor Summary

BasicPersister()

Method Summary

protected void	addError(IOException err)
protected boolean	canInstantiate(Class valueClazz)
protected void	clearErrors()
Object	create(Object o)
Attr	createAttribute(String name)
Element	createElement(String name)
T	createInstance(Lookup context, QName qName)
protected Object	createInstance(Object o) Default implementation: will create an instance using reflection.
protected Logger	createLog()
StateFactory.Reader	createReader(Lookup context, Class expectedType, Node parent, DFEnvironmentRO env) Reader factory.
Element	createState(Object bean, Node parent)
StateFactory.Writer	createWriter(Lookup context, Object bean, DFEnvironmentRO env) Writer factory.
protected void	defaultReadBean()
void	defaultWriteBean() Iterates through BeanInfo and writes all property values
protected void	enterElement(Element e, Lookup context) Enter the specified element and make it current.
protected Element	enterElement(String name, Lookup context) For readers: enter the named element, and establish the supplied Context.
protected Attr	getAttribute() Returns the current attribute being written to or read from
protected String	getAttribute(PropertyDescriptor pd, String propName, String attr) Helper methods to retrieving metadata.
protected T	getBean() The bean instance being written or read
protected Class	getBeanClass()
List<IOException>	getBufferedErrors()
protected Class	getClass(String name) A helper method to retrieve a Class object without throwing a CNFE.
protected QName	getConfiguredQName()
protected Lookup	getContext() Retrieves the current context.
protected static ClassLoader	getCurrentClassLoader()
DFEnvironmentRO	getEnv()
protected Node	getNode() Retrieves the current Node
protected Object	getPropertyValue(PropertyDescriptor property) Helper method to retrieve property's value.
QName	getQName(Object bean)
protected Element	getStorage() Returns the current element being written to or read from
Class	getType(Node n) Returns the class, used to register this Persister, as the type for all handled nodes.
StateFactory	init() Initializes the persister.
boolean	isPrimitive(Class clazz) The Basic persister does not support primitive serialization, as it works with beans with [multiple] properties.
protected void	leaveElement() Leave the element entered using enterElement(java.lang.String, org.openide.util.Lookup).
protected Object	loadObject(Class clazz, Node loadFrom, Object prototype) Loads an object from the specified Node (attribute or element).
protected void	popElement() Pops an element.
protected Element	pushElement(String name) Generates an element and makes it "current", so write* helper methods will all use it.
Object	read(String name, Object prototype)
boolean	readAttr(String name, boolean defValue)
int	readAttr(String name, int defValue)
String	readAttr(String name, String defValue)
protected Object	readAttribute(Object prototype)
protected void	readBeanProperties()
protected void	readBeanProperty(PropertyDescriptor pd)
protected Collection	readCollection(Class implClazz, Class itemType, String name, String itemName, Collection prototype)
protected Collection	readCollection(Class implClazz, Class itemType, String name, String itemName, Collection prototype, boolean throwOnMissing) Reads a collection of items.
protected Object	readCollectionProperty(PropertyDescriptor pd)
protected Object	readElement(Object prototype)
protected Object	readMap(Class implClazz, Class keyType, Class valType, String name, String itemName, Map prototype)
protected Object	readMapProperty(PropertyDescriptor pd)
protected Object	readObjectPolymorphic(String childName, Object prototype)
protected Object	readObjectStatic(Class type, String name, Object prototype) Reads a statically-typed Object from the current element.
protected Object	readPrimitiveProperty(PropertyDescriptor pd)
protected void	setBean(T bean) Sets the bean instance.
void	setBeanClass(Class clazz)
void	setClassBeanInfo(BeanInfo classBeanInfo)
protected void	setContext(Lookup context) Sets a new context.
void	setEnv(DFEnvironmentRO env)
protected void	setNode(Node n)
void	setPropertyAttributes(Map<String,String> propertyAttributes)
void	setQName(QName qName)
protected void	setStorage(Element storage) Sets the current element to a specific node.
protected void	storeObject(Element storeTo, Object val) Stores object directly in the specified element (not in its sub-elements).
protected void	throwWrappedIOException(String reason, Throwable cause)
protected void	throwWrappedIOException(Throwable cause)
void	write(String name, int value)
Node	write(String name, Node n) Writes the bean either into an Attribute, or to an Element.
void	write(String name, String value)
protected void	writeArray(PropertyDescriptor pd, String name, String itemName, Object[] val) Writes an array of objects
void	writeAttr(String name, boolean value, boolean defValue)
void	writeAttr(String name, int value)
void	writeAttr(String name, int value, int defValue)
void	writeAttr(String name, String value)
void	writeAttr(String name, String value, String defValue)
protected void	writeAttribute() The basic bean persister does not support primitive writing
protected void	writeCollection(Class staticType, String name, String itemName, Collection val)
protected void	writeCollection(Class staticType, String name, String itemName, Enumeration val) Writes an enumeration property.
protected void	writeCollection(PropertyDescriptor pd, String itemName, Collection val) Writes a collection property
protected void	writeElement() This default implementation will invoke defaultWriteBean, which outputs all properties described by the class' BeanInfo
protected void	writeMap(Class keyType, Class valueType, String name, String itemName, Map val)
protected void	writeMap(PropertyDescriptor pd, String itemName, Map val)
protected void	writeObject(Class implType, String name, Object val) Persist an object under the given name.
protected void	writeObjectPolymorphic(String name, Object val) Writes an object in a way that permits reconstruction of subclasses of the data type on reading.
protected void	writeObjectStatic(String name, Object val) Writes a static content of an object, as an attribute or an element, depending on the object's persister capabilities.
void	writeProperty(PropertyDescriptor property) Write a value described by the property descriptor.
protected void	writeSuperclass(Element where) This method will find and delegate to a superclass persister.

Methods inherited from class java.lang.Object

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

Constructor Detail

BasicPersister

public BasicPersister()

Method Detail

setClassBeanInfo

public void setClassBeanInfo(BeanInfo classBeanInfo)

Specified by:

setClassBeanInfo in interface BasicPersisterInit

setPropertyAttributes

public void setPropertyAttributes(Map<String,String> propertyAttributes)

Specified by:

setPropertyAttributes in interface BasicPersisterInit

setQName

public void setQName(QName qName)

Specified by:

setQName in interface BasicPersisterInit

setBeanClass

public void setBeanClass(Class clazz)
                  throws IntrospectionException

Specified by:

setBeanClass in interface BasicPersisterInit

Throws:

IntrospectionException

createLog

protected Logger createLog()

addError

protected void addError(IOException err)

clearErrors

protected void clearErrors()

getBufferedErrors

public List<IOException> getBufferedErrors()

getEnv

public DFEnvironmentRO getEnv()

setEnv

public void setEnv(DFEnvironmentRO env)

getCurrentClassLoader

protected static ClassLoader getCurrentClassLoader()

init

public StateFactory init()

Initializes the persister. To be overriden by subclasses instead of the constructor, as the BasicBeanPersisters are instantiated using reflection :)

Specified by:

init in interface BasicPersisterInit

pushElement

protected Element pushElement(String name)

Generates an element and makes it "current", so write* helper methods will all use it. Do not forget to call popElement() counterpart when done with the pushed element's contents.

enterElement

protected Element enterElement(String name,
                               Lookup context)

For readers: enter the named element, and establish the supplied Context. Helper read* methods will read from that element and if they delegate, they will use the context.

enterElement

protected void enterElement(Element e,
                            Lookup context)

Enter the specified element and make it current. If Lookup is specified, the current context is changed to that Lookup. If null is given as a lookup, the current Lookup is retained. To clear the Lookup, pass in Lookup.EMPTY instance.

leaveElement

protected void leaveElement()

Leave the element entered using enterElement(java.lang.String, org.openide.util.Lookup). The method also pops the Lookup context out of the stack.

getAttribute

protected final String getAttribute(PropertyDescriptor pd,
                                    String propName,
                                    String attr)

Helper methods to retrieving metadata. Metadata can be either stored as a named value in the BeanInfo or, if it is not feasible to change, the persister's propertyAttributesMap can contain the value under key "%". If none of the maps contains the requested attribute, null will be returned.

popElement

protected void popElement()

Pops an element. Use as a counterpart for pushElement(java.lang.String) when persisting the bean.

setBean

protected void setBean(T bean)

Sets the bean instance. Use this method early in write implementation, so all other state methods can work with the bean. When reading, set the bean as soon as the result object is constructed.

getBean

protected final T getBean()

The bean instance being written or read

getBeanClass

protected Class getBeanClass()

Returns:

The class of the bean that will be deserialized

setStorage

protected void setStorage(Element storage)

Sets the current element to a specific node. The method will reset the attribute property.

setNode

protected void setNode(Node n)

getAttribute

protected Attr getAttribute()

Returns the current attribute being written to or read from

getStorage

protected final Element getStorage()

Returns the current element being written to or read from

setContext

protected void setContext(Lookup context)

Sets a new context. This method should be used just for setting up the persister; otherwise, push and pop methods should be used to manipulate synchronously with the element and context stacks.

getContext

protected final Lookup getContext()

Retrieves the current context. Context can be used by the persister to discover its environment, to bind the deserialized bean to. Also it can be used by the serializer to discover which information is implicitly available in the environment (e.g. serializing a field within its Entity only requires the field ID - if the Entity instance is in the environment)

createWriter

public StateFactory.Writer createWriter(Lookup context,
                                        Object bean,
                                        DFEnvironmentRO env)

Writer factory. It clones self, and initializes the context and the bean being written.

Specified by:

createWriter in interface StateFactory

createReader

public StateFactory.Reader createReader(Lookup context,
                                        Class expectedType,
                                        Node parent,
                                        DFEnvironmentRO env)

Reader factory. It clones itself and initializes the context, and the current XML Node

Specified by:

createReader in interface StateFactory

isPrimitive

public boolean isPrimitive(Class clazz)

The Basic persister does not support primitive serialization, as it works with beans with [multiple] properties. Subclasses tailored specifically for certain bean may override this.

Specified by:

isPrimitive in interface StateFactory

Returns:

If true, the Factory is willing to write to an attribute

getType

public Class getType(Node n)

Returns the class, used to register this Persister, as the type for all handled nodes.

Specified by:

getType in interface StateFactory

Returns:

The type of the bean to be deserialized

getNode

protected Node getNode()

Retrieves the current Node

write

public final Node write(String name,
                        Node n)
                 throws IOException

Writes the bean either into an Attribute, or to an Element. If the passed Node is an attribute, it will try to persist the bean calling writeAttribute(). If the persister does not support primitive writing, a child element named "name" will be created to hold the bean's state. If the passed Node is an element, the bean's state is always stored to that element. Element is written by calling writeElement() overridable.

Specified by:

write in interface StateFactory.Writer

Parameters:

name - The name

n - The node

Returns:

The node

Throws:

IOException

writeAttribute

protected void writeAttribute()
                       throws IOException

The basic bean persister does not support primitive writing

Throws:

IOException

writeElement

protected void writeElement()
                     throws IOException

This default implementation will invoke defaultWriteBean, which outputs all properties described by the class' BeanInfo

Throws:

IOException

defaultWriteBean

public void defaultWriteBean()
                      throws IOException

Iterates through BeanInfo and writes all property values

Throws:

IOException

getPropertyValue

protected Object getPropertyValue(PropertyDescriptor property)
                           throws IOException

Helper method to retrieve property's value. All reflection exceptions are wrapped into IOExceptions

Throws:

IOException

writeProperty

public void writeProperty(PropertyDescriptor property)
                   throws IOException

Write a value described by the property descriptor. Primitives, arrays and collections are handled specially. If the bean is a generic object, the static type information from the BeanInfo's value map is used to determine whether it can be written without type information.

Throws:

IOException

getClass

protected Class getClass(String name)

A helper method to retrieve a Class object without throwing a CNFE. CNFE is expected in this case. The passed name may be null (null will be returned).

writeCollection

protected void writeCollection(Class staticType,
                               String name,
                               String itemName,
                               Enumeration val)
                        throws IOException

Writes an enumeration property. It may surround the entire collection in a wrapper element (named "name"). Each item will be either named "itemName" (if the parameter is not null), or the default name "item" will be used. If the static type is not known in advance, the object will be written in a typed way - no default name item name will be used, as the collection only contains its items, no other elements.

Parameters:

staticType - The element type, if static

name - The name of the wrapper element

itemName - The name of the "item" element where item information will be stored.

val - The enumeration of elements to be stored.

Throws:

IOException

writeMap

protected void writeMap(Class keyType,
                        Class valueType,
                        String name,
                        String itemName,
                        Map val)
                 throws IOException

Throws:

IOException

writeCollection

protected void writeCollection(Class staticType,
                               String name,
                               String itemName,
                               Collection val)
                        throws IOException

Throws:

IOException

canInstantiate

protected boolean canInstantiate(Class valueClazz)

writeCollection

protected void writeCollection(PropertyDescriptor pd,
                               String itemName,
                               Collection val)
                        throws IOException

Writes a collection property

Throws:

IOException

writeMap

protected void writeMap(PropertyDescriptor pd,
                        String itemName,
                        Map val)
                 throws IOException

Throws:

IOException

writeArray

protected void writeArray(PropertyDescriptor pd,
                          String name,
                          String itemName,
                          Object[] val)
                   throws IOException

Writes an array of objects

Throws:

IOException

writeObject

protected final void writeObject(Class implType,
                                 String name,
                                 Object val)
                          throws IOException

Persist an object under the given name. The object may be written as an attribute, or an sub-element, if the implementation type is known (statically). If the implementation type is not known in advance, the object must be written as a dynamic content, using sub-element with proper tagname and namespace URI which allows to locate the appropriate persister on deserialization. Note that dynamically typed objects cannot be stored as attributes.

Parameters:

implType - The static type, or null if the type may vary (e.g. subclasses might be used)

name - The attribute/child element name

val - The object

Throws:

IOException

writeObjectPolymorphic

protected final void writeObjectPolymorphic(String name,
                                            Object val)
                                     throws IOException

Writes an object in a way that permits reconstruction of subclasses of the data type on reading. Such objects must be read using readObjectPolymorphic(java.lang.String, java.lang.Object), and are stored as a child element "name", whose sole child is a {namespace}tagname element defined by the value persister. Alternatively, the typed object's typed element is appended as a direct child, if the passed name is null.

Throws:

IOException

writeObjectStatic

protected final void writeObjectStatic(String name,
                                       Object val)
                                throws IOException

Writes a static content of an object, as an attribute or an element, depending on the object's persister capabilities. Note that this object must be restored by readObjectStatic(java.lang.Class, java.lang.String, java.lang.Object), using the specific class.

Parameters:

name - The name of the element or attribute

val - The object

Throws:

IOException

loadObject

protected Object loadObject(Class clazz,
                            Node loadFrom,
                            Object prototype)
                     throws IOException

Loads an object from the specified Node (attribute or element). A prototype instance may be passed to populate with state or clone.

Throws:

IOException

storeObject

protected void storeObject(Element storeTo,
                           Object val)
                    throws IOException

Stores object directly in the specified element (not in its sub-elements). This is useful when a parent wants to annotate the child with additional properties

Throws:

IOException

createElement

public Element createElement(String name)

createAttribute

public Attr createAttribute(String name)

writeAttr

public void writeAttr(String name,
                      int value,
                      int defValue)

writeAttr

public void writeAttr(String name,
                      int value)

writeAttr

public void writeAttr(String name,
                      boolean value,
                      boolean defValue)

write

public void write(String name,
                  int value)

writeAttr

public void writeAttr(String name,
                      String value,
                      String defValue)

writeAttr

public void writeAttr(String name,
                      String value)

readAttr

public int readAttr(String name,
                    int defValue)

readAttr

public String readAttr(String name,
                       String defValue)

readAttr

public boolean readAttr(String name,
                        boolean defValue)

write

public void write(String name,
                  String value)

createInstance

public T createInstance(Lookup context,
                        QName qName)
                 throws IOException

Throws:

IOException

writeSuperclass

protected void writeSuperclass(Element where)
                        throws IOException

This method will find and delegate to a superclass persister.

Throws:

IOException

getQName

public QName getQName(Object bean)

Specified by:

getQName in interface StateFactory

Returns:

QName of the element to be created

getConfiguredQName

protected QName getConfiguredQName()

createState

public Element createState(Object bean,
                           Node parent)

create

public Object create(Object o)
              throws IOException

Specified by:

create in interface StateFactory.Reader

Throws:

IOException

createInstance

protected Object createInstance(Object o)
                         throws IOException

Default implementation: will create an instance using reflection. If the passed prototype is not null, and is assignable to the persister's bean class, the prototype object will be returned instead of a new instance. Nothing will be created if the bean does not have a default constructor.

Throws:

IOException

read

public final Object read(String name,
                         Object prototype)
                  throws IOException

Specified by:

read in interface StateFactory.Reader

Throws:

IOException

readElement

protected Object readElement(Object prototype)
                      throws IOException

Throws:

IOException

readAttribute

protected Object readAttribute(Object prototype)
                        throws IOException

Throws:

IOException

readObjectStatic

protected Object readObjectStatic(Class type,
                                  String name,
                                  Object prototype)
                           throws IOException

Reads a statically-typed Object from the current element. It may load the object from a sub-element or an attribute, depending on the object's registered Persister

Throws:

IOException

defaultReadBean

protected void defaultReadBean()
                        throws IOException

Throws:

IOException

readBeanProperties

protected void readBeanProperties()
                           throws IOException

Throws:

IOException

readBeanProperty

protected void readBeanProperty(PropertyDescriptor pd)
                         throws IOException

Throws:

IOException

readObjectPolymorphic

protected Object readObjectPolymorphic(String childName,
                                       Object prototype)
                                throws IOException

Throws:

IOException

throwWrappedIOException

protected void throwWrappedIOException(String reason,
                                       Throwable cause)
                                throws IOException

Throws:

IOException

throwWrappedIOException

protected void throwWrappedIOException(Throwable cause)
                                throws IOException

Throws:

IOException

readCollection

protected Collection readCollection(Class implClazz,
                                    Class itemType,
                                    String name,
                                    String itemName,
                                    Collection prototype)
                             throws IOException

Throws:

IOException

readCollection

protected Collection readCollection(Class implClazz,
                                    Class itemType,
                                    String name,
                                    String itemName,
                                    Collection prototype,
                                    boolean throwOnMissing)
                             throws IOException

Reads a collection of items. If an item cannot be read, the whole operation fails with an exception. If the 'prototype' is not null, the method will read into that prototype collection instance rather than create a new instance. 'implClazz' provides a Class type of collection to be created. If the type is null or is an interface an ArrayList is instantiated. 'itemType' specifies the base type to be read - Persister for that type will be used to read the items. If not provided, the persister will be looked up according to the item's DOM element name.

Parameters:

implClazz - The type of the collection, or null when prototype is present

itemType - The type of the item, or null for polymorphic lookup

name - The name of the wrapper DOM element, null if no wrapper

itemName - NOT USED !??!

prototype - The prototype collection instance

Returns:

The deserialized Collection

Throws:

IOException

readCollectionProperty

protected Object readCollectionProperty(PropertyDescriptor pd)
                                 throws IOException

Throws:

IOException

readMapProperty

protected Object readMapProperty(PropertyDescriptor pd)
                          throws IOException

Throws:

IOException

readMap

protected Object readMap(Class implClazz,
                         Class keyType,
                         Class valType,
                         String name,
                         String itemName,
                         Map prototype)
                  throws IOException

Throws:

IOException

readPrimitiveProperty

protected Object readPrimitiveProperty(PropertyDescriptor pd)
                                throws IOException

Throws:

IOException