Package com.tnsai.roles.registry

Class RoleRegistry

java.lang.Object
com.tnsai.roles.registry.RoleRegistry
public final class RoleRegistry extends Object
Central registry for managing exclusive Role assignments.

RoleRegistry enforces the shared=false constraint from RoleSpec annotation, ensuring that non-shared roles can only be assigned to one agent at a time.

Key Features

  • Thread-safe role assignment tracking
  • Exclusive role enforcement (shared=false)
  • Role-to-agent ownership lookup
  • Automatic role release on agent stop

Usage Example


 RoleRegistry registry = RoleRegistry.getInstance();

 // Assign a role (throws if exclusive and already assigned)
 registry.assignRole(agent, new LeaderRole());

 // Check if a role is shared
 boolean isShared = registry.isShared(LeaderRole.class);

 // Get the owner of an exclusive role
 Optional<Agent> owner = registry.getOwner(LeaderRole.class);

 // Release a role
 registry.releaseRole(agent, role);

Integration with @RoleSpec

When a Role class has @RoleSpec(shared=false), only one agent can hold that role at a time. Attempting to assign the same role to another agent will throw RoleAssignmentException.

Author:
TnsAI Team
See Also:

  • Method Details

    • getInstance

      public static RoleRegistry getInstance()
      Returns the singleton instance.
      Returns:
      the RoleRegistry instance

    • assignRole

      public void assignRole(Agent agent, Role role) throws RoleAssignmentException
      Assigns a role to an agent.

      If the role has @RoleSpec(shared=false) and is already assigned to another agent, throws RoleAssignmentException.

      Parameters:
      agent - the agent to assign the role to
      role - the role to assign
      Throws:
      RoleAssignmentException - if the role is exclusive and already assigned
      IllegalArgumentException - if agent or role is null

    • releaseRole

      public void releaseRole(Agent agent, Role role)
      Releases a role from an agent.

      If the role is exclusive, it becomes available for other agents.

      Parameters:
      agent - the agent releasing the role
      role - the role to release

    • releaseAllRoles

      public void releaseAllRoles(Agent agent)
      Releases all roles from an agent.

      Called when an agent is stopped or destroyed.

      Parameters:
      agent - the agent

    • getOwner

      public Optional<Agent> getOwner(Class<? extends Role> roleClass)
      Gets the current owner of an exclusive role.
      Parameters:
      roleClass - the role class
      Returns:
      the owning agent, or empty if not assigned or if role is shared

    • isShared

      public boolean isShared(Class<? extends Role> roleClass)
      Checks if a role class is shared (can be assigned to multiple agents).

      This is determined by the @RoleSpec(shared=...) annotation. Defaults to true if no annotation is present.

      Parameters:
      roleClass - the role class to check
      Returns:
      true if the role can be shared

    • hasRole

      public boolean hasRole(Agent agent, Class<? extends Role> roleClass)
      Checks if an agent has a specific role assigned.
      Parameters:
      agent - the agent
      roleClass - the role class
      Returns:
      true if the agent has this role

    • getRoles

      public Set<Class<? extends Role>> getRoles(Agent agent)
      Gets all role classes assigned to an agent.
      Parameters:
      agent - the agent
      Returns:
      unmodifiable set of role classes

    • clear

      public void clear()
      Clears all registrations (for testing).