Package ortus.boxlang.runtime.events

Class InterceptorPool

java.lang.Object
ortus.boxlang.runtime.events.InterceptorPool
Direct Known Subclasses:
InterceptorService
public class InterceptorPool extends Object
An InterceptorPool is a pool of interceptors that can be used to intercept events within the BoxLang runtime.

This pool can be used at any level to provide encapsulation of events and provide a way to intercept and modify the behavior of the runtime, service, etc.

This class should be instantiated and used as a singleton.

  • Field Details

    • interceptionPoints

      protected Set<Key> interceptionPoints
      The list of interception points we can listen for

    • interceptionStates

      protected Map<Key,InterceptorState> interceptionStates
      The collection of interception states registered with the service

    • keyRegistry

      protected ConcurrentHashMap<String,Key> keyRegistry
      Key registry of announced states, to avoid key creation

    • name

      protected Key name
      The name of the pool

    • runtime

      protected BoxRuntime runtime
      The runtime singleton

  • Constructor Details

    • InterceptorPool

      public InterceptorPool(Key name, BoxRuntime runtime)
      Construct a pool with a unique name
      Parameters:
      name - The name of the pool
      runtime - The runtime singleton

    • InterceptorPool

      public InterceptorPool(String name, BoxRuntime runtime)
      Construct a pool with a unique name
      Parameters:
      name - The name of the pool

  • Method Details

    • getName

      public Key getName()
      Get the name of the pool
      Returns:
      The name of the pool

    • getInterceptionPoints

      public Set<Key> getInterceptionPoints()
      Get the list of interception points that the pool can announce
      Returns:
      A set of unique interception points

    • getInterceptionStates

      public Map<Key,InterceptorState> getInterceptionStates()
      Get the registered interception states
      Returns:
      The registered interception states

    • clearInterceptionStates

      public void clearInterceptionStates()
      Clear all the interception states Use with caution. Mostly left for testing purposes

    • getInterceptionPointsNames

      public Set<String> getInterceptionPointsNames()
      Get the list of interception points that the pool can announce but as a Set of string names not case insensitive Key objects
      Returns:
      The list of interception points

    • hasInterceptionPoint

      public Boolean hasInterceptionPoint(Key interceptionPoint)
      Check if the pool has an interception point
      Parameters:
      interceptionPoint - The interception point to check
      Returns:
      True if the pool has the interception point, false otherwise

    • registerInterceptionPoint

      public InterceptorPool registerInterceptionPoint(Key... points)
      Register an interception point(s) with the pool
      Parameters:
      points - The interception point(s) to register
      Returns:
      The same pool

    • removeInterceptionPoint

      public InterceptorPool removeInterceptionPoint(Key... points)
      Remove an interception point(s) from the pool
      Parameters:
      points - The interception point(s) to remove
      Returns:
      The same pool

    • getState

      public InterceptorState getState(Key name)
      Get the InterceptorState by name
      Parameters:
      name - The name of the state
      Returns:
      The state if it exists, null otherwise

    • hasState

      public Boolean hasState(Key name)
      Check if the service has the InterceptorState
      Parameters:
      name - The name of the state
      Returns:
      True if the service has the state, false otherwise

    • registerState

      public InterceptorState registerState(Key name)
      Register a new InterceptorState with the pool and returns it. This verifies if there is already an interception point by that name. If there is not, it will add it.
      Parameters:
      name - The name of the state
      Returns:
      The registered InterceptorState

    • removeState

      public InterceptorPool removeState(Key name)
      Remove the InterceptorState from the pool. This essentially destroys all the interceptor references in the state
      Parameters:
      name - The name of the state
      Returns:
      The same pool

    • newAndRegister

      public IClassRunnable newAndRegister(String clazz, IStruct properties, String name, ModuleRecord moduleRecord)
      This method resolves, creates, wires, and registers a BoxLang interceptor Class with the service.
      Parameters:
      clazz - The BoxLang class invocation path of the interceptor to resolve. Example: "ortus.interceptors.MyInterceptor"
      properties - A of properties to wire the interceptor with
      name - The unique name of the interceptor
      moduleRecord - If passed (it can be null), it means that a module is registering the interceptor
      Returns:
      The newly built interceptor
      Throws:
      BoxRuntimeException - If the interceptor class cannot be found

    • register

      public InterceptorPool register(IInterceptor interceptor)
      This method registers a Java interceptor with the pool by metadata inspection of the InterceptionPoint annotation. It will inspect the interceptor for methods that match the states that the pool can announce. If the
      Parameters:
      interceptor - The interceptor to register that must implement IInterceptor
      Returns:
      The pool

    • register

      public InterceptorPool register(IInterceptor interceptor, IStruct properties)
      This method registers a Java interceptor with the pool by metadata inspection of the InterceptionPoint annotation. It will inspect the interceptor for methods that match the states that the pool can announce. If the interceptor has a method that matches the state, it will register it with the pool.
      Parameters:
      interceptor - The interceptor to register that must implement IInterceptor
      properties - A of properties to wire the interceptor with
      Returns:
      The same pool

    • unregister

      public InterceptorPool unregister(IInterceptor interceptor)
      This method UNregisters a Java interceptor with the pool by metadata inspection of the InterceptionPoint annotation. It will inspect the interceptor for methods that match the states that the pool can announce. If the interceptor has a method that matches the state, it will UNregister it with the pool.
      Parameters:
      interceptor - The interceptor to UNregister that must implement IInterceptor
      Returns:
      The same pool

    • register

      public InterceptorPool register(IClassRunnable interceptor)
      This method registers a BoxLang interceptor with the pool by metadata inspection. It will inspect the interceptor for methods that match the states that the pool can announce. If the interceptor has a method that matches the state, it will register it with the pool. If a method has a interceptionPoint BoxLang annotation, then the name of the method will be registered as a valid state and auto-registered.
      Parameters:
      interceptor - The interceptor to register that must implement IClassRunnable
      Returns:
      The same pool

    • register

      public InterceptorPool register(DynamicObject interceptor, Key... states)
      Register an interceptor with the pool which must be an instance of DynamicObject. The interceptor must have a method(s) according to the passed states.
      Parameters:
      interceptor - The interceptor to register
      states - The states to register the interceptor with
      Returns:
      The same pool

    • register

      public InterceptorPool register(IInterceptorLambda interceptor, Key... states)
      Register a Java Lambda Interceptor with the pool on the provided states.
      Parameters:
      interceptor - The interceptor lambda to register
      states - The states to register the interceptor with
      Returns:
      The same pool

    • unregister

      public InterceptorPool unregister(DynamicObject interceptor, Key... states)
      Unregister an interceptor from the provided states.
      Parameters:
      interceptor - The interceptor to unregister
      states - The states to unregister the interceptor from
      Returns:
      The same pool

    • unregister

      public InterceptorPool unregister(DynamicObject interceptor)
      Unregister an interceptor from all states
      Parameters:
      interceptor - The interceptor to unregister
      Returns:
      The same pool

    • announce

      public void announce(Key state)
      Announce an event with no data using a Key object as the state
      Parameters:
      state - The state key to announce

    • announce

      public void announce(BoxEvent state)
      Announce a BoxEvent with no data using a BoxEvent object as the state
      Parameters:
      state - The state key to announce

    • announce

      public void announce(BoxEvent state, IStruct data)
      Announce an event with the provided IStruct of data.
      Parameters:
      state - The state to announce
      data - The data to announce

    • announce

      public void announce(String state, IStruct data)
      Announce an event with the provided IStruct of data.
      Parameters:
      state - The state to announce
      data - The data to announce

    • announce

      public void announce(Key state, IStruct data)
      Announce an event with the provided IStruct of data.
      Parameters:
      state - The state key to announce
      data - The data to announce

    • announce

      public void announce(Key state, IStruct data, IBoxContext context)
      Announce an event with the provided IStruct of data and context
      Parameters:
      state - The state key to announce
      data - The data to announce

    • announceAsync

      public CompletableFuture<IStruct> announceAsync(Key state)
      Announce an event with no data using a Key object as the state asynchronously
      Parameters:
      state - The state key to announce
      Returns:
      A CompletableFuture of the data or null if the state does not exist

    • announceAsync

      public CompletableFuture<IStruct> announceAsync(BoxEvent state)
      Announce a BoxEvent with no data using a BoxEvent object as the state asynchronously
      Parameters:
      state - The state key to announce
      Returns:
      A CompletableFuture of the data or null if the state does not exist

    • announceAsync

      public CompletableFuture<IStruct> announceAsync(BoxEvent state, IStruct data)
      Announce an event with the provided IStruct of data asynchronously.
      Parameters:
      state - The state to announce
      data - The data to announce
      Returns:
      A CompletableFuture of the data or null if the state does not exist

    • announceAsync

      public CompletableFuture<IStruct> announceAsync(String state, IStruct data)
      Announce an event with the provided IStruct of data asynchronously.
      Parameters:
      state - The state to announce
      data - The data to announce
      Returns:
      A CompletableFuture of the data or null if the state does not exist

    • announceAsync

      public CompletableFuture<IStruct> announceAsync(Key state, IStruct data)
      Announce an event with the provided IStruct of data asynchronously.
      Parameters:
      state - The state key to announce
      data - The data to announce
      Returns:
      A CompletableFuture of the data or null if the state does not exist

    • announceAsync

      public CompletableFuture<IStruct> announceAsync(Key state, IStruct data, IBoxContext context)
      Announce an event with the provided IStruct of data and context asynchronously
      Parameters:
      state - The state key to announce
      data - The data to announce
      Returns:
      A CompletableFuture of the data or null if the state does not exist

    • getLogger

      public BoxLangLogger getLogger()
      Get the runtime logger for interceptors

    • inflateStates

      public static Key[] inflateStates(Object states)
      Inflates an array or string of states into a list of keys
      Parameters:
      states - The states to inflate
      Returns:
      The list of keys representing the states