jawiro
Interface RoleInterface

All Known Implementing Classes:

Actor, AggregateRole, Role

public interface RoleInterface

The methods of RoleInterface represent the common behaviour of the participants of a role hierarchy, namely the Actor and the Role objects.

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 a JAWIRO 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 aggregate role type having a particular identifier.
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 aggregate role type having a particular identifier.
void	dominateSearch(boolean dominate) Method for determining a participant of a role hierarchy as dominant.
java.lang.Object	executeLocalMethod(java.lang.String name, java.lang.Object... parameters) Method for executing a member method of a JAWIRO object.
java.lang.Object	executeMethod(java.lang.String name, java.lang.Object... parameters) Method for member method access without referring its owner.
java.lang.String	getClassName() Method for finding the class name of an object.
int	getDepth() Method for finding how deep a participant in a role hierarchy resides.
java.lang.String	getOwnerClassName() Returns the class name of the owner of this role.
java.lang.Object	getSelf() Gives access to the self member which is used for making the use of the delegation mechanism possible.
boolean	isDominant() Method for checking whether a participant of a role hierarchy is dominant or not.

Method Detail

addRole

boolean addRole(Role aNewRole)

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

The following precautions are hard-coded into the role model in order to prevent abnormal role bindings:

• A role instance is not added to a hierarchy where that instance already exists.
• A role instance can participate in only one hierarchy at the same time.
• A suspended role cannot be used with commands of JAWIRO API, e.g. it cannot be transferred to another owner.

JAWIRO also allows users to take additional precautions by defining a constraint manager, which extends the ConstraintStrategy interface.

Parameters:

aNewRole - The new role to be added.

Returns:

true if this operation is successful.

See Also:

ConstraintStrategy

canDelegate

boolean canDelegate(Role aRole)

Checks whether a given role object exists in the same role hierarchy with this object. In other words, it checks whether this object and the given role represent the same real world entity or not.

Parameters:

aRole - The role object whose existence to be checked.

Returns:

true if aRole exists in this hierarchy.

canSwitch

boolean canSwitch(java.lang.String className)

Checks whether this object has the given role type.

It is a wise move to check the existence of a role before attempting to switch that role, especially in persistent systems where keeping track of the participants of a role hierarchy gets harder in the long term.

Consequent checks for the same role type does not bring any overhead as the latest query and its result are remembered. Moreover, all variants of the as methods first check this 'cache' of size 1.

Use canSwitch(String, String) or canSwitch(Class, String) for checking the existence of an aggregate role. canSwitch(Class) returns the first encountered instance (usually the least evolved) if it's used for checking for aggregate roles.

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:

canSwitch(Class), canSwitch(String, String), canSwitch(Class, String)

canSwitch

boolean canSwitch(java.lang.Class roleClass)

Checks whether this object has the given role type.

It is a wise move to check the existence of a role before attempting to switch that role, especially in persistent systems where keeping track of the participants of a role hierarchy gets harder in the long term.

Consequent checks for the same role type does not bring any overhead as the latest query and its result are remembered. Moreover, all variants of the as methods first check this 'cache' of size 1.

Use canSwitch(String, String) or canSwitch(Class, String) for checking the existence of an aggregate role. canSwitch(Class) returns the first encountered instance (usually the least evolved) if it's used for checking for aggregate roles.

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:

canSwitch(String), canSwitch(String, String), canSwitch(Class, String)

canSwitch

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

Checks whether this object has the given aggregate role type having a particular identifier.

It is a wise move to check the existence of a role before attempting to switch that role, especially in persistent systems where keeping track of the participants of a role hierarchy gets harder in the long term. As multiple instances of an aggregate role type can be played simultaneously, it becomes even more important to 'Ask first, switch later'.

Consequent checks for the same role type does not bring any overhead as the latest query and its result are remembered. Moreover, all variants of the as methods first check this 'cache' of size 1.

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:

canSwitch(String), canSwitch(Class), canSwitch(Class, String)

canSwitch

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

Checks whether this object has the given aggregate role type having a particular identifier.

It is a wise move to check the existence of a role before attempting to switch that role, especially in persistent systems where keeping track of the participants of a role hierarchy gets harder in the long term. As multiple instances of an aggregate role type can be played simultaneously, it becomes even more important to 'Ask first, switch later'.

Consequent checks for the same role type does not bring any overhead as the latest query and its result are remembered. Moreover, all variants of the as methods first check this 'cache' of size 1.

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:

canSwitch(String), canSwitch(Class), canSwitch(String, String)

as

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

The role switching command for regular roles.

Any of the roles of an object (e.g. the destination role) can be accessed from a reference to any other role (e.g. the source role) by using the variants of the as methods.

It is usually better to check the existence of a role before attempting to switch that role. This check does not create any overhead on method execution. See canSwitch methods for more details.

Use as(String, String) or as(Class, String) for switching to aggregate roles. as(String) returns the first encountered instance (usually the least evolved) if it's used for switching to an aggregate role.

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:

canSwitch(String), as(Class), as(String, String), as(Class, String)

as

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

The role switching command for regular roles.

Any of the roles of an object (e.g. the destination role) can be accessed from a reference to any other role (e.g. the source role) by using the variants of the as methods.

It is usually better to check the existence of a role before attempting to switch that role. This check does not create any overhead on method execution. See canSwitch methods for more details.

Use as(String, String) or as(Class, String) for switching to aggregate roles. as(Class) returns the first encountered instance (usually the least evolved) if it's used for switching to an aggregate role.

Parameters:

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

Returns:

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

See Also:

canSwitch(Class), as(String), as(String, String), as(Class, String)

as

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

The role switching command for aggregate roles.

Any of the roles of an object (e.g. the destination role) can be accessed from a reference to any other role (e.g. the source role) by using the variants of the as methods.

It is usually better to check the existence of a role before attempting to switch that role. This check does not create any overhead on method execution. See canSwitch methods for more details.

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:

canSwitch(String, String)

as

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

The role switching command for aggregate roles.

Any of the roles of an object (e.g. the destination role) can be accessed from a reference to any other role (e.g. the source role) by using the variants of the as methods.

It is usually better to check the existence of a role before attempting to switch that role. This check does not create any overhead on method execution. See canSwitch methods for more details.

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:

canSwitch(Class, String)

bringMember

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

Method for member field access without referring its owner.

With JAWIRO, it is possible to access a member field of any participant of a role hierarchy, without explicitly referencing to the object having that field. If there are multiple objects in the role hierarchy with member fields having the same name, the most evolved participant's field is returned. Therefore, the requested field is searched in the entire hierarchy. However, this behaviour can be altered by determining some participants as dominant. As a result, the bringMember and executeMethod methods make modeling the evolving behaviour of dynamic objects easier.

Limitations caused by the Java Reflection API:

Member fields is returned by value and primitive types are supported only via their respective wrappers.

Member fields are accessed in call-by-value fashion.

Parameters:

name - The name of the requested field.

Returns:

Value of the requested field.

See Also:

dominateSearch( boolean ), executeMethod( String, Object... ), bringLocalMember( String )

bringLocalMember

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

Method for accessing a member field of a JAWIRO object.

bringLocalMember and executeLocalMethod methods ease the use of the multiple object level inheritance capability of JAWIRO. When a sub role can be owned by objects of different types, the type of the owner can only be determined in runtime. However, the programmer needs a uniform way of access to the owner, regardless of its type. Instead of creating the owner types via class level inheritance from the same type, or instead of implementing a common custom interface in the owner types, one can acquire the owner of the sub role in runtime with the Role.getOwner method and then use the bringLocalMember method.

Parameters:

name - The name of the requested field.

Returns:

Value of the requested field.

See Also:

executeLocalMethod( String, Object... ), bringMember( String )

executeMethod

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

Method for member method access without referring its owner.

With JAWIRO, it is possible to execute a member method of any participant of a role hierarchy, without explicitly referencing to the object having that method. If there are multiple objects in the role hierarchy with member methods having the same name, the most evolved participant's method is executed. Therefore, the requested method is searched in the entire hierarchy. However, this behaviour can be altered by determining some participants as dominant. As a result, the executeMethod and bringMember methods make modeling the evolving behaviour of dynamic objects easier.

Methods to be executed this way should not contain any primitive type in its signature. This is caused by the reflection API as method signatures are calculated by Class.getName which uses primitive type names, while the methods are executed by Method.Invoke which requires wrappers instead of primitive types. As a result, methods containing primitive parameters cannot be reached via this command.

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:

dominateSearch( boolean ), bringMember( String ), executeLocalMethod( String, Object... )

executeLocalMethod

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

Method for executing a member method of a JAWIRO object.

executeLocalMethod and bringLocalMember methods ease the use of the multiple object level inheritance capability of JAWIRO. When a sub role can be owned by objects of different types, the type of the owner can only be determined in runtime. However, the programmer needs a uniform way of access to the owner, regardless of its type. Instead of creating the owner types via class level inheritance from the same type, or instead of implementing a common custom interface in the owner types, one can acquire the owner of the sub role in runtime with the Role.getOwner method and then use the executeLocalMethod method.

Methods to be executed this way should not contain any primitive type in its signature. This is caused by the reflection API as method signatures are calculated by Class.getName which uses primitive type names, while the methods are executed by Method.Invoke which requires wrappers instead of primitive types. As a result, methods containing primitive parameters cannot be reached via this command.

Parameters:

name - The name of the requested field.

parameters - The parameters for the requested method.

Returns:

Value of the requested field.

See Also:

executeMethod( String, Object... ), bringMember( String )

dominateSearch

void dominateSearch(boolean dominate)

Method for determining a participant of a role hierarchy as dominant.

With JAWIRO, it is possible to access a member field or to execute a member method of any participant of a role hierarchy, without explicitly referencing to the object having that member method or field. Normally, JAWIRO uses the most evolved role object's member method or field when executeMethod and bringMember are called. Setting a member of a role hierarchy as dominant alters this behaviour.

The rules of dominance are as follows:

When a Role object is dominant, always this object's members are used, instead of the most evolved role's.

If there are more than one dominant Role objects, the most evolved one among these objects is used.

When an Actor object is dominant, always this object's members are used, regardless of how many other dominant Role objects exist in this hierarchy.

As a result, dominateSearch method adds more flexibility on top of executeMethod and bringMember methods when modeling the evolving behaviour of dynamic objects.

Parameters:

dominate - Determines whether this participant is dominant or not.

See Also:

executeMethod( String, Object... ), bringMember( String )

isDominant

boolean isDominant()

Method for checking whether a participant of a role hierarchy is dominant or not.

Returns:

true is this object is dominant.

See Also:

dominateSearch( boolean )

getDepth

int getDepth()

Method for finding how deep a participant in a role hierarchy resides.

Returns:

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

getClassName

java.lang.String getClassName()

Method for finding the class name of an object.

Returns:

Returns the name of this object's class.

getSelf

java.lang.Object getSelf()

Gives access to the self member which is used for making the use of the delegation mechanism possible.

Returns:

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

See Also:

Actor.enableDelegation(boolean)

getOwnerClassName

java.lang.String getOwnerClassName()

Returns the class name of the owner of this role.

Returns:

The class name of the owner of this role.