org.jboss.msc.service

Interface ServiceBuilder<T>

Type Parameters:

T - service value type if service provides single value

All Known Implementing Classes:

DelegatingServiceBuilder

public interface ServiceBuilder<T>

Builder to configure service before installing it into the container.

Service may require multiple dependencies (named values) to be satisfied before starting. Every dependency requirement must be specified via requires(ServiceName) method.

Single service can provide multiple values which can be requested by dependent services. Every named value service provides must be specified via provides(ServiceName...) method.

Once all required and provided dependencies are defined, references to all Consumers and Suppliers should be passed to service instance so they can be accessed by service at runtime.

Implementations of this interface are thread safe because they rely on thread confinement. The builder instance can be used only by thread that created it.

Author:

David M. Lloyd, Richard Opalka

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ServiceBuilder.DependencyType Deprecated. Optional dependencies are unsafe and should not be used. This enum will be removed in a future release.

Method Summary

Modifier and Type	Method and Description
ServiceBuilder<T>	addAliases(ServiceName... aliases) Deprecated. Use provides(ServiceName...) instead. This method will be removed in a future release.
ServiceBuilder<T>	addDependencies(Iterable<ServiceName> dependencies) Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.
ServiceBuilder<T>	addDependencies(ServiceBuilder.DependencyType dependencyType, Iterable<ServiceName> dependencies) Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.
ServiceBuilder<T>	addDependencies(ServiceBuilder.DependencyType dependencyType, ServiceName... dependencies) Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.
ServiceBuilder<T>	addDependencies(ServiceName... dependencies) Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.
ServiceBuilder<T>	addDependency(ServiceBuilder.DependencyType dependencyType, ServiceName dependency) Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.
<I> ServiceBuilder<T>	addDependency(ServiceBuilder.DependencyType dependencyType, ServiceName dependency, Class<I> type, Injector<I> target) Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.
ServiceBuilder<T>	addDependency(ServiceBuilder.DependencyType dependencyType, ServiceName dependency, Injector<Object> target) Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.
ServiceBuilder<T>	addDependency(ServiceName dependency) Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.
<I> ServiceBuilder<T>	addDependency(ServiceName dependency, Class<I> type, Injector<I> target) Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.
ServiceBuilder<T>	addDependency(ServiceName dependency, Injector<Object> target) Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.
<I> ServiceBuilder<T>	addInjection(Injector<? super I> target, I value) Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.
ServiceBuilder<T>	addInjection(Injector<? super T> target) Deprecated. Use provides(ServiceName...) instead. This method will be removed in a future release.
<I> ServiceBuilder<T>	addInjectionValue(Injector<? super I> target, Value<I> value) Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.
ServiceBuilder<T>	addListener(Collection<? extends ServiceListener<? super T>> listeners) Deprecated. Use addListener(LifecycleListener) instead. This method will be removed in a future release.
ServiceBuilder<T>	addListener(LifecycleListener listener) Adds a service listener to be added to the service.
ServiceBuilder<T>	addListener(ServiceListener<? super T>... listeners) Deprecated. Use addListener(LifecycleListener) instead. This method will be removed in a future release.
ServiceBuilder<T>	addListener(ServiceListener<? super T> listener) Deprecated. Use addListener(LifecycleListener) instead. This method will be removed in a future release.
ServiceBuilder<T>	addMonitor(StabilityMonitor monitor) Deprecated. Stability monitors are unreliable - do not use them. This method will be removed in a future release.
ServiceBuilder<T>	addMonitors(StabilityMonitor... monitors) Deprecated. Stability monitors are unreliable - do not use them. This method will be removed in a future release.
ServiceController<T>	install() Installs configured service into the container.
<V> Consumer<V>	provides(ServiceName... names) Specifies value provided by service.
<V> Supplier<V>	requires(ServiceName name) Specifies value name required by service.
ServiceBuilder<T>	setInitialMode(ServiceController.Mode mode) Sets initial service mode.
ServiceBuilder<T>	setInstance(Service service) Sets service instance.

Method Detail

requires

<V> Supplier<V> requires(ServiceName name)

Specifies value name required by service. There can be multiple values service may depend on.

Type Parameters:

V - required dependency value type

Parameters:

name - required dependency name

Returns:

readonly dependency reference

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalArgumentException - if value name was before used as parameter either in ServiceTarget.addService(ServiceName) method when creating this builder instance or in provides(ServiceName...) method call. Value can be either required or provided but not both.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if name parameter is null.

provides

<V> Consumer<V> provides(ServiceName... names)

Specifies value provided by service. There can be multiple names for the same value. At least one name parameter must be provided to this method. If there are more names in the vararg array then the first one is called provided value name and other are called provided value aliases.

Type Parameters:

V - provided value type

Parameters:

names - provided value name (and its aliases)

Returns:

writable dependency reference

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalArgumentException - if value name was before used as parameter in in requires(ServiceName) method call. Value can be either required or provided but not both.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if names parameter is null or any value of the vararg array is null.

setInitialMode

ServiceBuilder<T> setInitialMode(ServiceController.Mode mode)

Sets initial service mode.

Parameters:

mode - initial service mode

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalArgumentException - if mode is ServiceController.Mode.REMOVE.

IllegalStateException - if this method have been either called twice or it was called after install() method.

NullPointerException - if mode parameter is null.

setInstance

ServiceBuilder<T> setInstance(Service service)

Sets service instance. If install() method call is issued without this method being called then NULL service will be installed into the container.

Once this method have been called then all subsequent calls of requires(ServiceName), and provides(ServiceName...) methods will fail because their return values should be provided to service instance.

Parameters:

service - the service instance

Returns:

this configurator

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been either called twice or it was called after install() method.

addListener

ServiceBuilder<T> addListener(LifecycleListener listener)

Adds a service listener to be added to the service.

Parameters:

listener - the listener to add to the service

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if listener parameter is null.

install

ServiceController<T> install()

Installs configured service into the container.

Returns:

installed service controller

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called twice.

ServiceRegistryException - if installation fails for any reason

addAliases

@Deprecated
ServiceBuilder<T> addAliases(ServiceName... aliases)

Deprecated. Use provides(ServiceName...) instead. This method will be removed in a future release.

Adds aliases for this service.

Parameters:

aliases - the service names to use as aliases

Returns:

the builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalArgumentException - if value name was before used as parameter in in requires(ServiceName) method call. Value can be either required or provided but not both.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if aliases parameter is null or any value of the vararg array is null.

addDependencies

@Deprecated
ServiceBuilder<T> addDependencies(ServiceName... dependencies)

Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.

Add multiple, non-injected dependencies.

Parameters:

dependencies - the service names to depend on

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependencies parameter is null or any value of the vararg array is null.

addDependencies

@Deprecated
ServiceBuilder<T> addDependencies(ServiceBuilder.DependencyType dependencyType,
                                              ServiceName... dependencies)

Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.

Add multiple, non-injected dependencies.

Parameters:

dependencyType - the dependency type; must not be null

dependencies - the service names to depend on

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependencyType or dependencies parameter is null or any value of the vararg array is null.

addDependencies

@Deprecated
ServiceBuilder<T> addDependencies(Iterable<ServiceName> dependencies)

Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.

Add multiple, non-injected dependencies.

Parameters:

dependencies - the service names to depend on

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependencies parameter is null or any value of the iterable is null.

addDependencies

@Deprecated
ServiceBuilder<T> addDependencies(ServiceBuilder.DependencyType dependencyType,
                                              Iterable<ServiceName> dependencies)

Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.

Add multiple, non-injected dependencies.

Parameters:

dependencyType - the dependency type; must not be null

dependencies - the service names to depend on

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependencyType or dependencies parameter is null or any value of the iterable is null.

addDependency

@Deprecated
ServiceBuilder<T> addDependency(ServiceName dependency)

Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.

Add a dependency. Calling this method multiple times for the same service name will only add it as a dependency one time; however this may be useful to specify multiple injections for one dependency.

Parameters:

dependency - the name of the dependency

Returns:

an injection builder for optionally injecting the dependency

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependency parameter is null.

addDependency

@Deprecated
ServiceBuilder<T> addDependency(ServiceBuilder.DependencyType dependencyType,
                                            ServiceName dependency)

Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.

Add a dependency. Calling this method multiple times for the same service name will only add it as a dependency one time; however this may be useful to specify multiple injections for one dependency.

Parameters:

dependencyType - the dependency type; must not be null

dependency - the name of the dependency

Returns:

an injection builder for optionally injecting the dependency

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependencyType or dependency parameter is null.

addDependency

@Deprecated
ServiceBuilder<T> addDependency(ServiceName dependency,
                                            Injector<Object> target)

Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.

Add a service dependency. Calling this method multiple times for the same service name will only add it as a dependency one time; however this may be useful to specify multiple injections for one dependency.

Parameters:

dependency - the name of the dependency

target - the injector into which the dependency should be stored

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependency or target parameter is null.

addDependency

@Deprecated
ServiceBuilder<T> addDependency(ServiceBuilder.DependencyType dependencyType,
                                            ServiceName dependency,
                                            Injector<Object> target)

Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.

Add a service dependency. Calling this method multiple times for the same service name will only add it as a dependency one time; however this may be useful to specify multiple injections for one dependency.

Parameters:

dependencyType - the dependency type; must not be null

dependency - the name of the dependency

target - the injector into which the dependency should be stored

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependencyType or dependency or target parameter is null.

addDependency

@Deprecated
<I> ServiceBuilder<T> addDependency(ServiceName dependency,
                                                Class<I> type,
                                                Injector<I> target)

Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.

Add a service dependency. The type of the dependency is checked before it is passed into the (type-safe) injector instance. Calling this method multiple times for the same service name will only add it as a dependency one time; however this may be useful to specify multiple injections for one dependency.

Type Parameters:

I - the type of the value of the dependency

Parameters:

dependency - the name of the dependency

type - the class of the value of the dependency

target - the injector into which the dependency should be stored

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependency or type or target parameter is null.

addDependency

@Deprecated
<I> ServiceBuilder<T> addDependency(ServiceBuilder.DependencyType dependencyType,
                                                ServiceName dependency,
                                                Class<I> type,
                                                Injector<I> target)

Deprecated. Optional dependencies are unsafe and should not be used. This method will be removed in a future release.

Add a service dependency. The type of the dependency is checked before it is passed into the (type-safe) injector instance. Calling this method multiple times for the same service name will only add it as a dependency one time; however this may be useful to specify multiple injections for one dependency.

Type Parameters:

I - the type of the value of the dependency

Parameters:

dependencyType - the dependency type; must not be null

dependency - the name of the dependency

type - the class of the value of the dependency

target - the injector into which the dependency should be stored

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if dependencyType or dependency or type or target parameter is null.

addInjection

@Deprecated
<I> ServiceBuilder<T> addInjection(Injector<? super I> target,
                                               I value)

Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.

Add an injection. The given value will be injected into the given injector before service start, and uninjected after service stop.

Type Parameters:

I - the injection type

Parameters:

target - the injection target

value - the injection value

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if target or value parameter is null.

addInjectionValue

@Deprecated
<I> ServiceBuilder<T> addInjectionValue(Injector<? super I> target,
                                                    Value<I> value)

Deprecated. Use requires(ServiceName) instead. This method will be removed in a future release.

Add an injection value. The given value will be injected into the given injector before service start, and uninjected after service stop.

Type Parameters:

I - the injection type

Parameters:

target - the injection target

value - the injection value

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if target or value parameter is null.

addInjection

@Deprecated
ServiceBuilder<T> addInjection(Injector<? super T> target)

Deprecated. Use provides(ServiceName...) instead. This method will be removed in a future release.

Add an injection of this service into another target. The given injector will be given this service after start, and uninjected when this service stops.

Differently from other injection types, failures to perform an outward injection will not result in a failure to start the service.

Parameters:

target - the injector target

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if target parameter is null.

addMonitor

@Deprecated
ServiceBuilder<T> addMonitor(StabilityMonitor monitor)

Deprecated. Stability monitors are unreliable - do not use them. This method will be removed in a future release.

Adds a stability monitor to be added to the service.

Parameters:

monitor - the monitor to add to the service

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if monitor parameter is null.

addMonitors

@Deprecated
ServiceBuilder<T> addMonitors(StabilityMonitor... monitors)

Deprecated. Stability monitors are unreliable - do not use them. This method will be removed in a future release.

Add service stability monitors that will be added to this service.

Parameters:

monitors - a list of stability monitors to add to the service

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if monitors parameter is null or any value of the vararg array is null.

addListener

@Deprecated
ServiceBuilder<T> addListener(ServiceListener<? super T> listener)

Deprecated. Use addListener(LifecycleListener) instead. This method will be removed in a future release.

Add a service listener that will be added to this service.

Parameters:

listener - the listener to add to the service

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if listener parameter is null.

addListener

@Deprecated
ServiceBuilder<T> addListener(ServiceListener<? super T>... listeners)

Deprecated. Use addListener(LifecycleListener) instead. This method will be removed in a future release.

Add service listeners that will be added to this service.

Parameters:

listeners - a list of listeners to add to the service

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if listeners parameter is null or any value of the vararg array is null.

addListener

@Deprecated
ServiceBuilder<T> addListener(Collection<? extends ServiceListener<? super T>> listeners)

Deprecated. Use addListener(LifecycleListener) instead. This method will be removed in a future release.

Add service listeners that will be added to this service.

Parameters:

listeners - a collection of listeners to add to the service

Returns:

this builder

Throws:

ConcurrentModificationException - if builder is shared between threads. Only thread that created the builder can manipulate it.

IllegalStateException - if this method have been called after install() method.

NullPointerException - if listeners parameter is null or any value of the listeners collection is null.