Module org.eclipse.jetty.util
Package org.eclipse.jetty.util.component

Class ContainerLifeCycle

  • All Implemented Interfaces:
    Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle
    Direct Known Subclasses:
    AdaptiveExecutionStrategy, AttributeContainerMap, ExecutorThreadPool, KeyStoreScanner, QueuedThreadPool, Scanner
    @ManagedObject("Implementation of Container and LifeCycle")
public class ContainerLifeCycle
extends AbstractLifeCycle
implements Container, Destroyable, Dumpable.DumpableContainer
    A ContainerLifeCycle is an LifeCycle implementation for a collection of contained beans.

    Beans can be added to the ContainerLifeCycle either as managed beans or as unmanaged beans. A managed bean is started, stopped and destroyed with the aggregate. An unmanaged bean is associated with the aggregate for the purposes of dump(), but its lifecycle must be managed externally.

    When a LifeCycle bean is added without a managed state being specified the state is determined heuristically:

    • If the added bean is running, it will be added as an unmanaged bean.
    • If the added bean is !running and the container is !running, it will be added as an AUTO bean (see below).
    • If the added bean is !running and the container is starting, it will be added as a managed bean and will be started (this handles the frequent case of new beans added during calls to doStart).
    • If the added bean is !running and the container is started, it will be added as an unmanaged bean.
    When the container is started, then all contained managed beans will also be started. Any contained AUTO beans will be check for their status and if already started will be switched unmanaged beans, else they will be started and switched to managed beans. Beans added after a container is started are not started and their state needs to be explicitly managed.

    When stopping the container, a contained bean will be stopped by this aggregate only if it is started by this aggregate.

    The methods addBean(Object, boolean), manage(Object) and unmanage(Object) can be used to explicitly control the life cycle relationship.

    If adding a bean that is shared between multiple ContainerLifeCycle instances, then it should be started before being added, so it is unmanaged, or the API must be used to explicitly set it as unmanaged.

    All EventListeners added via addEventListener(EventListener) are also added as beans and all beans added via an addBean(Object) method that are also EventListeners are added as listeners via a call to addEventListener(EventListener).

    This class also provides utility methods to dump deep structures of objects. In the dump, the following symbols are used to indicate the type of contained object: 

     SomeContainerLifeCycleInstance
   +- contained POJO instance
   += contained MANAGED object, started and stopped with this instance
   +~ referenced UNMANAGED object, with separate lifecycle
   +? referenced AUTO object that could become MANAGED or UNMANAGED.

    • Constructor Detail

      • ContainerLifeCycle

        public ContainerLifeCycle()

    • Method Detail

      • doStart

        protected void doStart()
                throws java.lang.Exception
        Starts the managed lifecycle beans in the order they were added.
        Overrides:
        doStart in class AbstractLifeCycle
        Throws:
        AbstractLifeCycle.StopException - If thrown, the lifecycle will immediately be stopped.
        java.lang.Exception - If there was a problem starting. Will cause a transition to FAILED state

      • start

        protected void start​(LifeCycle l)
              throws java.lang.Exception
        Starts the given lifecycle.
        Parameters:
        l - the lifecycle to start
        Throws:
        java.lang.Exception - if unable to start lifecycle

      • stop

        protected void stop​(LifeCycle l)
             throws java.lang.Exception
        Stops the given lifecycle.
        Parameters:
        l - the lifecycle to stop
        Throws:
        java.lang.Exception - if unable to stop the lifecycle

      • doStop

        protected void doStop()
               throws java.lang.Exception
        Stops the managed lifecycle beans in the reverse order they were added.
        Overrides:
        doStop in class AbstractLifeCycle
        Throws:
        java.lang.Exception - If there was a problem stopping. Will cause a transition to FAILED state

      • destroy

        public void destroy()
        Destroys the managed Destroyable beans in the reverse order they were added.
        Specified by:
        destroy in interface Destroyable

      • contains

        public boolean contains​(java.lang.Object bean)
        Parameters:
        bean - the bean to test
        Returns:
        whether this aggregate contains the bean

      • isManaged

        public boolean isManaged​(java.lang.Object bean)
        Description copied from interface: Container
        Test if this container manages a bean
        Specified by:
        isManaged in interface Container
        Parameters:
        bean - the bean to test
        Returns:
        whether this aggregate contains and manages the bean

      • isAuto

        public boolean isAuto​(java.lang.Object bean)
        Parameters:
        bean - the bean to test
        Returns:
        whether this aggregate contains the bean in auto state

      • isUnmanaged

        public boolean isUnmanaged​(java.lang.Object bean)
        Parameters:
        bean - the bean to test
        Returns:
        whether this aggregate contains the bean in auto state

      • addBean

        public boolean addBean​(java.lang.Object o)
        Adds the given bean, detecting whether to manage it or not. If the bean is a LifeCycle, then it will be managed if it is not already started and not managed if it is already started. The addBean(Object, boolean) method should be used if this is not correct, or the manage(Object) and unmanage(Object) methods may be used after an add to change the status.
        Specified by:
        addBean in interface Container
        Parameters:
        o - the bean object to add
        Returns:
        true if the bean was added, false if it was already present

      • addBean

        public boolean addBean​(java.lang.Object o,
                       boolean managed)
        Adds the given bean, explicitly managing it or not.
        Specified by:
        addBean in interface Container
        Parameters:
        o - The bean object to add
        managed - whether to managed the lifecycle of the bean
        Returns:
        true if the bean was added, false if it was already present

      • addManaged

        public void addManaged​(LifeCycle lifecycle)
        Adds a managed lifecycle.

        This is a convenience method that uses addBean(lifecycle,true) and then ensures that the added bean is started iff this container is running. Exception from nested calls to start are caught and wrapped as RuntimeExceptions

        Parameters:
        lifecycle - the managed lifecycle to add

      • manage

        public void manage​(java.lang.Object bean)
        Manages a bean already contained by this aggregate, so that it is started/stopped/destroyed with this aggregate.
        Specified by:
        manage in interface Container
        Parameters:
        bean - The bean to manage (must already have been added).

      • unmanage

        public void unmanage​(java.lang.Object bean)
        Unmanages a bean already contained by this aggregate, so that it is not started/stopped/destroyed with this aggregate.
        Specified by:
        unmanage in interface Container
        Parameters:
        bean - The bean to unmanage (must already have been added).

      • setBeans

        public void setBeans​(java.util.Collection<java.lang.Object> beans)

      • getBeans

        public java.util.Collection<java.lang.Object> getBeans()
        Specified by:
        getBeans in interface Container
        Returns:
        the collection of beans known to this aggregate, in the order they were added.

      • getBeans

        public <T> java.util.Collection<T> getBeans​(java.lang.Class<T> clazz)
        Specified by:
        getBeans in interface Container
        Type Parameters:
        T - the Bean type
        Parameters:
        clazz - the class of the beans
        Returns:
        a list of beans of the given class (or subclass), in the order they were added.
        See Also:
        Container.getBeans(), Container.getContainedBeans(Class)

      • getBean

        public <T> T getBean​(java.lang.Class<T> clazz)
        Specified by:
        getBean in interface Container
        Type Parameters:
        T - the Bean type
        Parameters:
        clazz - the class of the bean
        Returns:
        the first bean (in order added) of a specific class (or subclass), or null if no such bean exist

      • removeBeans

        public void removeBeans()
        Removes all bean

      • removeBean

        public boolean removeBean​(java.lang.Object o)
        Description copied from interface: Container
        Removes the given bean. If the bean is-a EventListener, then also do an implicit Container.removeEventListener(EventListener).
        Specified by:
        removeBean in interface Container
        Parameters:
        o - the bean to remove
        Returns:
        whether the bean was removed

      • dumpStdErr

        @ManagedOperation("Dump the object to stderr")
public void dumpStdErr()
        Dumps to System.err.
        See Also:
        dump()

      • dump

        public void dump​(java.lang.Appendable out,
                 java.lang.String indent)
          throws java.io.IOException
        Description copied from interface: Dumpable
        Dump this object (and children) into an Appendable using the provided indent after any new lines. The indent should not be applied to the first object dumped.
        Specified by:
        dump in interface Dumpable
        Parameters:
        out - The appendable to dump to
        indent - The indent to apply after any new lines.
        Throws:
        java.io.IOException - if unable to write to Appendable

      • dump

        public void dump​(java.lang.Appendable out)
          throws java.io.IOException
        Dump this object to an Appendable with no indent.
        Parameters:
        out - The appendable to dump to.
        Throws:
        java.io.IOException - May be thrown by the Appendable

      • dumpObjects

        protected void dumpObjects​(java.lang.Appendable out,
                           java.lang.String indent,
                           java.lang.Object... items)
                    throws java.io.IOException
        Dump this object, it's contained beans and additional items to an Appendable
        Parameters:
        out - The appendable to dump to
        indent - The indent to apply after any new lines
        items - Additional items to be dumped as contained.
        Throws:
        java.io.IOException - May be thrown by the Appendable

      • updateBean

        public void updateBean​(java.lang.Object oldBean,
                       java.lang.Object newBean)

      • updateBean

        public void updateBean​(java.lang.Object oldBean,
                       java.lang.Object newBean,
                       boolean managed)

      • updateBeans

        public void updateBeans​(java.lang.Object[] oldBeans,
                        java.lang.Object[] newBeans)

      • updateBeans

        public void updateBeans​(java.util.Collection<?> oldBeans,
                        java.util.Collection<?> newBeans)

      • getContainedBeans

        public <T> java.util.Collection<T> getContainedBeans​(java.lang.Class<T> clazz)
        Specified by:
        getContainedBeans in interface Container
        Type Parameters:
        T - the Bean type
        Parameters:
        clazz - the class of the beans
        Returns:
        the list of beans of the given class from the entire Container hierarchy. The order is by depth first and then the order beans were added.

      • getContainedBeans

        protected <T> void getContainedBeans​(java.lang.Class<T> clazz,
                                     java.util.Collection<T> beans)