com.googlecode.openbeans
Class Encoder

java.lang.Object
  com.googlecode.openbeans.Encoder

Direct Known Subclasses:

XMLEncoder

public class Encoder
extends Object

The Encoder, together with PersistenceDelegate s, can encode an object into a series of java statements. By executing these statements, a new object can be created and it will has the same state as the original object which has been passed to the encoder. Here "has the same state" means the two objects are indistinguishable from their public API.

The Encoder and PersistenceDelegate s do this by creating copies of the input object and all objects it references. The copy process continues recursively util every object in the object graph has its new copy and the new version has the same state as the old version. All statements used to create those new objects and executed on them during the process form the result of encoding.

Constructor Summary

Encoder()
Construct a new encoder.

Method Summary

Object	get(Object old) Gets the new copy of the given old object.
ExceptionListener	getExceptionListener() Returns the exception listener of this encoder.
PersistenceDelegate	getPersistenceDelegate(Class<?> type) Returns a PersistenceDelegate for the given class type.
Object	remove(Object old) Remove the existing new copy of the given old object.
void	setExceptionListener(ExceptionListener listener) Sets the exception listener of this encoder.
void	setPersistenceDelegate(Class<?> type, PersistenceDelegate delegate) Register the PersistenceDelegate of the specified type.
void	writeExpression(Expression oldExp) Write an expression of old objects.
protected void	writeObject(Object o) Encode the given object into a series of statements and expressions.
void	writeStatement(Statement oldStat) Write a statement of old objects.

Methods inherited from class java.lang.Object

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

Constructor Detail

Encoder

public Encoder()

Construct a new encoder.

Method Detail

get

public Object get(Object old)

Gets the new copy of the given old object.

Strings are special objects which have their new copy by default, so if the old object is a string, it is returned directly.

Parameters:

old - an old object

Returns:

the new copy of the given old object, or null if there is not one.

getExceptionListener

public ExceptionListener getExceptionListener()

Returns the exception listener of this encoder.

An encoder always have a non-null exception listener. A default exception listener is used when the encoder is created.

Returns:

the exception listener of this encoder

getPersistenceDelegate

public PersistenceDelegate getPersistenceDelegate(Class<?> type)

Returns a PersistenceDelegate for the given class type.

The PersistenceDelegate is determined as following:

1. If a PersistenceDelegate has been registered by calling setPersistenceDelegate for the given type, it is returned.
2. If the given type is an array class, a special PersistenceDelegate for array types is returned.
3. If the given type is a proxy class, a special PersistenceDelegate for proxy classes is returned.
4. Introspector is used to check the bean descriptor value "persistenceDelegate". If one is set, it is returned.
5. If none of the above applies, the DefaultPersistenceDelegate is returned.

Parameters:

type - a class type

Returns:

a PersistenceDelegate for the given class type

remove

public Object remove(Object old)

Remove the existing new copy of the given old object.

Parameters:

old - an old object

Returns:

the removed new version of the old object, or null if there is not one

setExceptionListener

public void setExceptionListener(ExceptionListener listener)

Sets the exception listener of this encoder.

Parameters:

listener - the exception listener to set

setPersistenceDelegate

public void setPersistenceDelegate(Class<?> type,
                                   PersistenceDelegate delegate)

Register the PersistenceDelegate of the specified type.

Parameters:

type -

delegate -

writeExpression

public void writeExpression(Expression oldExp)

Write an expression of old objects.

The implementation first check the return value of the expression. If there exists a new version of the object, simply return.

A new expression is created using the new versions of the target and the arguments. If any of the old objects do not have its new version yet, writeObject() is called to create the new version.

The new expression is then executed to obtained a new copy of the old return value.

Call writeObject() with the old return value, so that more statements will be executed on its new version to change it into the same state as the old value.

Parameters:

oldExp - the expression to write. The target, arguments, and return value of the expression are all old objects.

writeObject

protected void writeObject(Object o)

Encode the given object into a series of statements and expressions.

The implementation simply finds the PersistenceDelegate responsible for the object's class, and delegate the call to it.

Parameters:

o - the object to encode

writeStatement

public void writeStatement(Statement oldStat)

Write a statement of old objects.

A new statement is created by using the new versions of the target and arguments. If any of the objects do not have its new copy yet, writeObject() is called to create one.

The new statement is then executed to change the state of the new object.

Parameters:

oldStat - a statement of old objects