Class Csar
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 Summary
Modifier and TypeMethodDescriptionstatic Thread
createThread
(String threadName, Runnable runnable, Concern... concerns) Creates a separate thread providing the given concerns via a new concerned thread group.static Thread
createThread
(String threadName, Runnable runnable, Collection<Concern> concerns) Creates a separate thread providing the given concerns via a new concerned thread group.static Thread
createThread
(String threadName, Runnable runnable, Stream<Concern> concerns) Creates a separate thread providing the given concerns via a new concerned thread group.findConcern
(Class<C> concernType) Retrieves an optional concern of the given type for the current thread.findConcern
(Thread thread, Class<T> concernType) Retrieves the concern of the given type for the indicated thread.findDefaultConcern
(Class<T> concernType) Returns the default concern for the given concern type.static <C extends Concern>
CgetConcern
(Class<C> concernType) Retrieves a concern of the given type for the current thread.registerDefaultConcern
(C concern) Registers the given concern as default for its concern type.registerDefaultConcern
(Class<T> concernType, C concern) Registers the given concern as default.static Thread
Deprecated.static Thread
Executes a runnable in a separate thread, providing the given concerns to the thread via a new concerned thread group.static Thread
Executes a runnable in a separate thread, providing the given concerns to the thread via a new concerned thread group.static Thread
Deprecated.This may be removed in a future version in favor ofrun(String, Runnable, Concern...)
.static Thread
Executes a runnable in a separate thread, providing the given concerns to the thread via a new concerned thread group.static Thread
Executes a runnable in a separate thread, providing the given concerns to the thread via a new concerned thread group.static void
setDefaultConcerns
(Concern... concerns) Registers the given concerns as defaults for their respective classes.static void
setDefaultConcerns
(Collection<Concern> concerns) Registers the given concerns as defaults for their respective classes.static void
setDefaultConcerns
(Stream<Concern> concerns) Registers the given concerns as defaults for their respective classes.unregisterDefaultConcern
(Class<T> concernType) Unregisters a default concern of the given type.
-
Method Details
-
setDefaultConcerns
Registers the given concerns as defaults for their respective classes.- Parameters:
concerns
- The concerns to register as defaults.
-
setDefaultConcerns
Registers the given concerns as defaults for their respective classes.- Parameters:
concerns
- The concerns to register as defaults.
-
setDefaultConcerns
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 isnull
.
-
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 isnull
.
-
findDefaultConcern
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 noConcerned
thread group is found for the thread, or no such concern is set for the thread group, a default concern is searched for usingfindDefaultConcern(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
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 noConcerned
thread group is found for the thread, or no such concern is set for the thread group, a default concern is searched for usingfindDefaultConcern(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 noConcerned
thread group is found for the thread, or no such concern is set for the thread group, a default concern is searched for usingfindDefaultConcern(Class)
. If no appropriate concern can be found, aConcernNotFoundException
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.This may be removed in a future version in favor ofrun(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 byConcern.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 isnull
.SecurityException
- If the current thread cannot create a thread in the specified thread group.- See Also:
-
run
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 byConcern.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 isnull
.SecurityException
- If the current thread cannot create a thread in the specified thread group.- See Also:
-
run
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 byConcern.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 isnull
.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 ofrun(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 byConcern.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 isnull
.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 byConcern.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 isnull
.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 byConcern.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 isnull
.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 byConcern.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 isnull
.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 byConcern.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 isnull
.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 byConcern.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 isnull
.SecurityException
- If the current thread cannot create a thread in the specified thread group.- See Also:
-
run(Runnable, Concern...)
.