edu.vub.at.objects
Interface ATObject

All Superinterfaces:

ATConversions

All Known Subinterfaces:

ATAbstractGrammar, ATActorMirror, ATApplication, ATAssignField, ATAssignment, ATAssignTable, ATAssignVariable, ATAsyncMessage, ATAsyncMessageCreation, ATBegin, ATBoolean, ATClosure, ATClosureLiteral, ATContext, ATDefExternalField, ATDefExternalMethod, ATDefField, ATDefinition, ATDefMethod, ATDefStripe, ATDefTable, ATExpression, ATFarReference, ATField, ATFraction, ATHandler, ATJavaClosure, ATMailbox, ATMessage, ATMessageCreation, ATMessageSend, ATMethod, ATMethodInvocation, ATMethodInvocationCreation, ATMirror, ATMultiAssignment, ATMultiDefinition, ATNil, ATNumber, ATNumeric, ATObservable, ATQuote, ATSelection, ATSplice, ATStatement, ATStripe, ATSymbol, ATTable, ATTabulation, ATText, ATUnquote, ATUnquoteSplice

All Known Implementing Classes:

AGApplication, AGAssignField, AGAssignTable, AGAssignVariable, AGBegin, AGClosureLiteral, AGDefExternalField, AGDefExternalMethod, AGDefField, AGDefFunction, AGDefStripe, AGDefTable, AGExpression, AGMessageCreation, AGMessageSend, AGMultiAssignment, AGMultiDefinition, AGQuote, AGSelection, AGSplice, AGSymbol, AGTabulation, AGUnquote, AGUnquoteSplice, JavaClass, JavaClosure, JavaField, JavaMethod, JavaObject, NATAbstractGrammar, NATActorMirror, NATAsyncMessage, NATBoolean, NATCallframe, NATClosure, NATClosureMethod, NATContext, NATDelegation, NATFarReference, NATField, NATFraction, NATHandler, NATIntercessiveMirror, NATIntrospectiveMirror, NativeAnonymousMethod, NativeField, NativeMethod, NATMessage, NATMethod, NATMethodInvocation, NATNil, NATNumber, NATNumeric, NATObject, NATObjectClosureTest.AGScopeTest, NATStripe, NATStripe.OBJRootStripe, NATTable, NATText, PrimitiveMethod

public interface ATObject

extends ATConversions

ATObject represents the public interface of an AmbientTalk/2 object. Any value representing an ambienttalk object should implement this interface. Some meta methods defined in this interface will give rise to events in the receiver object's beholders (i.e. the observers of the object's mirror). The principal implementors of this interface are: - NATNil which provides a default implementation for all native, non-object values The default implementation tries to make a Java native object look like an AmbientTalk object. - NATCallframe provides the implementation for a special kind of objects, namely call frames or 'activation records'. These are objects without true methods. - NATObject provides the most important implementation, namely that of base-level AmbientTalk objects. - NATSuperObject acts as a proxy to a NATObject. Therefore, it implements the ATObject interface by properly forwarding all methods to a wrapped object.

Author:

tvc

Method Summary

ATBoolean	base__opeql__opeql_(ATObject other) The pointer equality == operator.
ATObject	base_init(ATObject[] initargs) The object initialisation method.
ATObject	base_new(ATObject[] initargs) The object instantiation method.
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() Clone the receiver object.
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_eval(ATContext ctx) Evaluates a particular parsetree with respect to a particular context.
ATObject	meta_extend(ATClosure code) Create an is-a extension of the receiver object.
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() Returns the stripes of this object.
ATField	meta_grabField(ATSymbol selector) Queries an object for one of its field slots.
ATMethod	meta_grabMethod(ATSymbol selector) Queries an object for one of its method slots.
ATObject	meta_invoke(ATObject receiver, ATSymbol selector, 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.
ATBoolean	meta_isStripedWith(ATStripe stripe) Tests whether the receiver object is striped with a particular stripe.
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) Create a new instance of the receiver object.
ATObject	meta_pass() Allows objects to specify how they should be passed when passed as an argument in a message sent to another actor.
NATText	meta_print() Prints out the object in a human-readable way.
ATObject	meta_quote(ATContext ctx) Quotes a parsetree, in other words allows the parsetree to return itself instead of evaluating.
ATObject	meta_receive(ATAsyncMessage message) Handles a first-class message of which it is the receiver.
ATObject	meta_resolve() When an object is deserialized after it has been passed to another actor, it is given a chance to tell the interpreter which object it represents.
ATBoolean	meta_respondsTo(ATSymbol selector) 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_send(ATAsyncMessage message) Sends a newly created message asynchronously by this object.
ATObject	meta_share(ATClosure code) Create a shares-a extension of the receiver object.

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

asAmbientTalkObject, asJavaClassUnderSymbiosis, asJavaObjectUnderSymbiosis, asNativeBoolean, asNativeException, asNativeFarReference, asNativeFraction, asNativeNumber, asNativeNumeric, asNativeTable, asNativeText, base_asActorMirror, base_asAsyncMessage, base_asBegin, base_asBoolean, base_asClosure, base_asDefinition, base_asExpression, base_asFarReference, 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_isFarReference, base_isMessageCreation, base_isMethod, base_isMirror, base_isSplice, base_isStripe, base_isSymbol, base_isTable, base_isUnquoteSplice, base_isVariableAssignment, isAmbientTalkObject, isJavaObjectUnderSymbiosis, isNativeBoolean, isNativeField, isNativeText

Method Detail

meta_send

public ATObject meta_send(ATAsyncMessage message)
                   throws InterpreterException

Sends a newly created message asynchronously by this object. The message may be scheduled in the current actor's outbox if the current ATObject is a remote reference.

Parameters:

message - the asynchronous message (by default created using the actor's base_createMessage method) Triggers the following events on this object's beholders (mirror observers): - sentMessage when the message was sent by the actor.

Throws:

InterpreterException

meta_receive

public ATObject meta_receive(ATAsyncMessage message)
                      throws InterpreterException

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

Parameters:

message - the asynchronous message send by some object possibly from another actor

Returns:

the return value of invoking the method corresponding to the message

Throws:

InterpreterException

meta_invoke

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

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.

Parameters:

receiver - the object to which 'self' is bound during execution of the method

selector - the name of the method to be invoked

arguments - the table of arguments passed to the method

Returns:

return value of the method Triggers the following events on this object's beholders (mirror observers): - methodFound when a method has been found but not yet applied - methodInvoked when the received method has been applied

Throws:

InterpreterException

meta_respondsTo

public ATBoolean meta_respondsTo(ATSymbol selector)
                          throws InterpreterException

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.

Parameters:

selector - the name of a field or method

Returns:

a boolean denoting whether the object responds to o.selector

Throws:

InterpreterException

meta_doesNotUnderstand

public ATObject meta_doesNotUnderstand(ATSymbol selector)
                                throws InterpreterException

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.

Parameters:

selector - the selector that could not be found

Throws:

XSelectorNotFound - the default reaction to a failed selection

InterpreterException

meta_pass

public ATObject meta_pass()
                   throws InterpreterException

Allows objects to specify how they should be passed when passed as an argument in a message sent to another actor.

Returns:

Objects may choose to return themselves, a clone or a proxy representation

Throws:

InterpreterException - - when overridden by the programmer

meta_resolve

public ATObject meta_resolve()
                      throws InterpreterException

When an object is deserialized after it has been passed to another actor, it is given a chance to tell the interpreter which object it represents. Normally, by copy objects just return 'this' because they represent themselves. Far references, however, will try to 'resolve' themselves into a near reference when possible.

Returns:

the object represented by this deserialized object

Throws:

XIllegalOperation - when by-reference objects are resolved or when overridden by programmer

InterpreterException

meta_select

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

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.

Parameters:

receiver - the dynamic receiver to which method closures should bind self.

selector - the name of the field or method sought for.

Returns:

the contents of the slot Triggers the slotSelected event on this object's beholders (mirror observers).

Throws:

InterpreterException

meta_lookup

public ATObject meta_lookup(ATSymbol selector)
                     throws InterpreterException

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.

Parameters:

selector - the name of the field or method to look up.

Returns:

the contents of the slot

Throws:

XUndefinedField - if the field cannot be found Triggers the slotSelected event on this object's beholders (mirror observers).

InterpreterException

meta_defineField

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

Defines a new field in an object.

Parameters:

name - the name of the new field

value - the value of the new field

Returns:

nil

Throws:

XDuplicateSlot - if the field name already exists Triggers the fieldAdded event on this object's beholders (mirror observers) if the field is added successfully.

InterpreterException

meta_assignVariable

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

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.

Parameters:

name - a symbol representing the name of the variable to assign.

value - the value to assign to the specified slot.

Returns:

nil

Throws:

XUnassignableField - if the field to set cannot be found.

InterpreterException

meta_assignField

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

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.

Parameters:

receiver - the object which received (and possibly delegated) the request

name - a symbol representing the field to assign.

value - the value to assign to the specified slot.

Returns:

nil

Throws:

XUnassignableField - if the field to set cannot be found.

InterpreterException

meta_clone

public ATObject meta_clone()
                    throws InterpreterException

Clone the receiver object. This cloning closely corresponds to the allocation phase in class-based OO languages. In class-based languages, instance creation is based on the equation = () (i.e. first allocate a new instance, then initialize it). In our object-based model, allocation is replaced by cloning. When an object is asked to clone itself, it will also clone its dynamic parent if it extends this parent in an 'is-a' relationship. This is similar to the observation that, in class-based languages, allocating a new object of a subclass entails allocating space for the state of the superclass. Triggers the objectCloned event on this object's beholders (mirror observers). Initializing the clone is the responsibility of the method named .

Throws:

InterpreterException

meta_newInstance

public ATObject meta_newInstance(ATTable initargs)
                          throws InterpreterException

Create a new instance of the receiver object. AmbientTalk mimics the initialization protocol of Class-based languages like Smalltalk. In a typical CBL, object initialization equals class allocation + new instance initialization. In AmbientTalk, class allocation is replaced by cloning via the meta_clone operation. Object initialization itself differs from cloning in that it additionally initializes the clone. For standard AmbientTalk objects, this happens by invoking a method named 'init' on the newly created instance.

Parameters:

initargs - arguments to the 'init' constructor method

Returns:

the new instance

Throws:

InterpreterException

meta_extend

public ATObject meta_extend(ATClosure code)
                     throws InterpreterException

Create an is-a extension of the receiver object. The base-level code is represented at the meta-level by Triggers the objectExtended event on this object's beholders (mirror observers).

Returns:

a fresh object whose dynamic parent points to with 'is-a' semantics.

Throws:

InterpreterException

meta_share

public ATObject meta_share(ATClosure code)
                    throws InterpreterException

Create a shares-a extension of the receiver object. The base-level code obj.share { code } is represented at the meta-level by mirror(obj).meta_share(code) Triggers the objectShared event on this object's beholders (mirror observers).

Returns:

a fresh object whose dynamic parent points to with 'shares-a' semantics.

Throws:

InterpreterException

meta_addField

public ATNil meta_addField(ATField field)
                    throws InterpreterException

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.

Parameters:

field - a mirror on the field to add, consisting of a selector (a symbol) and a value (an object)

Returns:

nil

Throws:

XDuplicateSlot - if the field name already exists TODO: return value = nil?

InterpreterException

meta_addMethod

public ATNil meta_addMethod(ATMethod method)
                     throws InterpreterException

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.

Parameters:

method - a mirror on the method to add. A method consists of a selector, arguments and a body.

Returns:

nil

Throws:

XDuplicateSlot - if the method's selector already exists TODO: return value = nil? argument = a method mirror or a closure mirror?

InterpreterException

meta_grabField

public ATField meta_grabField(ATSymbol selector)
                       throws InterpreterException

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

Parameters:

selector - a symbol representing the name of the slot.

Returns:

a mirror on this object's field slot.

Throws:

XUndefinedField - if the field cannot be found.

InterpreterException

meta_grabMethod

public ATMethod meta_grabMethod(ATSymbol selector)
                         throws InterpreterException

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

Parameters:

selector - a symbol representing the name of the slot.

Returns:

a mirror on this object's method slot.

Throws:

XSelectorNotFound - if the method cannot be found.

InterpreterException

meta_listFields

public ATTable meta_listFields()
                        throws InterpreterException

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?

Returns:

a table of ATField mirrors.

Throws:

InterpreterException

meta_listMethods

public ATTable meta_listMethods()
                         throws InterpreterException

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?

Returns:

a table of ATMethod mirrors.

Throws:

InterpreterException

meta_getDynamicParent

public ATObject meta_getDynamicParent()
                               throws InterpreterException

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.

Throws:

InterpreterException

meta_getLexicalParent

public ATObject meta_getLexicalParent()
                               throws InterpreterException

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.

Throws:

InterpreterException

meta_eval

public ATObject meta_eval(ATContext ctx)
                   throws InterpreterException

Evaluates a particular parsetree with respect to a particular context.

Parameters:

ctx - - context (object) to lookup bindings in.

Throws:

InterpreterException

meta_quote

public ATObject meta_quote(ATContext ctx)
                    throws InterpreterException

Quotes a parsetree, in other words allows the parsetree to return itself instead of evaluating. This mode is triggered when a quotation parsetree element was encountered and is switched off again when an unquotation parsetree element is found. The context is passed on behalf of these possible future evaluations.

Parameters:

ctx - - context passed on to be used in subsequent evaluations.

Throws:

InterpreterException - upon conversion errors or upon illegal unquoted expressions

meta_print

public NATText meta_print()
                   throws InterpreterException

Prints out the object in a human-readable way.

Returns:

a native textual representation of the object.

Throws:

InterpreterException

meta_isRelatedTo

public ATBoolean meta_isRelatedTo(ATObject object)
                           throws InterpreterException

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

Throws:

InterpreterException

meta_isCloneOf

public ATBoolean meta_isCloneOf(ATObject original)
                         throws InterpreterException

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

Parameters:

original - - the object of which this object is supposedly a sibling

Returns:

NATBoolean._TRUE_ if both objects are related.

Throws:

InterpreterException

meta_isStripedWith

public ATBoolean meta_isStripedWith(ATStripe stripe)
                             throws InterpreterException

Tests whether the receiver object is striped with a particular stripe. If the test fails, i.e. the object is not directly striped with (a substripe of) the given stripe, the test is applied recursively to the dynamic parent of the object, until nil is reached.

Throws:

InterpreterException

meta_getStripes

public ATTable meta_getStripes()
                        throws InterpreterException

Returns the stripes of this object. Note that only the stripes that were attached directly to this object are returned, not all of the parent's stripes as well.

Throws:

InterpreterException

base__opeql__opeql_

public ATBoolean base__opeql__opeql_(ATObject other)
                              throws InterpreterException

The pointer equality == operator. OBJ(o1) == OBJ(o2) => BLN(o1.equals(o2))

Throws:

InterpreterException

base_new

public ATObject base_new(ATObject[] initargs)
                  throws InterpreterException

The object instantiation method. obj.new(@args) => (reflect: obj).newInstance(@args)

Throws:

InterpreterException

base_init

public ATObject base_init(ATObject[] initargs)
                   throws InterpreterException

The object initialisation method. By default, it does nothing. obj.init(@args) => nil

Throws:

InterpreterException