org.dynalang.mop
Interface CallProtocol

All Known Subinterfaces:
BaseMetaobjectProtocol, ClassBasedMetaobjectProtocol, MetaobjectProtocol
All Known Implementing Classes:
BeansMetaobjectProtocol, BottomMetaobjectProtocol, CompositeClassBasedMetaobjectProtocol, CompositeMetaobjectProtocol, ListMetaobjectProtocol, MapMetaobjectProtocol, MetaobjectProtocolAdaptor, MetaobjectProtocolBase

public interface CallProtocol

An interface for objects that are capable of creating alternative representations for objects, for purposes of converting between types where necessary (usually used for arguments of method invocation and property setters). It is also capable of invoking callable objects, and retrieving a property from an object. Note that BaseMetaobjectProtocol extends this interface.

Version:
$Id: $
Author:
Attila Szegedi

Method Summary
 java.lang.Object call(java.lang.Object callable, CallProtocol callProtocol, java.util.Map args)
          Calls a callable object with named arguments.
 java.lang.Object call(java.lang.Object callable, CallProtocol callProtocol, java.lang.Object... args)
          Calls a callable object with positional arguments.
 java.lang.Object get(java.lang.Object target, java.lang.Object propertyId)
          Retrieves the property value from the target object.
 java.lang.Object representAs(java.lang.Object object, java.lang.Class targetClass)
          Returns a representation of the specified target object as an object of the specified target class.
 

Method Detail

representAs

java.lang.Object representAs(java.lang.Object object,
                             java.lang.Class targetClass)
Returns a representation of the specified target object as an object of the specified target class. Typical supported target classes would be wrappers for Java primitive types that map to native types of the higher level languages. I.e. if an object is used as a boolean expression, then the language would ask the protocol to interpret it as boolean by calling representAs(Boolean.TYPE).

Parameters:
object - the object to represent
targetClass - the target class for representation.
Returns:
the representation that must be instance of the targetClass, or in case targetClass is primitive, of its adequate boxing class. It can also be a special value to indicate conversion failure: BaseMetaobjectProtocol.Results.noAuthority is returned if the marshaller can not authoritatively decide on a representation; BaseMetaobjectProtocol.Results.noRepresentation is returned if the marshaller can authoritatively decide that the requested representation is not possible. representation of null should be null, except when the target class is a primitive type in which case BaseMetaobjectProtocol.Results.noRepresentation should be returned.

get

java.lang.Object get(java.lang.Object target,
                     java.lang.Object propertyId)
Retrieves the property value from 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 property value for the target object. A null value means that the protocol authoritatively decided that the value of the property is null. If the protocol decides that the property does not exist, it will return BaseMetaobjectProtocol.Results.doesNotExist. If the protocol decides that the property exists, but is not readable, it will return BaseMetaobjectProtocol.Results.notReadable. If the protocol can not make an authoritative decision, it will return BaseMetaobjectProtocol.Results.noAuthority.

call

java.lang.Object call(java.lang.Object callable,
                      CallProtocol callProtocol,
                      java.util.Map args)
Calls a callable object with named arguments.

Parameters:
callProtocol - a marshaller that should be used by this metaobject protocol to convert the arguments to conform to expected argument types for the call.
args - the named arguments for the callable object. null must be treated as empty map. Usually, the map keys are strings, but it is possible that some protocols support non-string keys.
callable - the callable object
Returns:
the return value of the call, or a special result. BaseMetaobjectProtocol.Results.notCallable is returned if the protocol can authoritatively decide that the target is not a callable, or is not callable with named arguments. BaseMetaobjectProtocol.Results.doesNotExist is returned if the callable does not exist at all. BaseMetaobjectProtocol.Results.noAuthority is returned if the protocol can not authoritatively decide whether the target is callable.

call

java.lang.Object call(java.lang.Object callable,
                      CallProtocol callProtocol,
                      java.lang.Object... args)
Calls a callable object with positional arguments.

Parameters:
callable - the callable object
callProtocol - a marshaller that should be used by this metaobject protocol to convert the arguments to conform to expected argument types for the call.
args - the positional arguments for the callable object. null must be treated as empty array.
Returns:
the return value of the call, or a special result. BaseMetaobjectProtocol.Results.notCallable is returned if the protocol can authoritatively decide that the target is not a callable, or is not callable with positional arguments. BaseMetaobjectProtocol.Results.doesNotExist is returned if the callable does not exist at all. BaseMetaobjectProtocol.Results.noAuthority is returned if the protocol can not authoritatively decide whether the target is callable.