jawiro
Class Actor

java.lang.Object
  jawiro.Actor

All Implemented Interfaces:

java.io.Serializable, RoleInterface

public class Actor
extends java.lang.Object
implements RoleInterface, java.io.Serializable

Real world entities are modeled with a jawiro.Actor instance and the required number of jawiro.Role and/or jawiro.AggregateRole instances. All those instances create a tree structure, e.g. a role hierarchy, where the Actor instance is the root.

See Also:

Role, AggregateRole

Field Summary

java.lang.Class	myClass Keeps the type name to eliminate the need of calling the costly Object.getClass() method.
java.lang.String	myClassName Keeps the type name to eliminate the need of calling the costly Object.getClass().getName() method.

Constructor Summary

Actor()
The default constructor.

Method Summary

boolean	addRole(Role aNewRole) Adds a new role to this object if it will not cause any ambiguities or role binding anomalies.
java.lang.Object	as(java.lang.Class roleClass) The role switching command for regular roles.
java.lang.Object	as(java.lang.Class roleClass, java.lang.String identifier) The role switching command for aggregate roles.
java.lang.Object	as(java.lang.String className) The role switching command for regular roles.
java.lang.Object	as(java.lang.String className, java.lang.String identifier) The role switching command for aggregate roles.
java.lang.Object	bringLocalMember(java.lang.String name) Method for accessing a member field of this object.
java.lang.Object	bringMember(java.lang.String name) Method for member field access without referring its owner.
boolean	canDelegate(Role aRole) Checks whether a given role object exists in the same role hierarchy with this object.
boolean	canSwitch(java.lang.Class roleClass) Checks whether this object has the given role type.
boolean	canSwitch(java.lang.Class roleClass, java.lang.String identifier) Checks whether this object has the given role type.
boolean	canSwitch(java.lang.String className) Checks whether this object has the given role type.
boolean	canSwitch(java.lang.String className, java.lang.String identifier) Checks whether this object has the given role type.
void	dominateSearch(boolean dominate) Method for determining this object as dominant.
void	enableDelegation(boolean use) Enables the use of the delegation mechanism.
java.lang.Object	executeLocalMethod(java.lang.String name, java.lang.Object... parameters) Method for executing a member method of an Actor object.
java.lang.Object	executeMethod(java.lang.String name, java.lang.Object... parameters) Method for member method access without referring its owner.
Actor	getActor()
java.lang.String	getClassName() Method for finding the class name of an object.
jawiro.ConstraintStrategy	getConstraintManager() Returns the constraint manager assigned to this role hierarchy.
int	getDepth() Returns how deep this object resides in its role hierarchy.
boolean	getReflectionPrePopulationMode() Shows the prepopulation behaviour for the entire hierarchy.
jawiro.RoleList	getRoleList() Used for internal operations of JAWIRO.
java.lang.Object	getSelf() Gives access to the self member which is used in the delegation mechanism.
boolean	isDelegationEnabled() Checks whether the use of the delegation mechanism is enabled or not.
boolean	isDelegationUsed() Checks whether the delegation mechanism or the consultation mechanism is used.
boolean	isDominant() Method for checking whether this object is dominant or not.
void	prePopulateReflectionTables(boolean prePopulate) Determines the prepopulation behaviour for member and method tables for the entire hierarchy.
boolean	receiveRole(Role r) Although this method is public, it belongs to the inner workings of JAWIRO and a flagging mechanism prevents its usage from outside of the jawiro package.
void	removeAllDominance() Removes the dominance marks of every participant of the role hierarchy.
boolean	resumeRole(java.lang.String className) Method for resuming a jawiro.Role object of a known type name, when the reference to this role is unavailable.
boolean	resumeRole(java.lang.String className, java.lang.String identifier) Method for resuming a jawiro.AggregateRole object of whose type name and identifier is known, when the reference to this role is unavailable.
void	setConstraintManager(jawiro.ConstraintStrategy cstr) Assigns a constraint manager to this role hierarchy.
boolean	suspendRole(java.lang.String className) The alternative way for suspending a role.
boolean	suspendRole(java.lang.String className, java.lang.String identifier) The alternative way for suspending an aggregate role.
void	useConsultation() Switches to the consultation mechanism.
void	useDelegation() Switches to the delegation mechanism.

Methods inherited from class java.lang.Object

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

Field Detail

myClassName

public final java.lang.String myClassName

Keeps the type name to eliminate the need of calling the costly Object.getClass().getName() method.

myClass

public final java.lang.Class myClass

Keeps the type name to eliminate the need of calling the costly Object.getClass() method.

Constructor Detail

Actor

public Actor()

The default constructor. The predetermined behaviour is as follows:

• Delegation is enabled but consultation is used.
• Member field and method tables are prepopulated.

See Also:

enableDelegation(boolean), prePopulateReflectionTables(boolean)

Method Detail

addRole

public boolean addRole(Role aNewRole)

Adds a new role to this object if it will not cause any ambiguities or role binding anomalies.

Specified by:

addRole in interface RoleInterface

Parameters:

aNewRole - The new role to be added.

Returns:

true if this operation is successful.

See Also:

RoleInterface.addRole(jawiro.Role), ConstraintStrategy, ConstraintStrategy.approveAddRole(String,String)

canDelegate

public boolean canDelegate(Role aRole)

Checks whether a given role object exists in the same role hierarchy with this object.

Specified by:

canDelegate in interface RoleInterface

Parameters:

aRole - The role object whose existence to be checked.

Returns:

true if aRole exists in this hierarchy.

See Also:

RoleInterface.canDelegate(jawiro.Role)

canSwitch

public boolean canSwitch(java.lang.String className)

Checks whether this object has the given role type.

Specified by:

canSwitch in interface RoleInterface

Parameters:

className - The fully qualified class name of a role type of whose existence is to be checked. For example, a customer role defined by the Customer class of package examples, the correct name is "examples.Customer"

Returns:

true if this object is currently playing the given role type.

See Also:

RoleInterface.canSwitch(java.lang.String)

canSwitch

public boolean canSwitch(java.lang.Class roleClass)

Checks whether this object has the given role type.

Specified by:

canSwitch in interface RoleInterface

Parameters:

roleClass - The Class object representing the role type of whose existence is to be checked.

Returns:

true if this object is currently playing the given role type.

See Also:

RoleInterface.canSwitch(java.lang.Class)

canSwitch

public boolean canSwitch(java.lang.String className,
                         java.lang.String identifier)

Checks whether this object has the given role type.

Specified by:

canSwitch in interface RoleInterface

Parameters:

className - The fully qualified class name of an aggregate role type of whose existence is to be checked. For example, a customer role defined by the Customer class of package examples, the correct name is "examples.Customer"

identifier - The identifier of the aggregate role of whose existence is to be checked.

Returns:

true if this object is currently playing the given role type.

See Also:

RoleInterface.canSwitch(java.lang.String, java.lang.String)

canSwitch

public boolean canSwitch(java.lang.Class roleClass,
                         java.lang.String identifier)

Checks whether this object has the given role type.

Specified by:

canSwitch in interface RoleInterface

Parameters:

roleClass - The Class object representing the role type of whose existence is to be checked.

identifier - The identifier of the aggregate role of whose existence is to be checked.

Returns:

true if this object is currently playing the given role type.

See Also:

RoleInterface.canSwitch(java.lang.Class, java.lang.String)

as

public java.lang.Object as(java.lang.String className)

The role switching command for regular roles.

Specified by:

as in interface RoleInterface

Parameters:

className - The fully qualified class name of the 'destination' role. For example, a customer role defined by the Customer class of package examples, the correct name is "examples.Customer"

Returns:

The requested role object or null if no such role is found.

See Also:

RoleInterface.as(java.lang.String)

as

public java.lang.Object as(java.lang.Class roleClass)

The role switching command for regular roles.

Specified by:

as in interface RoleInterface

Parameters:

roleClass - The Class object representing the 'destination' role.

Returns:

The requested role object or null if no such role is found.

See Also:

RoleInterface.as(java.lang.Class)

as

public java.lang.Object as(java.lang.String className,
                           java.lang.String identifier)

The role switching command for aggregate roles.

Specified by:

as in interface RoleInterface

Parameters:

className - The fully qualified class name of the 'destination' role. For example, a customer role defined by the Customer class of package examples, the correct name is "examples.Customer"

identifier - The identifier of the 'destination' aggregate role

Returns:

The requested aggregate role object or null if no such role is found.

See Also:

RoleInterface.as(java.lang.String, java.lang.String)

as

public java.lang.Object as(java.lang.Class roleClass,
                           java.lang.String identifier)

The role switching command for aggregate roles.

Specified by:

as in interface RoleInterface

Parameters:

roleClass - The Class object representing the type of the 'destination' aggregate role.

identifier - The identifier of the 'destination' aggregate role

Returns:

The requested aggregate role object or null if no such role is found.

See Also:

RoleInterface.as(java.lang.Class, java.lang.String)

getRoleList

public jawiro.RoleList getRoleList()

Used for internal operations of JAWIRO. This method returns a jawiro.RoleList instance, which represents the list of the child roles of this object. However, all member fields of jawiro.RoleList are private and all of its member methods are only visible for the jawiro package.

receiveRole

public boolean receiveRole(Role r)

Although this method is public, it belongs to the inner workings of JAWIRO and a flagging mechanism prevents its usage from outside of the jawiro package.

dominateSearch

public void dominateSearch(boolean dominate)

Method for determining this object as dominant.

Specified by:

dominateSearch in interface RoleInterface

Parameters:

dominate - Determines whether this participant is dominant or not.

See Also:

RoleInterface.dominateSearch(boolean)

isDominant

public boolean isDominant()

Method for checking whether this object is dominant or not.

Specified by:

isDominant in interface RoleInterface

Returns:

true is this object is dominant.

See Also:

RoleInterface.isDominant()

executeMethod

public java.lang.Object executeMethod(java.lang.String name,
                                      java.lang.Object... parameters)

Method for member method access without referring its owner.

Specified by:

executeMethod in interface RoleInterface

Parameters:

name - The name of the requested method.

parameters - The parameters for the requested method.

Returns:

The result which the requested method returns.

See Also:

RoleInterface.executeMethod(java.lang.String, java.lang.Object[])

executeLocalMethod

public java.lang.Object executeLocalMethod(java.lang.String name,
                                           java.lang.Object... parameters)

Method for executing a member method of an Actor object.

Specified by:

executeLocalMethod in interface RoleInterface

Parameters:

name - The name of the requested field.

parameters - The parameters for the requested method.

Returns:

Value of the requested field.

See Also:

RoleInterface.executeLocalMethod(java.lang.String, java.lang.Object[])

bringMember

public java.lang.Object bringMember(java.lang.String name)

Method for member field access without referring its owner.

Specified by:

bringMember in interface RoleInterface

Parameters:

name - The name of the requested field.

Returns:

Value of the requested field.

See Also:

RoleInterface.bringMember(java.lang.String)

bringLocalMember

public java.lang.Object bringLocalMember(java.lang.String name)

Method for accessing a member field of this object.

Specified by:

bringLocalMember in interface RoleInterface

Parameters:

name - The name of the requested field.

Returns:

Value of the requested field.

See Also:

RoleInterface.bringLocalMember(java.lang.String)

getDepth

public int getDepth()

Returns how deep this object resides in its role hierarchy. Actor.getDepth() always returns 1 as it is the root object.

Specified by:

getDepth in interface RoleInterface

Returns:

Returns the depth of this object's location in the role hierarchy.

See Also:

RoleInterface.getDepth()

setConstraintManager

public void setConstraintManager(jawiro.ConstraintStrategy cstr)

Assigns a constraint manager to this role hierarchy.

Parameters:

cstr - The constraint manager to be assigned.

See Also:

ConstraintStrategy

getConstraintManager

public jawiro.ConstraintStrategy getConstraintManager()

Returns the constraint manager assigned to this role hierarchy.

Returns:

The constraint manager of this role hierarchy.

See Also:

ConstraintStrategy

enableDelegation

public void enableDelegation(boolean use)

Enables the use of the delegation mechanism.

By default, JAWIRO works with the consultation mechanism, where the implicit this parameter points to the object that the method call has been forwarded to. The alternative is the delegation mechanism where the implicit this parameter points to the original receiver of the message. JAWIRO does not alter the implicit this parameter but it keeps the self member field of both Actor and Role classes updated as explained above. JAWIRO supports both consultation and delegation in such a flexible way that a user can switch between these two mechanisms at will.

Supporting the consultation mechanism is easier because it does not require the additional operations to keep the original recepient of a message. Moreover, these additional operations are expected to introduce some overhead. Therefore the default mechanism is consultation. These issues are kept in mind when implementing the commands related to the delegation and consultation mechanisms. However, benchmarks showed that the delegation and consultation mechanisms of JAWIRO complete the execution of messages in equal times.

Parameters:

use - Determines whether the use of the delegation mechanism is allowed or not.

See Also:

useDelegation, useConsultation(), isDelegationEnabled(), isDelegationUsed(), getSelf()

isDelegationEnabled

public boolean isDelegationEnabled()

Checks whether the use of the delegation mechanism is enabled or not.

Returns:

true if delegation is enabled

See Also:

enableDelegation(boolean), useDelegation, useConsultation(), isDelegationUsed()

useDelegation

public void useDelegation()

Switches to the delegation mechanism.

See Also:

enableDelegation(boolean), useConsultation(), isDelegationEnabled(), isDelegationUsed()

isDelegationUsed

public boolean isDelegationUsed()

Checks whether the delegation mechanism or the consultation mechanism is used.

Returns:

true if the delegation mechanism is being used, false if the consultation mechanism is being used.

See Also:

enableDelegation(boolean), useDelegation, useConsultation(), isDelegationEnabled()

useConsultation

public void useConsultation()

Switches to the consultation mechanism.

See Also:

enableDelegation(boolean), useDelegation, isDelegationEnabled(), isDelegationUsed()

removeAllDominance

public void removeAllDominance()

Removes the dominance marks of every participant of the role hierarchy.

See Also:

RoleInterface.dominateSearch(boolean)

getClassName

public java.lang.String getClassName()

Method for finding the class name of an object.

Specified by:

getClassName in interface RoleInterface

Returns:

Returns the name of this object's class.

resumeRole

public boolean resumeRole(java.lang.String className)

Method for resuming a jawiro.Role object of a known type name, when the reference to this role is unavailable.

If a role hierarchy is saved to secondary storage while some of the roles are suspended, these roles cannot be resumed with the jawiro.Role.resume() method because suspended roles cannot be accessed with the commands of the JAWIRO API. In this case, Actor.resumeRole(String) can be used.

Parameters:

className - The type name of the role to be resumed.

Returns:

true if the role is found and a constraint manager did not disallowed the operation, false otherwise.

See Also:

resumeRole( String, String )

resumeRole

public boolean resumeRole(java.lang.String className,
                          java.lang.String identifier)

Method for resuming a jawiro.AggregateRole object of whose type name and identifier is known, when the reference to this role is unavailable. This is the case when a role hierarchy is saved to secondary storage while there are suspended roles.

Parameters:

className - The type name of the aggregate role to be resumed.

identifier - The identifier of the aggregate role to be resumed.

Returns:

Whether the operation is successful or not.

See Also:

resumeRole( String )

suspendRole

public boolean suspendRole(java.lang.String className)

The alternative way for suspending a role.

Parameters:

className - The type name of the role to be resumed.

Returns:

Whether the operation is successful or not.

suspendRole

public boolean suspendRole(java.lang.String className,
                           java.lang.String identifier)

The alternative way for suspending an aggregate role.

Parameters:

className - The type name of the role to be resumed.

identifier - The identifier of the aggregate role to be resumed.

Returns:

Whether the operation is successful or not.

getSelf

public java.lang.Object getSelf()

Gives access to the self member which is used in the delegation mechanism.

Specified by:

getSelf in interface RoleInterface

Returns:

Either the original or the final recepient of a message, depending on which mechanism is used.

See Also:

enableDelegation(boolean)

prePopulateReflectionTables

public void prePopulateReflectionTables(boolean prePopulate)

Determines the prepopulation behaviour for member and method tables for the entire hierarchy.

In order to let users access members and methods without the actual owner, the Actor.hierarchy object needs to know what members and methods that each participant of a role hierarchy have. It's sufficent to obtain this information only once. This is done either when needed for the first time or beforehand when a Role object is added to an owner for the first time. The latter procedure is referred as "prepopulation of the reflection tables".

For an Actor object, prepopulation means that the reflection table is calculated when its addRole(Object) method is run for the very first time.

Parameters:

prePopulate - If true, reflection tables are prepopulated.

getReflectionPrePopulationMode

public boolean getReflectionPrePopulationMode()

Shows the prepopulation behaviour for the entire hierarchy.

Returns:

Whether the reflection tables are prepopulated or not

See Also:

prePopulateReflectionTables(boolean)

getActor

public Actor getActor()