FileDocCategorySizeDatePackage
Encoder.javaAPI DocJava SE 6 API11073Tue Jun 10 00:25:30 BST 2008java.beans

Encoder

public class Encoder extends Object
An Encoder is a class which can be used to create files or streams that encode the state of a collection of JavaBeans in terms of their public APIs. The Encoder, in conjunction with its persistence delegates, is responsible for breaking the object graph down into a series of Statementss and Expressions which can be used to create it. A subclass typically provides a syntax for these expressions using some human readable form - like Java source code or XML.
since
1.4
version
1.3 11/15/00
author
Philip Milne

Fields Summary
private Map
bindings
private ExceptionListener
exceptionListener
boolean
executeStatements
private Map
attributes
Constructors Summary
Methods Summary
voidclear()

 
        bindings.clear(); 
    
private java.beans.StatementcloneStatement(java.beans.Statement oldExp)

 
        Object oldTarget = oldExp.getTarget(); 
        Object newTarget = writeObject1(oldTarget); 
                
        Object[] oldArgs = oldExp.getArguments(); 
        Object[] newArgs = new Object[oldArgs.length]; 
        for (int i = 0; i < oldArgs.length; i++) { 
            newArgs[i] = writeObject1(oldArgs[i]);
        }
        if (oldExp.getClass() == Statement.class) { 
            return new Statement(newTarget, oldExp.getMethodName(), newArgs); 
        }
        else { 
            return new Expression(newTarget, oldExp.getMethodName(), newArgs); 
        }
    
public java.lang.Objectget(java.lang.Object oldInstance)
Returns a tentative value for oldInstance in the environment created by this stream. A persistence delegate can use its mutatesTo method to determine whether this value may be initialized to form the equivalent object at the output or whether a new object must be instantiated afresh. If the stream has not yet seen this value, null is returned.

param
oldInstance The instance to be looked up.
return
The object, null if the object has not been seen before.

 
        if (oldInstance == null || oldInstance == this || 
	    oldInstance.getClass() == String.class) { 
            return oldInstance; 
        }
        Expression exp = (Expression)bindings.get(oldInstance); 
        return getValue(exp); 
    
java.lang.ObjectgetAttribute(java.lang.Object key)

	if (attributes == null) {
	    return null;
	}
	return attributes.get(key);
    
public java.beans.ExceptionListenergetExceptionListener()
Gets the exception handler for this stream.

return
The exception handler for this stream; Will return the default exception listener if this has not explicitly been set.
see
#setExceptionListener

 
        return (exceptionListener != null) ? exceptionListener : Statement.defaultExceptionListener;
    
public java.beans.PersistenceDelegategetPersistenceDelegate(java.lang.Class type)
Returns the persistence delegate for the given type. The persistence delegate is calculated by applying the following of rules in order:
  • If the type is an array, an internal persistence delegate is returned which will instantiate an array of the appropriate type and length, initializing each of its elements as if they are properties.
  • If the type is a proxy, an internal persistence delegate is returned which will instantiate a new proxy instance using the static "newProxyInstance" method defined in the Proxy class.
  • If the BeanInfo for this type has a BeanDescriptor which defined a "persistenceDelegate" property, this value is returned.
  • In all other cases the default persistence delegate is returned. The default persistence delegate assumes the type is a JavaBean, implying that it has a default constructor and that its state may be characterized by the matching pairs of "setter" and "getter" methods returned by the Introspector. The default constructor is the constructor with the greatest number of parameters that has the {@link ConstructorProperties} annotation. If none of the constructors have the {@code ConstructorProperties} annotation, then the nullary constructor (constructor with no parameters) will be used. For example, in the following the nullary constructor for {@code Foo} will be used, while the two parameter constructor for {@code Bar} will be used. public class Foo { public Foo() { ... } public Foo(int x) { ... } } public class Bar { public Bar() { ... }

    ConstructorProperties({"x"})
    public Bar(int x) { ... }
    ConstructorProperties({"x",
    "y"}) public Bar(int x, int y) { ... } }
    param
    type The type of the object.
    return
    The persistence delegate for this type of object.
    see
    #setPersistenceDelegate
    see
    java.beans.Introspector#getBeanInfo
    see
    java.beans.BeanInfo#getBeanDescriptor

     
            return MetaData.getPersistenceDelegate(type); 
        
java.lang.ObjectgetValue(java.beans.Expression exp)

 
        try { 
            return (exp == null) ? null : exp.getValue(); 
        }
        catch (Exception e) { 
            getExceptionListener().exceptionThrown(e); 
            throw new RuntimeException("failed to evaluate: " + exp.toString()); 
        }
    
public java.lang.Objectremove(java.lang.Object oldInstance)
Removes the entry for this instance, returning the old entry.

param
oldInstance The entry that should be removed.
return
The entry that was removed.
see
#get

 
        Expression exp = (Expression)bindings.remove(oldInstance); 
        return getValue(exp); 
    
voidsetAttribute(java.lang.Object key, java.lang.Object value)

	if (attributes == null) {
	    attributes = new HashMap();
	}
	attributes.put(key, value);
    
public voidsetExceptionListener(java.beans.ExceptionListener exceptionListener)
Sets the exception handler for this stream to exceptionListener. The exception handler is notified when this stream catches recoverable exceptions.

param
exceptionListener The exception handler for this stream; if null the default exception listener will be used.
see
#getExceptionListener

 
        this.exceptionListener = exceptionListener; 
    
public voidsetPersistenceDelegate(java.lang.Class type, java.beans.PersistenceDelegate persistenceDelegate)
Sets the persistence delegate associated with this type to persistenceDelegate.

param
type The class of objects that persistenceDelegate applies to.
param
persistenceDelegate The persistence delegate for instances of type.
see
#getPersistenceDelegate
see
java.beans.Introspector#getBeanInfo
see
java.beans.BeanInfo#getBeanDescriptor

        MetaData.setPersistenceDelegate(type, persistenceDelegate); 
    
public voidwriteExpression(java.beans.Expression oldExp)
The implementation first checks to see if an expression with this value has already been written. If not, the expression is cloned, using the same procedure as writeStatement, and the value of this expression is reconciled with the value of the cloned expression by calling writeObject.

param
oldExp The expression to be written to the stream.

 
        // System.out.println("Encoder::writeExpression: " + oldExp); 
        Object oldValue = getValue(oldExp); 
        if (get(oldValue) != null) {  
            return; 
        }
        bindings.put(oldValue, (Expression)cloneStatement(oldExp)); 
        writeObject(oldValue); 
    
protected voidwriteObject(java.lang.Object o)
Write the specified object to the output stream. The serialized form will denote a series of expressions, the combined effect of which will create an equivalent object when the input stream is read. By default, the object is assumed to be a JavaBean with a nullary constructor, whose state is defined by the matching pairs of "setter" and "getter" methods returned by the Introspector.

param
o The object to be written to the stream.
see
XMLDecoder#readObject


                                                                                                 
         
    	if (o == this) { 
    	    return; 
        }
        PersistenceDelegate info = getPersistenceDelegate(o == null ? null : o.getClass()); 
        info.writeObject(o, this); 
    
private java.lang.ObjectwriteObject1(java.lang.Object oldInstance)

 
        Object o = get(oldInstance); 
        if (o == null) {  
            writeObject(oldInstance);   
            o = get(oldInstance);
        }        
        return o; 
    
public voidwriteStatement(java.beans.Statement oldStm)
Writes statement oldStm to the stream. The oldStm should be written entirely in terms of the callers environment, i.e. the target and all arguments should be part of the object graph being written. These expressions represent a series of "what happened" expressions which tell the output stream how to produce an object graph like the original.

The implementation of this method will produce a second expression to represent the same expression in an environment that will exist when the stream is read. This is achieved simply by calling writeObject on the target and all the arguments and building a new expression with the results.

param
oldStm The expression to be written to the stream.

 
        // System.out.println("writeStatement: " + oldExp); 
        Statement newStm = cloneStatement(oldStm); 
        if (oldStm.getTarget() != this && executeStatements) { 
	    try { 
		newStm.execute(); 
	    } catch (Exception e) { 
		getExceptionListener().exceptionThrown(new Exception("Encoder: discarding statement " 
								     + newStm, e)); 
	    }
        }