Interface ServiceController<S>

  • Type Parameters:
    S - the service type
    All Superinterfaces:
    Value<S>
    All Known Implementing Classes:
    ServiceControllerImpl

    public interface ServiceController<S>
    extends Value<S>
    A controller for a single service instance.
    • Method Detail

      • getParent

        ServiceController<?> getParent()
        Get this service's parent service, or null if there is none.
        Returns:
        the parent service or null if this service has no parent
      • getServiceContainer

        ServiceContainer getServiceContainer()
        Get the service container associated with this controller.
        Returns:
        the container
      • getMode

        ServiceController.Mode getMode()
        Get the service controller's current mode.
        Returns:
        the controller mode
      • compareAndSetMode

        boolean compareAndSetMode​(ServiceController.Mode expected,
                                  ServiceController.Mode newMode)
        Compare the current mode against expected; if it matches, change it to newMode. The return value is true when the mode was matched and changed.
        Parameters:
        expected - the expected mode
        newMode - the new mode
        Returns:
        true if the mode was changed
      • setMode

        void setMode​(ServiceController.Mode mode)
        Change the service controller's current mode. Might result in the service starting or stopping. The mode may only be changed if it was not already set to ServiceController.Mode.REMOVE. Calling this method with the controller's current mode has no effect and is always allowed.
        Parameters:
        mode - the new controller mode
        Throws:
        java.lang.IllegalStateException - if the mode given is null, or the caller attempted to change the service's mode from ServiceController.Mode.REMOVE to a different mode
      • getState

        ServiceController.State getState()
        Get the current service controller state.
        Returns:
        the current state
      • getSubstate

        ServiceController.Substate getSubstate()
        Get the current service controller substate.
        Returns:
        the current substate
      • getValue

        S getValue()
            throws java.lang.IllegalStateException
        Get the service value.
        Specified by:
        getValue in interface Value<S>
        Returns:
        the service value
        Throws:
        java.lang.IllegalStateException - if the service is not available (i.e. it is not up)
      • awaitValue

        S awaitValue()
              throws java.lang.IllegalStateException,
                     java.lang.InterruptedException
        Wait for a service to come up, and then return its value.
        Returns:
        the service value
        Throws:
        java.lang.IllegalStateException - if the service is not available (i.e. it was removed or failed)
        java.lang.InterruptedException - if the wait operation was interrupted
      • awaitValue

        S awaitValue​(long time,
                     java.util.concurrent.TimeUnit unit)
              throws java.lang.IllegalStateException,
                     java.lang.InterruptedException,
                     java.util.concurrent.TimeoutException
        Wait for a service to come up for a certain amount of time, and then return its value.
        Parameters:
        time - the amount of time to wait
        unit - the unit of time to wait
        Returns:
        the service value
        Throws:
        java.lang.IllegalStateException - if the service is not available (i.e. it was removed or failed)
        java.lang.InterruptedException - if the wait operation was interrupted
        java.util.concurrent.TimeoutException
      • getService

        Service<S> getService()
                       throws java.lang.IllegalStateException
        Get the service.
        Returns:
        the service
        Throws:
        java.lang.IllegalStateException - if the service is not available (i.e. it is not up)
      • getName

        ServiceName getName()
        Get the name of this service, if any.
        Returns:
        the name, or null if none was specified.
      • getAliases

        ServiceName[] getAliases()
        Get other names this service is known as.
        Returns:
        the aliases
      • addListener

        void addListener​(ServiceListener<? super S> serviceListener)
        Add a service listener. The listener's "listener added" callback will be invoked from the same thread that calls this method. Then, the method corresponding to the current service state is called.
        Parameters:
        serviceListener - the service listener
      • removeListener

        void removeListener​(ServiceListener<? super S> serviceListener)
        Remove a service listener.
        Parameters:
        serviceListener - the service listener to remove
      • getStartException

        StartException getStartException()
        Get the reason why the last start failed.
        Returns:
        the last start exception, or null if the last start succeeded or the service has not yet started
      • getImmediateUnavailableDependencies

        java.util.Set<ServiceName> getImmediateUnavailableDependencies()
        Get the complete list of immediate dependencies that are unavailable.
        Returns:
        a set containing the names of all unavailable immediate dependencies