com.linecorp.armeria.common.util

Class StartStopSupport<T,U,V,L>

java.lang.Object

com.linecorp.armeria.common.util.StartStopSupport<T,U,V,L>

Type Parameters:

T - the type of the startup argument. Use Void if unused.

U - the type of the shutdown argument. Use Void if unused.

V - the type of the startup result. Use Void if unused.

L - the type of the life cycle event listener. Use Void if unused.

All Implemented Interfaces:

AsyncCloseable, ListenableAsyncCloseable, AutoCloseable

public abstract class StartStopSupport<T,U,V,L>
extends Object
implements ListenableAsyncCloseable

Provides asynchronous start-stop life cycle support.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StartStopSupport(Executor executor) Creates a new instance.

Method Summary

Modifier and Type	Method and Description
void	addListener(L listener) Adds the specified listener, so that it is notified when the state of this StartStopSupport changes.
void	close() A synchronous version of stop(Object).
CompletableFuture<?>	closeAsync() Releases any underlying resources held by this object asynchronously.
protected void	closeFailed(Throwable cause) Invoked when failed to stop in close().
protected abstract CompletionStage<V>	doStart(T arg) Invoked by start(Object, boolean) to perform the actual startup.
protected abstract CompletionStage<Void>	doStop(U arg) Invoked by stop(Object) to perform the actual startup, or indirectly by start(Object, boolean) when startup failed.
boolean	isClosed() Returns whether AsyncCloseable.close() or AsyncCloseable.closeAsync() operation has been completed.
boolean	isClosing() Returns whether AsyncCloseable.close() or AsyncCloseable.closeAsync() has been called.
protected void	notificationFailed(L listener, Throwable cause) Invoked when an event listener raises an exception.
protected void	notifyStarted(L listener, T arg, V result) Invoked when the startup procedure is finished.
protected void	notifyStarting(L listener, T arg) Invoked when the startup procedure begins.
protected void	notifyStopped(L listener, U arg) Invoked when the shutdown procedure is finished.
protected void	notifyStopping(L listener, U arg) Invoked when the shutdown procedure begins.
boolean	removeListener(L listener) Removes the specified listener, so that it is not notified anymore.
protected void	rollbackFailed(Throwable cause) Invoked when failed to stop during the rollback after startup failure.
CompletableFuture<V>	start(boolean failIfStarted) Begins the startup procedure without an argument by calling doStart(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently.
CompletableFuture<V>	start(T arg, boolean failIfStarted) Begins the startup procedure without an argument by calling doStart(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently.
CompletableFuture<V>	start(T arg, U rollbackArg, boolean failIfStarted) Begins the startup procedure by calling doStart(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently.
CompletableFuture<Void>	stop() Begins the shutdown procedure without an argument by calling doStop(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently.
CompletableFuture<Void>	stop(U arg) Begins the shutdown procedure by calling doStop(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently.
String	toString()
CompletableFuture<?>	whenClosed() Returns the CompletableFuture which is completed after the AsyncCloseable.close() or AsyncCloseable.closeAsync() operation is completed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

StartStopSupport

protected StartStopSupport(Executor executor)

Creates a new instance.

Parameters:

executor - the Executor which will be used for invoking the extension points of this class:

• doStart(Object)
• doStop(Object)
• rollbackFailed(Throwable)
• notificationFailed(Object, Throwable)
• All listener notifications

.. except closeFailed(Throwable) which is invoked at the caller thread.

Method Detail

addListener

public final void addListener(L listener)

Adds the specified listener, so that it is notified when the state of this StartStopSupport changes.

removeListener

public final boolean removeListener(L listener)

Removes the specified listener, so that it is not notified anymore.

start

public final CompletableFuture<V> start(boolean failIfStarted)

Begins the startup procedure without an argument by calling doStart(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently. When the startup fails, stop() will be invoked automatically to roll back the side effect caused by this method and any exceptions that occurred during the rollback will be reported to rollbackFailed(Throwable). This method is a shortcut for start(null, null, failIfStarted).

Parameters:

failIfStarted - whether to fail the returned CompletableFuture with an IllegalStateException when the startup procedure is already in progress or done

start

public final CompletableFuture<V> start(T arg,
                                        boolean failIfStarted)

Begins the startup procedure without an argument by calling doStart(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently. When the startup fails, stop() will be invoked automatically to roll back the side effect caused by this method and any exceptions that occurred during the rollback will be reported to rollbackFailed(Throwable). This method is a shortcut for start(arg, null, failIfStarted).

Parameters:

arg - the argument to pass to doStart(Object), or null to pass no argument.

failIfStarted - whether to fail the returned CompletableFuture with an IllegalStateException when the startup procedure is already in progress or done

start

public final CompletableFuture<V> start(T arg,
                                        U rollbackArg,
                                        boolean failIfStarted)

Begins the startup procedure by calling doStart(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently. When the startup fails, stop(Object) will be invoked with the specified rollbackArg automatically to roll back the side effect caused by this method and any exceptions that occurred during the rollback will be reported to rollbackFailed(Throwable).

Parameters:

arg - the argument to pass to doStart(Object), or null to pass no argument.

rollbackArg - the argument to pass to doStop(Object) when rolling back.

failIfStarted - whether to fail the returned CompletableFuture with an IllegalStateException when the startup procedure is already in progress or done

stop

public final CompletableFuture<Void> stop()

Begins the shutdown procedure without an argument by calling doStop(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently. This method is a shortcut of stop(null).

stop

public final CompletableFuture<Void> stop(U arg)

Begins the shutdown procedure by calling doStop(Object), ensuring that neither doStart(Object) nor doStop(Object) is invoked concurrently.

Parameters:

arg - the argument to pass to doStop(Object), or null to pass no argument.

isClosing

public boolean isClosing()

Description copied from interface: ListenableAsyncCloseable

Returns whether AsyncCloseable.close() or AsyncCloseable.closeAsync() has been called.

Specified by:

isClosing in interface ListenableAsyncCloseable

See Also:

ListenableAsyncCloseable.isClosed()

isClosed

public boolean isClosed()

Description copied from interface: ListenableAsyncCloseable

Returns whether AsyncCloseable.close() or AsyncCloseable.closeAsync() operation has been completed.

Specified by:

isClosed in interface ListenableAsyncCloseable

See Also:

ListenableAsyncCloseable.isClosing()

whenClosed

public CompletableFuture<?> whenClosed()

Description copied from interface: ListenableAsyncCloseable

Returns the CompletableFuture which is completed after the AsyncCloseable.close() or AsyncCloseable.closeAsync() operation is completed.

Specified by:

whenClosed in interface ListenableAsyncCloseable

closeAsync

public CompletableFuture<?> closeAsync()

Description copied from interface: AsyncCloseable

Releases any underlying resources held by this object asynchronously.

Specified by:

closeAsync in interface AsyncCloseable

Returns:

the CompletableFuture which is completed after the resources are released

close

public final void close()

A synchronous version of stop(Object). Exceptions occurred during shutdown are reported to closeFailed(Throwable). No argument (i.e. null) is passed.

Specified by:

close in interface AsyncCloseable

Specified by:

close in interface AutoCloseable

doStart

protected abstract CompletionStage<V> doStart(T arg)
                                       throws Exception

Invoked by start(Object, boolean) to perform the actual startup.

Parameters:

arg - the argument passed from start(Object, boolean), or null if no argument was specified.

Throws:

Exception

doStop

protected abstract CompletionStage<Void> doStop(U arg)
                                         throws Exception

Invoked by stop(Object) to perform the actual startup, or indirectly by start(Object, boolean) when startup failed.

Parameters:

arg - the argument passed from stop(Object), or null if no argument was specified.

Throws:

Exception

notifyStarting

protected void notifyStarting(L listener,
                              T arg)
                       throws Exception

Invoked when the startup procedure begins.

Parameters:

listener - the listener

arg - the argument passed from start(Object, boolean), or null if no argument was specified.

Throws:

Exception

notifyStarted

protected void notifyStarted(L listener,
                             T arg,
                             V result)
                      throws Exception

Invoked when the startup procedure is finished.

Parameters:

listener - the listener

arg - the argument passed from start(Object, boolean), or null if no argument was specified.

result - the value of the CompletionStage returned by doStart(Object).

Throws:

Exception

notifyStopping

protected void notifyStopping(L listener,
                              U arg)
                       throws Exception

Invoked when the shutdown procedure begins.

Parameters:

listener - the listener

arg - the argument passed from stop(Object), or null if no argument was specified.

Throws:

Exception

notifyStopped

protected void notifyStopped(L listener,
                             U arg)
                      throws Exception

Invoked when the shutdown procedure is finished.

Parameters:

listener - the listener

arg - the argument passed from stop(Object), or null if no argument was specified.

Throws:

Exception

rollbackFailed

protected void rollbackFailed(Throwable cause)

Invoked when failed to stop during the rollback after startup failure.

notificationFailed

protected void notificationFailed(L listener,
                                  Throwable cause)

Invoked when an event listener raises an exception.

closeFailed

protected void closeFailed(Throwable cause)

Invoked when failed to stop in close().

toString

public String toString()

Overrides:

toString in class Object