edu.vub.at.actors.natives
Class NATFarReference

java.lang.Object
  edu.vub.at.objects.natives.NATNil
      edu.vub.at.objects.natives.NATByCopy
          edu.vub.at.actors.natives.NATFarReference

All Implemented Interfaces:

ATAbstractGrammar, ATConversions, ATExpression, ATFarReference, ATNil, ATObject, ATStatement, java.io.Serializable

Direct Known Subclasses:

NATLocalFarRef, NATRemoteFarRef

public abstract class NATFarReference

extends NATByCopy

implements ATFarReference

NATFarReference is the root of the native classes that represent native far references. The AmbientTalk/2 implementation distinguishes between two kinds of far references: local and remote far references. The former denote far references to objects hosted by actors on the same virtual machine. The latter ones denote far references to remote objects that are hosted on a separate virtual (and usually even physical) machine. This abstract superclass encapsulates all of the code that these two kinds of far references have in common. The variabilities are delegated to the subclasses. Subclasses should implement an abstract method (transmit) which is invoked by this class when the far reference receives a message to be forwarded to the remote principal. Note that far references are pass by copy and resolve to either a near or a new actor-local far reference. Far references encapsulate the same stripes as the remote object they represent. As such it becomes possible to perform a stripe test on a far reference as if it was performed on the local object itself!

Author:

tvcutsem, smostinc

See Also:

Serialized Form

Nested Class Summary

static class	NATFarReference.NATDisconnectionSubscription
static class	NATFarReference.NATReconnectionSubscription

Field Summary

private ATObjectID	objectId_
private ATStripe[]	stripes_

Fields inherited from class edu.vub.at.objects.natives.NATNil

_INSTANCE_

Constructor Summary

protected

NATFarReference(ATObjectID objectId, ATStripe[] stripes)

Method Summary

NATFarReference	asNativeFarReference()
ATFarReference	base_asFarReference()
boolean	base_isFarReference()
ATObjectID	getObjectId()
ATNil	meta_addField(ATField field) Adds a field slot to an object at runtime.
ATNil	meta_addMethod(ATMethod method) Adds a method slot to an object at runtime.
ATNil	meta_assignField(ATObject receiver, ATSymbol name, ATObject value) Sets the value of a field to the given value.
ATNil	meta_assignVariable(ATSymbol name, ATObject value) Sets the value of the variable to the given value.
ATObject	meta_clone() References to objects hosted by another actor are forced to be unique.
ATNil	meta_defineField(ATSymbol name, ATObject value) Defines a new field in an object.
ATObject	meta_doesNotUnderstand(ATSymbol selector) Called when a selection fails because the selector was not found along the dynamic delegation hierarchy.
ATObject	meta_extend(ATClosure code) TODO(discuss) Think about extending objects of another actor.
ATObject	meta_getDynamicParent() Objects have a classical dynamic parent chain created using extension primitives.
ATObject	meta_getLexicalParent() Objects also have a lexical parent which is the scope in which their definitions are nested.
ATTable	meta_getStripes() The stripes of a far reference are the stripes of the remote object it points to, plus the FarReference stripe.
ATField	meta_grabField(ATSymbol fieldName) Queries an object for one of its field slots.
ATMethod	meta_grabMethod(ATSymbol methodName) Queries an object for one of its method slots.
ATObject	meta_invoke(ATObject receiver, ATSymbol atSelector, ATTable arguments) Invoke a method corresponding to the selector with the given arguments.
ATBoolean	meta_isCloneOf(ATObject original) Detects whether this object an the passed parameter are the result of cloning from a common ancestor (possibly either one of the objects itself).
ATBoolean	meta_isRelatedTo(ATObject object) Detects whether both objects have a common origin, in other words whether they are related through a combination of the cloning and extension operators.
ATTable	meta_listFields() Queries an object for a list of all of its field slots.
ATTable	meta_listMethods() Queries an object for a list of all of its method slots.
ATObject	meta_lookup(ATSymbol selector) Select a slot (field | method) from an object whose name corresponds to the given selector.
ATObject	meta_newInstance(ATTable initargs) Cannot create a new instance using a farObject, this should be done either by sending rather than invoking new(args) such that the correct method is triggered or by invoking newInstance on a farMirror, which will send the call as well.
NATText	meta_print() Prints out the object in a human-readable way.
ATObject	meta_receive(ATAsyncMessage message) Handles a first-class message of which it is the receiver.
ATObject	meta_resolve() After deserialization, ensure that only one unique remote reference exists for my target.
ATBoolean	meta_respondsTo(ATSymbol atSelector) Query an object for a given field or method which is visible to the outside world.
ATObject	meta_select(ATObject receiver, ATSymbol selector) Select a slot (field | method) from an object whose name corresponds to the given selector.
ATObject	meta_share(ATClosure code) TODO(discuss) Think about sharing objects of another actor.
protected abstract ATObject	transmit(ATAsyncMessage passedMessage)

Methods inherited from class edu.vub.at.objects.natives.NATByCopy

meta_pass

Methods inherited from class edu.vub.at.objects.natives.NATNil

asAmbientTalkObject, asJavaClassUnderSymbiosis, asJavaObjectUnderSymbiosis, asNativeBoolean, asNativeException, asNativeFraction, asNativeNumber, asNativeNumeric, asNativeTable, asNativeText, base__opeql__opeql_, base_asActorMirror, base_asAsyncMessage, base_asBegin, base_asBoolean, base_asClosure, base_asDefinition, base_asExpression, base_asField, base_asHandler, base_asMessage, base_asMessageCreation, base_asMethod, base_asMirror, base_asNumber, base_asSplice, base_asStatement, base_asStripe, base_asSymbol, base_asTable, base_asUnquoteSplice, base_asVariableAssignment, base_init, base_isBoolean, base_isCallFrame, base_isClosure, base_isMessageCreation, base_isMethod, base_isMirror, base_isSplice, base_isStripe, base_isSymbol, base_isTable, base_isUnquoteSplice, base_isVariableAssignment, base_new, createChild, equals, isAmbientTalkObject, isJavaObjectUnderSymbiosis, isNativeBoolean, isNativeField, isNativeText, meta_eval, meta_isStripedWith, meta_quote, meta_send, readResolve, toString, writeReplace

Methods inherited from class java.lang.Object

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

Methods inherited from interface edu.vub.at.actors.ATFarReference

meta_retractUnsentMessages

Methods inherited from interface edu.vub.at.objects.ATObject

base__opeql__opeql_, base_init, base_new, meta_eval, meta_isStripedWith, meta_pass, meta_quote, meta_send

Methods inherited from interface edu.vub.at.objects.coercion.ATConversions

asAmbientTalkObject, asJavaClassUnderSymbiosis, asJavaObjectUnderSymbiosis, asNativeBoolean, asNativeException, asNativeFraction, asNativeNumber, asNativeNumeric, asNativeTable, asNativeText, base_asActorMirror, base_asAsyncMessage, base_asBegin, base_asBoolean, base_asClosure, base_asDefinition, base_asExpression, base_asField, base_asHandler, base_asMessage, base_asMessageCreation, base_asMethod, base_asMirror, base_asNumber, base_asSplice, base_asStatement, base_asStripe, base_asSymbol, base_asTable, base_asUnquoteSplice, base_asVariableAssignment, base_isBoolean, base_isCallFrame, base_isClosure, base_isMessageCreation, base_isMethod, base_isMirror, base_isSplice, base_isStripe, base_isSymbol, base_isTable, base_isUnquoteSplice, base_isVariableAssignment, isAmbientTalkObject, isJavaObjectUnderSymbiosis, isNativeBoolean, isNativeField, isNativeText

Field Detail

objectId_

private final ATObjectID objectId_

stripes_

private final ATStripe[] stripes_

Constructor Detail

NATFarReference

protected NATFarReference(ATObjectID objectId,
                          ATStripe[] stripes)

Method Detail

getObjectId

public ATObjectID getObjectId()

asNativeFarReference

public NATFarReference asNativeFarReference()
                                     throws XTypeMismatch

Specified by:

asNativeFarReference in interface ATConversions

Overrides:

asNativeFarReference in class NATNil

Throws:

XTypeMismatch

meta_resolve

public ATObject meta_resolve()
                      throws InterpreterException

After deserialization, ensure that only one unique remote reference exists for my target.

Specified by:

meta_resolve in interface ATObject

Overrides:

meta_resolve in class NATByCopy

Throws:

InterpreterException

meta_receive

public ATObject meta_receive(ATAsyncMessage message)
                      throws InterpreterException

Description copied from interface: ATObject

Handles a first-class message of which it is the receiver.

Specified by:

meta_receive in interface ATObject

Overrides:

meta_receive in class NATNil

Throws:

InterpreterException

transmit

protected abstract ATObject transmit(ATAsyncMessage passedMessage)
                              throws InterpreterException

Throws:

InterpreterException

meta_invoke

public ATObject meta_invoke(ATObject receiver,
                            ATSymbol atSelector,
                            ATTable arguments)
                     throws InterpreterException

Description copied from interface: ATObject

Invoke a method corresponding to the selector with the given arguments. The selector is looked up along the dynamic delegation chain. The first argument, 'receiver', denotes the receiver of the method invocation.

Specified by:

meta_invoke in interface ATObject

Overrides:

meta_invoke in class NATNil

Throws:

XIllegalOperation - Cannot synchronously invoke a method on a far reference

InterpreterException

meta_respondsTo

public ATBoolean meta_respondsTo(ATSymbol atSelector)
                          throws InterpreterException

Description copied from interface: ATObject

Query an object for a given field or method which is visible to the outside world. Only methods in the dynamic parent chain are considered.

Specified by:

meta_respondsTo in interface ATObject

Overrides:

meta_respondsTo in class NATNil

Returns:

true if and only if the far object is queried for responses to basic operations such as ==

Throws:

InterpreterException

meta_doesNotUnderstand

public ATObject meta_doesNotUnderstand(ATSymbol selector)
                                throws InterpreterException

Description copied from interface: ATObject

Called when a selection fails because the selector was not found along the dynamic delegation hierarchy. Note the differences with Smalltalk's well-known 'doesNotUnderstand': - dNU is a meta-level operation in AmbientTalk; it is applied to mirrors. - dNU relates to attribute selection, not to method invocation. Hence, dNU in AmbientTalk is more general: it can be used to model 'virtual' fields by returning a value and it can be used to model 'virtual' methods by returning a block closure.

Specified by:

meta_doesNotUnderstand in interface ATObject

Overrides:

meta_doesNotUnderstand in class NATNil

Throws:

XSelectorNotFound - to ensure proper semantics should the interpreter be extended such that it allows extending a far reference in the future.

InterpreterException

meta_clone

public ATObject meta_clone()
                    throws InterpreterException

References to objects hosted by another actor are forced to be unique. Therefore cloning them throws an XIllegalOperation to avoid inconsistencies by performing state updates (through sent messages) after a clone operation. TODO(discuss) clone: farObject may create a clone on the other actor.

Specified by:

meta_clone in interface ATObject

Overrides:

meta_clone in class NATNil

Throws:

InterpreterException

meta_newInstance

public ATObject meta_newInstance(ATTable initargs)
                          throws InterpreterException

Cannot create a new instance using a farObject, this should be done either by sending rather than invoking new(args) such that the correct method is triggered or by invoking newInstance on a farMirror, which will send the call as well.

Specified by:

meta_newInstance in interface ATObject

Overrides:

meta_newInstance in class NATNil

Throws:

InterpreterException

meta_extend

public ATObject meta_extend(ATClosure code)
                     throws InterpreterException

TODO(discuss) Think about extending objects of another actor. The result should be a far reference, although the child object may be hosted on your actor. This enforces correct use of the sending operation the only concern is then to check no super invocations are made by the child.

Specified by:

meta_extend in interface ATObject

Overrides:

meta_extend in class NATNil

Throws:

InterpreterException

meta_share

public ATObject meta_share(ATClosure code)
                    throws InterpreterException

TODO(discuss) Think about sharing objects of another actor. The result should be a far reference, although the child object may be hosted on your actor. This enforces correct use of the sending operation the only concern is then to check no super invocations are made by the child.

Specified by:

meta_share in interface ATObject

Overrides:

meta_share in class NATNil

Throws:

InterpreterException

meta_select

public ATObject meta_select(ATObject receiver,
                            ATSymbol selector)
                     throws InterpreterException

Description copied from interface: ATObject

Select a slot (field | method) from an object whose name corresponds to the given selector. The slot lookup follows the dynamic delegation chain. Like with method invocation, slot selection is parameterized by the 'original receiver'. This original receiver is equal to 'this' the first time it is called. Via delegation, 'this' may instead be a dynamic parent of 'receiver'. When a method is selected from an object, it is wrapped in a closure such that the 'self' is properly preserved.

Specified by:

meta_select in interface ATObject

Overrides:

meta_select in class NATNil

Throws:

XIllegalOperation - - cannot select in objects hosted by another actor.

InterpreterException

meta_lookup

public ATObject meta_lookup(ATSymbol selector)
                     throws InterpreterException

Description copied from interface: ATObject

Select a slot (field | method) from an object whose name corresponds to the given selector. The slot lookup follows the lexical nesting chain. When a method is found in an object, it is wrapped in a closure such that the 'self' is properly preserved.

Specified by:

meta_lookup in interface ATObject

Overrides:

meta_lookup in class NATNil

Throws:

XIllegalOperation - - cannot lookup in objects hosted by another actor.

InterpreterException

meta_defineField

public ATNil meta_defineField(ATSymbol name,
                              ATObject value)
                       throws InterpreterException

Description copied from interface: ATObject

Defines a new field in an object.

Specified by:

meta_defineField in interface ATObject

Overrides:

meta_defineField in class NATNil

Throws:

XIllegalOperation - - cannot define in objects hosted by another actor.

InterpreterException

meta_assignField

public ATNil meta_assignField(ATObject receiver,
                              ATSymbol name,
                              ATObject value)
                       throws InterpreterException

Description copied from interface: ATObject

Sets the value of a field to the given value. Triggers the fieldAssigned event on this object's beholders (mirror observers). Field assignment may result in the assignment of a parent's field.

Specified by:

meta_assignField in interface ATObject

Overrides:

meta_assignField in class NATNil

Throws:

XIllegalOperation - - cannot assign in objects hosted by another actor.

InterpreterException

meta_assignVariable

public ATNil meta_assignVariable(ATSymbol name,
                                 ATObject value)
                          throws InterpreterException

Description copied from interface: ATObject

Sets the value of the variable to the given value. Triggers the fieldAssigned event on this object's beholders (mirror observers). Normally, a variable assignment can only be triggered from within the lexical scope of an object.

Specified by:

meta_assignVariable in interface ATObject

Overrides:

meta_assignVariable in class NATNil

Throws:

XIllegalOperation - - cannot assign in objects hosted by another actor.

InterpreterException

meta_isCloneOf

public ATBoolean meta_isCloneOf(ATObject original)
                         throws InterpreterException

Description copied from interface: ATObject

Detects whether this object an the passed parameter are the result of cloning from a common ancestor (possibly either one of the objects itself).

Specified by:

meta_isCloneOf in interface ATObject

Overrides:

meta_isCloneOf in class NATNil

Returns:

false unless this == original

Throws:

InterpreterException

meta_isRelatedTo

public ATBoolean meta_isRelatedTo(ATObject object)
                           throws InterpreterException

Description copied from interface: ATObject

Detects whether both objects have a common origin, in other words whether they are related through a combination of the cloning and extension operators.

Specified by:

meta_isRelatedTo in interface ATObject

Overrides:

meta_isRelatedTo in class NATNil

Returns:

false unless this == original

Throws:

InterpreterException

meta_addField

public ATNil meta_addField(ATField field)
                    throws InterpreterException

Description copied from interface: ATObject

Adds a field slot to an object at runtime. Triggers the fieldAdded event on this object's beholders (mirror observers) if the field is added successfully.

Specified by:

meta_addField in interface ATObject

Overrides:

meta_addField in class NATNil

Throws:

XIllegalOperation - - cannot add fields to an object in another actor.

InterpreterException

meta_addMethod

public ATNil meta_addMethod(ATMethod method)
                     throws InterpreterException

Description copied from interface: ATObject

Adds a method slot to an object at runtime. Triggers the methodAdded event on this object's beholders (mirror observers) if the method is added successfully.

Specified by:

meta_addMethod in interface ATObject

Overrides:

meta_addMethod in class NATNil

Throws:

XIllegalOperation - - cannot add methods to an object in another actor.

InterpreterException

meta_grabField

public ATField meta_grabField(ATSymbol fieldName)
                       throws InterpreterException

Description copied from interface: ATObject

Queries an object for one of its field slots. Triggers the fieldAccessed event on this object's beholders (mirror observers).

Specified by:

meta_grabField in interface ATObject

Overrides:

meta_grabField in class NATNil

Throws:

XSelectorNotFound - - as the far object has no fields of its own

InterpreterException

meta_grabMethod

public ATMethod meta_grabMethod(ATSymbol methodName)
                         throws InterpreterException

Description copied from interface: ATObject

Queries an object for one of its method slots. Triggers the methodAccessed event on this object's beholders (mirror observers).

Specified by:

meta_grabMethod in interface ATObject

Overrides:

meta_grabMethod in class NATNil

Returns:

a method if and only if the requested selector is a default operator such as ==

Throws:

XSelectorNotFound - otherwise

InterpreterException

meta_listFields

public ATTable meta_listFields()
                        throws InterpreterException

Description copied from interface: ATObject

Queries an object for a list of all of its field slots. TODO(beholders) should this method trigger beholders? if so, using a single 'fieldsQueried' event or by invoking 'fieldAccessed' for each field in the list returned?

Specified by:

meta_listFields in interface ATObject

Overrides:

meta_listFields in class NATNil

Returns:

an empty table

Throws:

InterpreterException

meta_listMethods

public ATTable meta_listMethods()
                         throws InterpreterException

Description copied from interface: ATObject

Queries an object for a list of all of its method slots. TODO(beholders) should this method trigger beholders? if so, using a single 'methodsQueried' event or by invoking 'methodAccessed' for each field in the list returned?

Specified by:

meta_listMethods in interface ATObject

Overrides:

meta_listMethods in class NATNil

Returns:

a table of default methods

Throws:

InterpreterException

meta_print

public NATText meta_print()
                   throws InterpreterException

Description copied from interface: ATObject

Prints out the object in a human-readable way.

Specified by:

meta_print in interface ATObject

Overrides:

meta_print in class NATNil

Throws:

InterpreterException

meta_getDynamicParent

public ATObject meta_getDynamicParent()
                               throws InterpreterException

Description copied from interface: ATObject

Objects have a classical dynamic parent chain created using extension primitives. This getter method allows accessing the parent alongside this dynamic parent chain to be accessed as a field of the object's mirror.

Specified by:

meta_getDynamicParent in interface ATObject

Overrides:

meta_getDynamicParent in class NATNil

Throws:

InterpreterException

meta_getLexicalParent

public ATObject meta_getLexicalParent()
                               throws InterpreterException

Description copied from interface: ATObject

Objects also have a lexical parent which is the scope in which their definitions are nested. This scope is visible using receiverless messages. This getter method allows accessing the parent alongside the lexical nesting chain to be accessed as a field of the object's mirror.

Specified by:

meta_getLexicalParent in interface ATObject

Overrides:

meta_getLexicalParent in class NATNil

Throws:

InterpreterException

meta_getStripes

public ATTable meta_getStripes()
                        throws InterpreterException

The stripes of a far reference are the stripes of the remote object it points to, plus the FarReference stripe.

Specified by:

meta_getStripes in interface ATObject

Overrides:

meta_getStripes in class NATNil

Throws:

InterpreterException

base_isFarReference

public boolean base_isFarReference()

Specified by:

base_isFarReference in interface ATConversions

Overrides:

base_isFarReference in class NATNil

base_asFarReference

public ATFarReference base_asFarReference()
                                   throws XTypeMismatch

Specified by:

base_asFarReference in interface ATConversions

Overrides:

base_asFarReference in class NATNil

Throws:

XTypeMismatch