jawiro
Class Role

java.lang.Object
  jawiro.Role

All Implemented Interfaces:

java.io.Serializable, RoleInterface

Direct Known Subclasses:

AggregateRole

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

From the modeling perspective, roles are different types of behavior that different types of entities can perform. Roles are modeled by the Role class in JAWIRO.

Definition of the basic features of roles varies slightly among different researchers. According to our experience, the basic features of a role model should contain the following:

• Roles can be gained and abandoned dynamically and independently of each other.
• Roles can be organized in various hierarchical relationships. A role can play other roles, too.
• The notion that a real world object is defined by all its roles is preserved, e.g. each role object is aware of its owner and the root of the hierarchy.
• An entity can switch between its roles any time it wishes. This means that any of the roles of an object can be accessed from a reference to any other role.
• A role can access member variables and methods of other roles by means of the two previously described features.
• Class level inheritance can be used together with object level inheritance.
• Entities can be queried whether they are currently playing a certain type of role or a particular role object.
• An entity can have more than one instance of the same role type. Such roles are called aggregate roles and distinguished from each other with an identifier.
• Different roles are allowed to have member variables and methods with same names without conflicts.

These basic features do not cover all that can be done with roles. JAWIRO implements the following extended features of roles as well:

• Roles can be suspended and then resumed.
• A role can be transferred to another owner without dropping its sub roles.
• Multiple object level inheritance is supported.
• Any public member variable or method of any participant of a role hierarchy can be accessed solely by its name, without a direct reference to its owner. In case of identical names, the most evolved member is returned.
• Previously mentioned behavior can be overridden by setting dominant nodes in a role hierarchy.
• Both consultation and delegation mechanisms are supported.
• Abnormal role bindings are prevented.
• Persistence is supported, so that users are able to save entire role hierarchies to secondary storage devices for later use.

See Also:

Actor, 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

Role()
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 a role 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.
java.lang.Object	executeLocalMethod(java.lang.String name, java.lang.Object... parameters) Method for executing a member method of a Role object.
java.lang.Object	executeMethod(java.lang.String name, java.lang.Object... parameters) Method for member method access without referring its owner.
Actor	getActor() Method for accessing the root of the role hierarchy, e.g. the modeled real-world entity.
java.lang.String	getClassName() Method for finding the class name of an object.
int	getDepth() Returns how deep this JAWIRO object resides in its role hierarchy.
java.lang.String	getOwnerClassName() Returns the class name of the owner of this role.
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	isDominant() Method for checking whether this object is dominant or not.
boolean	isReadableWhileSuspended() Normally, suspended roles cannot be used with the commands of JAWIRO API.
boolean	isSuspended() Method for checking whether this role is suspended or not.
java.lang.Object	playedBy() Method for accessing this role's owner.
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.
boolean	resign() Permanently removes this role from the role hierarchy.
boolean	resume() Resumes a suspended role if a reference to this role exists or the reference can be obtained by role switching.
void	setReadableWhileSuspended(boolean isReadable) Normally, suspended roles cannot be used with the commands of JAWIRO API.
boolean	suspend() Temporarily suspends a role.
boolean	transfer(RoleInterface newOwner) Transfers this role, without dropping its sub roles, to another owner.

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

Role

public Role()

Default constructor.

Method Detail

playedBy

public java.lang.Object playedBy()

Method for accessing this role's owner. If the role is suspended or not assigned to an owner since its creation, this method returns null.

Returns:

Reference to the owner of this role or null, as described above.

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)

resign

public boolean resign()

Permanently removes this role from the role hierarchy. It's possible to give a resigned role to a new owner but other methods of the JAWIRO API such as role switching will not work.

Returns:

Whether the operation is successful or not.

suspend

public boolean suspend()

Temporarily suspends a role. A suspended role cannot be used with the commands of the JAWIRO API except Role.resume or Actor.resumeRole. A constraint manager can prevent the suspension if its rules dictate so.

Returns:

Whether the operation is successful or not.

See Also:

Actor.suspendRole(String), ConstraintStrategy, ConstraintStrategy#approveSuspend(String, String)

isSuspended

public boolean isSuspended()

Method for checking whether this role is suspended or not.

Returns:

true if this role is suspended.

resume

public boolean resume()

Resumes a suspended role if a reference to this role exists or the reference can be obtained by role switching. A constraint manager can prevent the resuming if its rules dictate so.

Returns:

Whether the operation is successful or not.

See Also:

ConstraintStrategy, ConstraintStrategy#approveResume(String, String), Actor.resumeRole(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 role object. However, all member fields of jawiro.RoleList are private and all of its member methods are only visible for the jawiro package.

transfer

public boolean transfer(RoleInterface newOwner)

Transfers this role, without dropping its sub roles, to another owner. A constraint manager can prevent the transfer if its rules dictate so.

A role object is not added to a hierarchy where another role object of the same type already exists. In case of aggregate roles, one is not added to a hierarchy where another role object having both the same type and identifier already exists. However, the transfer command does not check for these constraints for subroles of the object that is to be transferred.

Parameters:

newOwner -

Returns:

Whether the operation is successful or not.

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()

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 a role 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 JAWIRO object resides in its role hierarchy.

Specified by:

getDepth in interface RoleInterface

Returns:

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

See Also:

RoleInterface.getDepth()

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 a Role 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[])

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.

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:

Actor.enableDelegation(boolean)

getActor

public Actor getActor()

Method for accessing the root of the role hierarchy, e.g. the modeled real-world entity. If this role is not assigned to an owner since its creation, this method returns null.

Returns:

Reference to the root of the hierarchy where this role is a participant.

getOwnerClassName

public java.lang.String getOwnerClassName()

Description copied from interface: RoleInterface

Returns the class name of the owner of this role.

Specified by:

getOwnerClassName in interface RoleInterface

Returns:

The class name of the owner of this role.

isReadableWhileSuspended

public boolean isReadableWhileSuspended()

Normally, suspended roles cannot be used with the commands of JAWIRO API. Each role can be thought as a responsibility and a suspended responsibility should not be used. Otherwise, it would be either 'illegal' or 'abnormal'.

However, one may need to read a member variable or execute a method of a role which will not cause anything 'illegal' or 'abnormal', although it is not allowed by default. Therefore, this rule can be overridden. This method returns true if it is done so, false otherwise.

Role checking controls (canSwitch and canDelegate) will return false and member variable/method access calls (Role.bringMember and Role.executeMethod) will remain to be inaccessible, regardless of that assignment.

Returns:

whether this role can be accessed via role switching while it is suspended.

See Also:

setReadableWhileSuspended(boolean)

setReadableWhileSuspended

public void setReadableWhileSuspended(boolean isReadable)

Normally, suspended roles cannot be used with the commands of JAWIRO API. Each role can be thought as a responsibility and a suspended responsibility should not be used. Otherwise, it would be either 'illegal' or 'abnormal'.

However, one may need to read a member variable or execute a method of a role which will not cause anything 'illegal' or 'abnormal', although it is not allowed by default.

In order to override the enforcement described above, and to let someone to switch a suspended role, assign true to the isReadable parameter of this method. Role checking controls (canSwitch and canDelegate) will return false, regardless of that assignment. Moreover, member variable and method access calls (Role.bringMember and Role.executeMethod) will remain to be inaccessible while this role is suspended.

The default behaviour is to disallow role switching while the role is suspended.

Parameters:

isReadable - Determines whether this role can be accessed via role switching while it is suspended.

See Also:

isReadableWhileSuspended()