public final class BR.unicamp.Guarana.Guarana

java.lang.Object
   |
   +----BR.unicamp.Guarana.Guarana

public final class Guarana

This class provides the implementation of the kernel of Guarana. It provides methods for setting up meta-configurations and for communication between the base level and the meta level. This class, as well as Operation and Result, are the only special classes in Guarana, in the sense that they cannot be made reflexive at all. Instances of Operation and Result cannot ever be made reflexive either. This would break security constraints, by allowing its MetaObjects to obtain references to MetaObjects associated with base-level Objects, or to break restrictions imposed by OperationFactories.

This protection could have been implemented by associating suitable MetaObjects to those classes, so that no such security holes can be opened. However, this would have serious performance impact. Since we couldn't find any good reason to make any of these classes or objects reflexive, we decided not to pay that additional cost. If we ever find a good reason to make any of these classes reflexive, we may change this constraint.

broadcast(Message, Object)

This method asks the MetaObject associated with the given Object to handle the presented

getClass(Object)

Obtains the most derived Class an Object belongs to

getClassName(Class)

Obtains the name of a Class

hashCode(Object)

Obtains the address of memory where the Object is stored, which is the standard hashCode of

makeProxy(Class, MetaObject)

Creates an unitialized Object, broadcasts a NewObject Message to the Class' MetaObject, and

perform(Operation)

Whenever an operation is intercepted in the base level, it is reified and presented to the

reconfigure(Object, MetaObject, MetaObject)

This is a reconfiguration request

toString(Object)

Obtains a String that contains the Object's class name and address.

public static Result perform(Operation operation)
  throws MetaException;

Whenever an operation is intercepted in the base level, it is reified and presented to the MetaObject by the invocation of this method. It does implement exactly the protocol described in the general description of a MetaObject.

Just before delivering the Operation to the target Object, we check whether the primary MetaObject is no longer the one that was originally asked to handle it. If there was any change, Result.throwObject(null) is presented to the MetaObject that was originally asked to handle the Operation, and the handling is restarted with the new MetaObject.

If the MetaObject is unchanged, the operation will be validated and delivered. If the validate method throws, the thrown Object will be considered the Result of the Operation.

This Result will be presented to the Object's MetaObject, if it asked so.

Parameters:

operation - the Operation reified from the base level.

Returns:

the Result to be returned back to the base level.

Throws:

MetaException -if any Exception propagates from the execution of either Operation or Result handling methods.

IllegalArgumentException -if the Operation was already performed, or it is a replacement Operation.

See also:

MetaObject , validate

broadcast

public static void broadcast(Message message,
                             Object object);

This method asks the MetaObject associated with the given Object to handle the presented Message. If the object is not associated with any MetaObject, nothing is done.

Parameters:

message - the Message to be sent to the Object's meta-level.

object - the object whose MetaObject should receive the Message.

reconfigure

public static void reconfigure(Object object,
                               MetaObject oldMetaObject,
                               MetaObject newMetaObject);

This is a reconfiguration request. The caller wants the newMetaObject to occupy the place of the oldMetaObject in the meta-configuration of the given Object.

This Operation is a do-nothing if the given Object is either the class Guarana, the class Operation, the class Result, or any instace thereof, since these are non-reflexive classes.

This method ensures that any top-level reconfiguration is atomic, by synchronizing either on the current primary MetaObject associated with the Object or on the object's class, and checking whether the MetaObject associated with the Object hasn't changed. If it has, the operation is restarted.

As soon as it makes sure there's no other thread reconfiguring the given Object, it sends the reconfigure request to the current MetaObject. If the current MetaObject was null, but the oldMetaObject was not, the request is ignored, but if the oldMetaObject was null too, an InstanceReconfigure Message is created and broadcasted to the meta-configuration of the Object's class, then to its superclass, and so on. After the InstanceReconfigure Message is broadcasted to the meta-configuration of class java.lang.Object, the MetaObject stored in the InstanceReconfigure Message is used as the new primary MetaObject.

Finally, if the returned MetaObject is different from the current MetaObject, and the current MetaObject is still the primary MetaObject, the returned MetaObject is initialized and associated with the Object, and then the previous primary MetaObject is told to release the Object.

If, at any point after the execution of method reconfigure and before the execution of method release, the primary MetaObject is found to have changed (which means that the execution of either reconfigure or initialize caused the MetaObject to change), the reconfiguration is considered terminated.

There's no standard way to check whether the reconfiguration succeeded, since the new MetaObject may have been accepted but guarded under a Composer controlled by the existing MetaObject, or it may have been rejected at all, or it may have been reconfigured before being accepted, so that the previous meta-configuration remains. The only way to check whether the MetaObject was actually accepted is to Broadcast a Message after the Reconfiguration finishes.

Parameters:

object - the Object whose meta-configuration is to be changed.

oldMetaObject - the MetaObject to be replaced, or null, which means the current MetaObject.

newMetaObject - the MetaObject intended to be associated with the Object.

See also:

broadcast , Message

makeProxy

public static native Object makeProxy(Class cls,
                                      MetaObject metaObject)
  throws MetaException;

Creates an unitialized Object, broadcasts a NewObject Message to the Class' MetaObject, and tries to associate the given MetaObject with the uninitialized Object. An unitialized Objects is useful for representing Objects in other address spaces, reinstantiating persistent Objects, to migrating, copying or replicating Objects, etc. Since such Objects usually represent other Objects, they'll be called proxies, and the NewObject Message that will be broadcasted to the Class' MetaObject is in fact a NewProxy Message, an instance of a subclass of class NewObject.

A MetaObject associated with a proxy Object should not allow messages to be delivered to an uninitialized proxy Object. In fact, this applied to any Object before it is constructed, but proxy Object are seldom constructed at all. If they are, or if their fields are all properly initialized, they may be considered actual Objects.

The following pseudo-code depicts the behavior of this method. The static pseudo-method <alloc> is assumed to allocate an uninitialized Object, or an array of length 0, if the given Class is an array type. For arrays of non-zero lengths, method newInstance of class java.lang.reflect.Array must be used.

---

 if (cls.isPrimitive() ||
     cls == Guarana.class ||
     cls == Operation.class ||
     cls == Result.class)
   throw new IllegalArgumentException
     ("cannot create proxy of non-reflexive class");
 Object object = <alloc>(cls);
 broadcast(new NewProxy(object), cls);
 if (metaObject != null)
   reconfigure(object, null, metaObject);
 return object;
	

---

The meta-configuration of a Class may refuse to accept the instantiation of pseudo-Objects by throwing a MetaException when broadcasted the NewProxy Message. It may also create a meta-configuration for the new Object that rejects or modifies the proposed meta-configuration.

Parameters:

cls - the Class whose pseudo-instance is to be created.

metaObject - the MetaObject to be associated with the new proxy Object.

Returns:

the created proxy Object, or null, if the given class is a primitive type or a non-reflexive class, such as Guarana, Operation, Result.

Throws:

MetaException -may be propagated out from the execution of either reconfigure or broadcast.

See also:

NewProxy

hashCode

public static native int hashCode(Object object);

Obtains the address of memory where the Object is stored, which is the standard hashCode of an Object. Note that this method does not invoke any method of the given object, so it is useful for meta-level objects to find out information about base-level ones.

Parameters:

object - the Object whose address is to be returned.

Returns:

the address of the given Object.

getClass

public static native Class getClass(Object object);

Obtains the most derived Class an Object belongs to. Note that this method does not invoke any method of the given object, so it is useful for meta-level objects to find out information about base-level ones.

Parameters:

object - the Object whose Class is to be returned.

Returns:

the Class the given object belongs to.

getClassName

public static native String getClassName(Class clazz);

Obtains the name of a Class. Note that this method does not invoke any method of the given class, so it is useful for meta-level objects to find out information about classes of base-level objects.

Parameters:

object - the Class whose name is to be returned.

Returns:

the name of the given Class.

toString

public static String toString(Object object);

Obtains a String that contains the Object's class name and address.

Parameters:

object - the Object whose String representation is wanted.

Returns:

a String that contains the Object Class name, an `@' sign and the object address in hexa-decimal notation.

BR.unicamp.Guarana.Guarana.html