Package org.jboss.msc

Interface Service

All Known Subinterfaces:
Service<T>, SingletonService, SingletonService<T>
All Known Implementing Classes:
ActiveMQActivationService, BinderService, ChildTargetService, DefaultNamespaceContextSelectorService, ExternalBrokerConfigurationService, ExternalConnectionFactoryService, ExternalContextBinderService, ExternalContextsService, ExternalJMSQueueService, ExternalJMSTopicService, ExternalPooledConnectionFactoryService, FunctionalService, GroupBindingService, HttpRemoteNamingServerService, HTTPUpgradeService, Installer.UnaryService, JMSQueueService, JMSService, JMSTopicService, JndiViewExtensionRegistry, LegacyConnectionFactoryService, NamingService, NamingStoreService, PooledConnectionFactoryService, PooledConnectionFactoryStatisticsService, RemoteNamingServerService, RuntimeBindReleaseService
public interface Service
A service is a thing which can be started and stopped. A service may be started or stopped from any thread. Service implementation should always take care to protect any mutable state appropriately. Service may provide multiple values to its consumers.

When writing MSC service implementations, your start(StartContext) and stop(StopContext) methods must never block. This means these methods must not:

  • Use network connections
  • Wait for network connections
  • Sleep
  • Wait on a condition
  • Wait on a count down latch
  • Call any method which may do any of the above
  • Wait for termination of a thread pool or other service
  • Wait for another service to change state
If your service start/stop does any of these things, you must use the asynchronous start/stop mechanism (LifecycleContext.asynchronous()) and do one of the following:
  • Initiate your task in start()/stop(), and utilize a callback (NIO, ThreadPoolExecutor.terminated(), etc.) to call LifecycleContext.complete() when your start/stop completes instead of blocking
  • Delegate your blocking task to a thread pool (Executor) which calls LifecycleContext.complete() when done
  • Use proper dependencies instead of explicitly waiting for services in your start/stop

Note that using LifecycleContext.execute(Runnable) to execute the blocking task is also not permissible.

Author:
David M. Lloyd, Richard Opalka

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Service
    NULL
    A simple null service whose start and stop methods do nothing.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <V> Service
    newInstance(Consumer<V> injector, V value)
    Factory for services providing single value.
    void
    start(StartContext context)
    Start the service.
    void
    stop(StopContext context)
    Stop the service.

  • Field Details

    • NULL

      static final Service NULL
      A simple null service whose start and stop methods do nothing.

  • Method Details

    • start

      void start(StartContext context) throws StartException
      Start the service. Do not return until the service has been fully started, unless an asynchronous service start is performed. All injections will be complete before this method is called.

      If the service start involves any activities that may block, the asynchronous mechanism provided by the context should be used. See the class javadoc for details.

      Parameters:
      context - the context which can be used to trigger an asynchronous service start
      Throws:
      StartException - if the service could not be started for some reason

    • stop

      void stop(StopContext context)
      Stop the service. Do not return until the service has been fully stopped, unless an asynchronous service stop is performed. All injections will remain intact until the service is fully stopped. This method should not throw an exception.

      If the service start involves any activities that may block, the asynchronous mechanism provided by the context should be used. See the class javadoc for details.

      Parameters:
      context - the context which can be used to trigger an asynchronous service stop

    • newInstance

      static <V> Service newInstance(Consumer<V> injector, V value)
      Factory for services providing single value.
      Type Parameters:
      V - provided value type
      Parameters:
      injector - target
      value - to assign
      Returns:
      new service instance