# Class ComponentRegistry

java.lang.Object
com.google.adk.utils.ComponentRegistry

Direct Known Subclasses:
  `CustomDemoRegistry`

public class ComponentRegistry extends Object
A registry for storing and retrieving ADK instances by name.

This class provides a base registry with common ADK components and is designed to be extended by users who want to add their own pre-wired entries. The registry is fully thread-safe and supports storing any type of object.

Thread Safety:

- All instance methods are thread-safe due to the underlying ConcurrentHashMap
- The singleton instance access is thread-safe using volatile semantics
- The setInstance() method is synchronized to ensure atomic singleton replacement

Base pre-wired entries include:

- "google_search" - GoogleSearchTool instance
- "code_execution" - BuiltInCodeExecutionTool instance
- "exit_loop" - ExitLoopTool instance
- "url_context" - UrlContextTool instance
- "google_maps_grounding" - GoogleMapsTool instance

Example usage:

    // Use the singleton instance
    ComponentRegistry registry = ComponentRegistry.getInstance();
    Optional<GoogleSearchTool> searchTool = registry.get("google_search", GoogleSearchTool.class);

    // Extend ComponentRegistry to add custom pre-wired entries
    public class MyComponentRegistry extends ComponentRegistry {
      public MyComponentRegistry() {
        super(); // Initialize base pre-wired entries
        register("my_custom_tool", new MyCustomTool());
        register("my_agent", new MyCustomAgent());
      }
    }

    // Replace the singleton with custom registry when server starts
    ComponentRegistry.setInstance(new MyComponentRegistry());

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ComponentRegistry()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Optional<Object>`
  `get(String name)`
  Retrieves an object by name without type checking.
  `<T> Optional<T>`
  `get(String name, Class<T> type)`
  Retrieves an object by name and attempts to cast it to the specified type.
  `static ComponentRegistry`
  `getInstance()`
  Returns the global singleton instance of ComponentRegistry.
  `Set<String>`
  `getToolNamesWithPrefix(String prefix)`
  `void`
  `register(String name, Object value)`
  Registers an object with the given name.
  `static Optional<Callbacks.AfterAgentCallback>`
  `resolveAfterAgentCallback(String name)`
  `static Optional<Callbacks.AfterModelCallback>`
  `resolveAfterModelCallback(String name)`
  `static Optional<Callbacks.AfterToolCallback>`
  `resolveAfterToolCallback(String name)`
  `static Class<? extends BaseAgent>`
  `resolveAgentClass(String agentClassName)`
  Resolves the agent class based on the agent class name from the configuration.
  `static Optional<BaseAgent>`
  `resolveAgentInstance(String name)`
  Resolves an agent instance from the registry.
  `static Optional<Callbacks.BeforeAgentCallback>`
  `resolveBeforeAgentCallback(String name)`
  `static Optional<Callbacks.BeforeModelCallback>`
  `resolveBeforeModelCallback(String name)`
  `static Optional<Callbacks.BeforeToolCallback>`
  `resolveBeforeToolCallback(String name)`
  `static Optional<Class<? extends BaseTool>>`
  `resolveToolClass(String toolClassName)`
  Resolves the tool class based on the tool class name from the configuration.
  `static Optional<BaseTool>`
  `resolveToolInstance(String name)`
  `static Optional<Class<? extends BaseToolset>>`
  `resolveToolsetClass(String toolsetClassName)`
  Resolves a toolset class by name from the registry or by attempting to load it.
  `static Optional<BaseToolset>`
  `resolveToolsetInstance(String name)`
  Resolves a toolset instance by name from the registry.
  `static void`
  `setInstance(ComponentRegistry newInstance)`
  Updates the global singleton instance with a new ComponentRegistry.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### ComponentRegistry

    protected ComponentRegistry()

- ## Method Details

  - ### register

    public void register(String name, Object value)
    Registers an object with the given name. This can override pre-wired entries.

    This method is thread-safe due to the underlying ConcurrentHashMap.

    Parameters:
      `name` - the name to associate with the object
      `value` - the object to register (can be an instance, class, function, etc.)
    Throws:
      `IllegalArgumentException` - if name is null or empty, or if value is null

  - ### get

    public <T> Optional<T> get(String name, Class<T> type)
    Retrieves an object by name and attempts to cast it to the specified type.
    Type Parameters:
      `T` - the type parameter
    Parameters:
      `name` - the name of the object to retrieve
      `type` - the expected type of the object
    Returns:
      an Optional containing the object if found and castable to the specified type, or an empty Optional otherwise

  - ### get

    public Optional<Object> get(String name)
    Retrieves an object by name without type checking.
    Parameters:
      `name` - the name of the object to retrieve
    Returns:
      an Optional containing the object if found, or an empty Optional otherwise

  - ### getInstance

    public static ComponentRegistry getInstance()
    Returns the global singleton instance of ComponentRegistry.
    Returns:
      the singleton ComponentRegistry instance

  - ### setInstance

    public static void setInstance(ComponentRegistry newInstance)
    Updates the global singleton instance with a new ComponentRegistry. This is useful for replacing the default registry with a custom one when the server starts.

    This method is thread-safe and ensures that all threads see the updated instance atomically.

    Parameters:
      `newInstance` - the new ComponentRegistry instance to use as the singleton
    Throws:
      `IllegalArgumentException` - if newInstance is null

  - ### resolveAgentInstance

    public static Optional<BaseAgent> resolveAgentInstance(String name)
    Resolves an agent instance from the registry.

    This method looks up an agent in the ComponentRegistry by the given key. The registry should have been pre-populated with all available agents during initialization.

    The key can be any string that was used to register the agent, such as:

    - A class name: "com.example.LifeAgent"
    - A static field reference: "com.example.LifeAgent.INSTANCE"
    - A simple name: "life_agent"
    - Any custom key: "sub_agents_config.life_agent.agent"
    Parameters:
      `name` - the registry key to look up
    Returns:
      an Optional containing the BaseAgent if found, or empty if not found

  - ### resolveAgentClass

    public static Class<? extends BaseAgent> resolveAgentClass(String agentClassName)
    Resolves the agent class based on the agent class name from the configuration.
    Parameters:
      `agentClassName` - the name of the agent class from the config
    Returns:
      the corresponding agent class
    Throws:
      `IllegalArgumentException` - if the agent class is not supported

  - ### resolveToolsetInstance

    public static Optional<BaseToolset> resolveToolsetInstance(String name)
    Resolves a toolset instance by name from the registry.
    Parameters:
      `name` - The name of the toolset instance to resolve.
    Returns:
      An Optional containing the toolset instance if found, empty otherwise.

  - ### resolveToolInstance

    public static Optional<BaseTool> resolveToolInstance(String name)

  - ### resolveToolClass

    public static Optional<Class<? extends BaseTool>> resolveToolClass(String toolClassName)
    Resolves the tool class based on the tool class name from the configuration.
    Parameters:
      `toolClassName` - the name of the tool class from the config
    Returns:
      an Optional containing the tool class if found, empty otherwise

  - ### resolveToolsetClass

    public static Optional<Class<? extends BaseToolset>> resolveToolsetClass(String toolsetClassName)
    Resolves a toolset class by name from the registry or by attempting to load it.

    This method follows the same pattern as `resolveToolClass` but for BaseToolset implementations. It first checks the registry, then attempts direct class loading if the name contains a dot (indicating a fully qualified class name).

    Parameters:
      `toolsetClassName` - the name of the toolset class from the config
    Returns:
      an Optional containing the toolset class if found, empty otherwise

  - ### getToolNamesWithPrefix

    public Set<String> getToolNamesWithPrefix(String prefix)

  - ### resolveBeforeAgentCallback

    public static Optional<Callbacks.BeforeAgentCallback> resolveBeforeAgentCallback(String name)

  - ### resolveAfterAgentCallback

    public static Optional<Callbacks.AfterAgentCallback> resolveAfterAgentCallback(String name)

  - ### resolveBeforeModelCallback

    public static Optional<Callbacks.BeforeModelCallback> resolveBeforeModelCallback(String name)

  - ### resolveAfterModelCallback

    public static Optional<Callbacks.AfterModelCallback> resolveAfterModelCallback(String name)

  - ### resolveBeforeToolCallback

    public static Optional<Callbacks.BeforeToolCallback> resolveBeforeToolCallback(String name)

  - ### resolveAfterToolCallback

    public static Optional<Callbacks.AfterToolCallback> resolveAfterToolCallback(String name)