ServiceBuilder (JBoss Modular Service Container 1.5.0.Beta3 API)

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

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
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.
`<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>`	`addListener(LifecycleListener listener)` Adds a service listener to be added to the service.
`ServiceBuilder<T>`	`addMonitor(StabilityMonitor monitor)` 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.
  - 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.
  - 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.

Interface ServiceBuilder<T>

Method Summary

Method Detail

requires

provides

setInitialMode

setInstance

addListener

install

addAliases

addDependency

addMonitor