org.dynalang.mop
Interface BaseMetaobjectProtocol

All Superinterfaces:

CallProtocol

All Known Subinterfaces:

ClassBasedMetaobjectProtocol, MetaobjectProtocol

All Known Implementing Classes:

BeansMetaobjectProtocol, BottomMetaobjectProtocol, CompositeClassBasedMetaobjectProtocol, CompositeMetaobjectProtocol, ListMetaobjectProtocol, MapMetaobjectProtocol, MetaobjectProtocolAdaptor, MetaobjectProtocolBase

public interface BaseMetaobjectProtocol
extends CallProtocol

The base metaobject protocol interface that provides essential functionality for implementing a metaobject protocol. Some notes on the design:

• No methods throw checked exceptions. If a method's implementation relies on calling Java methods that throw checked exceptions (most likely the various call methods), then they must wrap them into a UndeclaredThrowableException first.
• Various expected failures are not indicated by exceptions, but rather indicated with special return values, either by returning null from methods that otherwise return a Boolean, or more frequently, by returning a special value from the BaseMetaobjectProtocol.Results enum where methods return Object. The rationale for this is that the protocols are designed with chaining in mind, namely more than one protocol can be invoked for an operation on an object, and certain protocols can declare that they can't handle that particular object (in our self-chosen terminology, they don't have authority over it) so the next protocol gets tried. Using exceptions for such expected flow control seemed like a bad practice. Also, a language implementation using multiple protocols can choose to signal an error on its own if all protocols are exhausted without success for a particular operation, and it is at liberty to use whatever is its natural error signaling method, which is not necessarily equivalent or best implemented using Java structured exception handling.

Version:

$Id: $

Author:

Attila Szegedi

Nested Class Summary

static class

BaseMetaobjectProtocol.Results Defines special operation results that are used as return values from many metaobject protocol methods to indicate success or failure.

Method Summary

BaseMetaobjectProtocol.Results	delete(java.lang.Object target, java.lang.Object propertyId) Deletes an association of a value with a property in the target object.
java.lang.Boolean	has(java.lang.Object target, java.lang.Object propertyId) Tells whether the target object has a particular property.
java.util.Iterator<java.util.Map.Entry>	properties(java.lang.Object target) Returns an iterator over the property ID-value pairs in the target object this MOP knows about (and chooses to expose - not all properties must be exposed; hidden properties are allowed).
BaseMetaobjectProtocol.Results	put(java.lang.Object target, java.lang.Object propertyId, java.lang.Object value, CallProtocol callProtocol) Associates a value with a property in the target object.

Methods inherited from interface org.dynalang.mop.CallProtocol

call, call, get, representAs

Method Detail

delete

BaseMetaobjectProtocol.Results delete(java.lang.Object target,
                                      java.lang.Object propertyId)

Deletes an association of a value with a property in the target object.

Parameters:

target - the target object

propertyId - the ID of the property. Usually a String or an Integer, but other property ID types can also be supported.

Returns:

the status of the operation. If the protocol decides that the property did not previously exist, it will return BaseMetaobjectProtocol.Results.doesNotExist. If the protocol authoritatively decides that the property can not be deleted, it will return BaseMetaobjectProtocol.Results.notDeleteable. If the protocol doesn't have the authority to delete the property, it will leave the object unchanged, and return BaseMetaobjectProtocol.Results.noAuthority. If the operation succeeds, BaseMetaobjectProtocol.Results.ok is returned.

has

java.lang.Boolean has(java.lang.Object target,
                      java.lang.Object propertyId)

Tells whether the target object has a particular property.

Parameters:

target - the target object

propertyId - the ID of the property. Usually a String or an Integer, but other property ID types can also be supported.

Returns:

Boolean.TRUE or Boolean.FALSE if the protocol can authoritatively decide whether the target has or has not the property, or null if it does not have the authority to decide.

properties

java.util.Iterator<java.util.Map.Entry> properties(java.lang.Object target)

Returns an iterator over the property ID-value pairs in the target object this MOP knows about (and chooses to expose - not all properties must be exposed; hidden properties are allowed).

Parameters:

target - the target object

Returns:

an iterator over all the property ID-value pairs.

put

BaseMetaobjectProtocol.Results put(java.lang.Object target,
                                   java.lang.Object propertyId,
                                   java.lang.Object value,
                                   CallProtocol callProtocol)

Associates a value with a property in the target object.

Parameters:

target - the target object

propertyId - the ID of the property. Usually a String or an Integer, but other property ID types can also be supported.

value - the new value for the property

callProtocol - a marshaller that is used to convert the value in case the property can only accept values of certain types, and the metaobject protocol allows automatic coercing to those types.

Returns:

a value indicating the outcome of the operation. If the protocol decides that the property does not exist, and can not be created, it will return BaseMetaobjectProtocol.Results.doesNotExist. If the protocol authoritatively decides that the property is read-only, it will return BaseMetaobjectProtocol.Results.notWritable. If the property has a limitation on types it can take as values, and the supplied marshaller is not able to provide a suitable representation, then the value of the property is not changed, and BaseMetaobjectProtocol.Results.noRepresentation is returned. Finally, if the protocol doesn't have the authority to put the new property value, it will leave the property value unchanged, and return BaseMetaobjectProtocol.Results.noAuthority. If the operation succeeds, BaseMetaobjectProtocol.Results.ok is returned.