Package io.csar

Class Csar

java.lang.Object
io.csar.Csar
public class Csar extends Object
The Concern Separation Aspect Registrar (Csar /zɑːr/) provides access to some concern (usually cross-cutting) that may configured globally or locally to some section of the program.

A concern is some implementation of Concern and represents some concern such as logging or internationalization. Csar supports associating a concern of a specific type with some thread group, which allows local concerns to be set. A global concern can also be set, which which serves as a fallback for that concern type when no thread group-specific concern is defined. No fallback need be implemented if a thread group-specific concern is always provided to requesting threads.

A concern can be made local by registering it with a thread group that is Concerned, such as ConcernRegistryThreadGroup, and creating a Thread using one of the thread's constructors that specify a ThreadGroup. All threads that run in the thread group will have access to the concern by calling getConcern(Class), specifying the class of the Concern implementation. The concern registered with the Concerned thread group will be returned. A concern can thus be restricted to specific areas of the program.

If no thread group is found that implements the concern type, a global default concern is searched for by using findDefaultConcern(Class). If no local or global concern of the requested type is found, a ConcernNotFoundException is thrown.

For transparent and automatic installation of default concerns, a particular concern implementation (such as an internationalization package based upon resource bundles) can implement ConcernProvider, indicating the the concerns implemented by that library as specified by ServiceLoader. The concern library will provide a text file META-INF/services/io.csar.ConcernProvider containing a line indicating the class name of the concern provider: 

 com.example.FooConcernProvider

When Csar is first loaded, it will ask all registered concern providers for their concerns and register them as default concern providers for the concern type indicated by the Concern.getConcernType() indicated by each.

Author:
Garret Wilson
See Also:

  • Method Details

    • setDefaultConcerns

      public static void setDefaultConcerns(@Nonnull Concern... concerns)
      Registers the given concerns as defaults for their respective classes.
      Parameters:
      concerns - The concerns to register as defaults.

    • setDefaultConcerns

      public static void setDefaultConcerns(@Nonnull Collection<Concern> concerns)
      Registers the given concerns as defaults for their respective classes.
      Parameters:
      concerns - The concerns to register as defaults.

    • setDefaultConcerns

      public static void setDefaultConcerns(@Nonnull Stream<Concern> concerns)
      Registers the given concerns as defaults for their respective classes.
      Parameters:
      concerns - The concerns to register as defaults.

    • registerDefaultConcern

      public static <C extends Concern, D extends Concern> Optional<D> registerDefaultConcern(@Nonnull C concern)
      Registers the given concern as default for its concern type.
      Type Parameters:
      C - The type of concern being set as the default of its concern type.
      D - The type of concern previously set as the default for its concern type.
      Parameters:
      concern - The concern to register.
      Returns:
      The concern previously associated with the same class.
      Throws:
      NullPointerException - if the given concern is null.

    • registerDefaultConcern

      public static <T extends Concern, C extends T> Optional<T> registerDefaultConcern(@Nonnull Class<T> concernType, @Nonnull C concern)
      Registers the given concern as default.
      Type Parameters:
      T - The registration concern type.
      C - The type of concern being registered.
      Parameters:
      concernType - The class with which to associate the concern.
      concern - The concern to register.
      Returns:
      The concern previously associated with the given class.
      Throws:
      NullPointerException - if the given concern is null.

    • findDefaultConcern

      public static <T extends Concern> Optional<T> findDefaultConcern(@Nonnull Class<T> concernType)
      Returns the default concern for the given concern type.
      Type Parameters:
      T - The type of concern to retrieve.
      Parameters:
      concernType - The class of concern to retrieve.
      Returns:
      The concern associated with the given class, or null if there was no concern for that class.

    • unregisterDefaultConcern

      public static <T extends Concern> Optional<T> unregisterDefaultConcern(@Nonnull Class<T> concernType)
      Unregisters a default concern of the given type. If no concern is associated with the specified type, no action occurs.
      Type Parameters:
      T - The type of concern being removed.
      Parameters:
      concernType - The class with which the concern is associated.
      Returns:
      The concern previously associated with the given class, or null if there was no previous concern for that class.

    • getConcern

      public static <C extends Concern> C getConcern(@Nonnull Class<C> concernType) throws ConcernNotFoundException
      Retrieves a concern of the given type for the current thread.

      A local concern is first searched for using the first Concerned thread group, if any, of the current thread. If no Concerned thread group is found for the thread, or no such concern is set for the thread group, a default concern is searched for using findDefaultConcern(Class).

      If no appropriate concern can be found, a ConcernNotFoundException is thrown.

      Type Parameters:
      C - The type of concern to retrieve.
      Parameters:
      concernType - The class indicating the type of concern to retrieve.
      Returns:
      The concern of the requested type.
      Throws:
      ConcernNotFoundException - if no concern of the requested type could be found.
      See Also:

    • findConcern

      public static <C extends Concern> Optional<C> findConcern(@Nonnull Class<C> concernType)
      Retrieves an optional concern of the given type for the current thread.

      A local concern is first searched for using the first Concerned thread group, if any, of the current thread. If no Concerned thread group is found for the thread, or no such concern is set for the thread group, a default concern is searched for using findDefaultConcern(Class).

      Type Parameters:
      C - The type of concern to retrieve.
      Parameters:
      concernType - The class indicating the type of concern to retrieve.
      Returns:
      The concern of the requested type.
      See Also:

    • findConcern

      protected static <T extends Concern> Optional<T> findConcern(@Nonnull Thread thread, @Nonnull Class<T> concernType)
      Retrieves the concern of the given type for the indicated thread.

      A local concern is first searched for using the first Concerned thread group, if any, of the given thread. If no Concerned thread group is found for the thread, or no such concern is set for the thread group, a default concern is searched for using findDefaultConcern(Class). If no appropriate concern can be found, a ConcernNotFoundException is thrown.

      Type Parameters:
      T - The type of concern to retrieve.
      Parameters:
      thread - The thread for which a concern should be retrieved.
      concernType - The class indicating the type of concern to retrieve.
      Returns:
      The concern of the requested type.
      Throws:
      ConcernNotFoundException - if no concern of the requested type could be found.
      See Also:

    • run

      @Deprecated public static Thread run(@Nonnull Concern concern, @Nonnull Runnable runnable)
      Deprecated.
      This may be removed in a future version in favor of run(Runnable, Concern...).
      Executes a runnable in a separate thread, providing the given concern to the thread via a new concerned thread group. The returned thread will already be started.

      The concern will be accessible to the new thread using getConcern(Class) using the type returned by Concern.getConcernType().

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Implementation Specification:
      This implementation delegates to run(String, Runnable, Stream).
      Parameters:
      concern - The concern to be available to the new thread via a new thread group.
      runnable - The runnable to run in the thread.
      Returns:
      The thread executing the given runnable operation in the context of the given concern.
      Throws:
      NullPointerException - if the given concern and/or runnable is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also:

    • run

      public static Thread run(@Nonnull Runnable runnable, @Nonnull Concern... concerns)
      Executes a runnable in a separate thread, providing the given concerns to the thread via a new concerned thread group. The returned thread will already be started.

      The concerns will be accessible to the new thread using getConcern(Class). If more than one concern provided here has the same type returned by Concern.getConcernType(), the latter concern has priority.

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Implementation Specification:
      This implementation delegates to run(String, Runnable, Stream).
      Parameters:
      runnable - The runnable to run in the thread.
      concerns - The concerns to be available to the new thread via a new thread group.
      Returns:
      The thread executing the given runnable operation in the context of the given concerns.
      Throws:
      NullPointerException - if the given runnable and/or concerns is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also:

    • run

      public static Thread run(@Nonnull Runnable runnable, @Nonnull Stream<Concern> concerns)
      Executes a runnable in a separate thread, providing the given concerns to the thread via a new concerned thread group. The returned thread will already be started.

      The concerns will be accessible to the new thread using getConcern(Class). If more than one concern provided here has the same type returned by Concern.getConcernType(), the latter concern has priority.

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Implementation Specification:
      This implementation delegates to run(String, Runnable, Stream).
      Parameters:
      runnable - The runnable to run in the thread.
      concerns - The concerns to be available to the new thread via a new thread group.
      Returns:
      The thread executing the given runnable operation in the context of the given concerns.
      Throws:
      NullPointerException - if the given concerns and/or runnable is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also:

    • run

      @Deprecated public static Thread run(@Nonnull String threadName, @Nonnull Concern concern, @Nonnull Runnable runnable)
      Deprecated.
      This may be removed in a future version in favor of run(String, Runnable, Concern...).
      Executes a runnable in a separate thread, providing the given concern to the thread via a new concerned thread group. The returned thread will already be started.

      The concern will be accessible to the new thread using getConcern(Class) using the type returned by Concern.getConcernType().

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Implementation Specification:
      This implementation delegates to run(String, Runnable, Stream).
      Parameters:
      threadName - The name of the thread to create.
      concern - The concern to be available to the new thread via a new thread group.
      runnable - The runnable to run in the thread.
      Returns:
      The thread executing the given runnable operation in the context of the given concern.
      Throws:
      NullPointerException - if the given thread name, concern, and/or runnable is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also:

    • run

      public static Thread run(@Nonnull String threadName, @Nonnull Runnable runnable, @Nonnull Concern... concerns)
      Executes a runnable in a separate thread, providing the given concerns to the thread via a new concerned thread group. The returned thread will already be started.

      The concerns will be accessible to the new thread using getConcern(Class). If more than one concern provided here has the same type returned by Concern.getConcernType(), the latter concern has priority.

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Implementation Specification:
      This implementation delegates to run(String, Runnable, Stream).
      Parameters:
      threadName - The name of the thread to create.
      runnable - The runnable to run in the thread.
      concerns - The concerns to be available to the new thread via a new thread group.
      Returns:
      The thread executing the given runnable operation in the context of the given concerns.
      Throws:
      NullPointerException - if the given thread name, runnable, and/or concerns is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also:

    • run

      public static Thread run(@Nonnull String threadName, @Nonnull Runnable runnable, @Nonnull Stream<Concern> concerns)
      Executes a runnable in a separate thread, providing the given concerns to the thread via a new concerned thread group. The returned thread will already be started.

      The concerns will be accessible to the new thread using getConcern(Class). If more than one concern provided here has the same type returned by Concern.getConcernType(), the latter concern has priority.

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Parameters:
      threadName - The name of the thread to create.
      runnable - The runnable to run in the thread.
      concerns - The concerns to be available to the new thread via a new thread group.
      Returns:
      The thread executing the given runnable operation in the context of the given concerns.
      Throws:
      NullPointerException - if the given thread name, concerns, and/or runnable is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also:

    • createThread

      public static Thread createThread(@Nonnull String threadName, @Nonnull Runnable runnable, @Nonnull Concern... concerns)
      Creates a separate thread providing the given concerns via a new concerned thread group. The new thread is not started.

      The concerns will be accessible to the new thread using getConcern(Class). If more than one concern provided here has the same type returned by Concern.getConcernType(), the latter concern has priority.

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Implementation Specification:
      This implementation delegates to createThread(String, Runnable, Stream)
      Parameters:
      threadName - The name of the thread to create.
      runnable - The runnable to run in the thread.
      concerns - The concerns to be available to the new thread via a new thread group.
      Returns:
      A thread for executing the given runnable operation in the context of the given concerns.
      Throws:
      NullPointerException - if the given thread name, concerns, and/or runnable is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also:

    • createThread

      public static Thread createThread(@Nonnull String threadName, @Nonnull Runnable runnable, @Nonnull Collection<Concern> concerns)
      Creates a separate thread providing the given concerns via a new concerned thread group. The new thread is not started.

      The concerns will be accessible to the new thread using getConcern(Class). If more than one concern provided here has the same type returned by Concern.getConcernType(), the latter concern has priority.

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Implementation Specification:
      This implementation delegates to createThread(String, Runnable, Stream)
      Parameters:
      threadName - The name of the thread to create.
      runnable - The runnable to run in the thread.
      concerns - The concerns to be available to the new thread via a new thread group.
      Returns:
      A thread for executing the given runnable operation in the context of the given concerns.
      Throws:
      NullPointerException - if the given thread name, concerns, and/or runnable is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also:

    • createThread

      public static Thread createThread(@Nonnull String threadName, @Nonnull Runnable runnable, @Nonnull Stream<Concern> concerns)
      Creates a separate thread providing the given concerns via a new concerned thread group. The new thread is not started.

      The concerns will be accessible to the new thread using getConcern(Class). If more than one concern provided here has the same type returned by Concern.getConcernType(), the latter concern has priority.

      To wait for the operation to complete, simply call one of the Thread.join() methods on the returned thread.

      Parameters:
      threadName - The name of the thread to create.
      runnable - The runnable to run in the thread.
      concerns - The concerns to be available to the new thread via a new thread group.
      Returns:
      A thread for executing the given runnable operation in the context of the given concerns.
      Throws:
      NullPointerException - if the given thread name, concerns, and/or runnable is null.
      SecurityException - If the current thread cannot create a thread in the specified thread group.
      See Also: