org.fourthline.cling.model

## Interface ServiceManager<T>

- Type Parameters:
    `T` - The interface expected by the bound `ActionExecutor`s and `StateVariableAccessor`s.
  All Known Implementing Classes:
    DefaultServiceManager

      public interface ServiceManager<T>

  Binds the metadata of a service to a service implementation, unified interface for accessing local services.

  The UPnP core will always access a local service implementation through this manager, available with `LocalService.getManager()`:

  - The `ActionExecutor`s use the manager to process UPnP control invocations. It's the service manager's job to translate such an action invocation into an actual method invocation, or any other procedure that satisfies the requirements. The `ActionExecutor` works together with the manager, for example, the `MethodActionExecutor` expects that an action method can be invoked through reflection on the instance returned by the manager's `getImplementation()` method. This is possible with the the `DefaultServiceManager`. A different service manager might require a different set of action executors, and vice versa.
  - The `StateVariableAccessor`s use the manager to process UPnP state variable queries and GENA eventing. It's the service manager's job to return an actual value when a state variable has to be read. The `StateVariableAccessor` works together with the service manager, for example, the `FieldStateVariableAccessor` expects that a state variable value can be read through reflection on a field, of the instance returned by `getImplementation()`. This is possible with the `DefaultServiceManager`. A different service manager might require a different set of state variable accessors, and vice versa.
  - A service manager has to notify the UPnP core, and especially the GENA eventing system, whenever the state of any evented UPnP state variable changes. For new subscriptions GENA also has to read the current state of the service manually, when the subscription has been established and an initial event message has to be send to the subscriber.

  A service manager can implement these concerns in any way imaginable. It has to be thread-safe.

  Author:
    Christian Bauer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `EVENTED_STATE_VARIABLES` Use this property name when propagating change events that affect any evented UPnP state variable.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `execute(Command<T> cmd)` Double-dispatch of arbitrary commands, used by action executors and state variable accessors.
    `Collection<StateVariableValue>` | `getCurrentState()` Reading the state of a service manually.
    `T` | `getImplementation()`
    `PropertyChangeSupport` | `getPropertyChangeSupport()` Provides the capability to monitor the service for state changes.
    `LocalService<T>` | `getService()`

- - ### Field Detail

    - #### EVENTED_STATE_VARIABLES

          static final String EVENTED_STATE_VARIABLES

      Use this property name when propagating change events that affect any evented UPnP state variable. This name is detected by the GENA subsystem.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getService

          LocalService<T> getService()

      Returns:
        The metadata of the service to which this manager is assigned.

    - #### getImplementation

          T getImplementation()

      Returns:
        An instance with the interface expected by the bound `ActionExecutor`s and `StateVariableAccessor`s.

    - #### execute

          void execute(Command<T> cmd)
                throws Exception

      Double-dispatch of arbitrary commands, used by action executors and state variable accessors.

      The service manager will execute the given `Command` and it might decorate the execution, for example, by locking/unlocking access to a shared service implementation before and after the execution.

      Parameters:
        `cmd` - The command to execute.
      Throws:
        `Exception` - Any exception, without wrapping, as thrown by `Command.execute(ServiceManager)`

    - #### getPropertyChangeSupport

          PropertyChangeSupport getPropertyChangeSupport()

      Provides the capability to monitor the service for state changes.

      The GENA subsystem expects that this adapter will notify its listeners whenever any evented UPnP state variable of the service has changed its state. The following change event is expected:

      - The property name is the constant `EVENTED_STATE_VARIABLES`.
      - The "old value" can be `null`, only the current state has to be included.
      - The "new value" is a `Collection` of `StateVariableValue`, representing the current state of the service after the change.

      The collection has to include values for all state variables, no matter what state variable was updated. Any other event is ignored (e.g. individual property changes).

      Returns:
        An adapter that will notify its listeners whenever any evented state variable changes.

    - #### getCurrentState

          Collection<StateVariableValue> getCurrentState()
                                                  throws Exception

      Reading the state of a service manually.
      Returns:
        A `Collection` of `StateVariableValue`, representing the current state of the service, that is, all evented state variable values.
      Throws:
        `Exception` - Any error that occurred when the service's state was accessed.

Copyright © 2016 4th Line GmbH, Switzerland. All rights reserved.