Package 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	Description
protected	StartStopSupport(Executor executor)	Creates a new instance.

Method Summary

Modifier and Type	Method	Description
final void	addListener(L listener)	Adds the specified listener, so that it is notified when the state of this StartStopSupport changes.
final void	close()	A synchronous version of stop(Object).
final 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.
final boolean	isClosed()	Returns whether AsyncCloseable.close() or AsyncCloseable.closeAsync() operation has been completed.
final 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.
final 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.
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.
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.
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.
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.
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.
String	toString()
final 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 Details

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 Details

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(@Nullable
 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(@Nullable
 T arg,
 @Nullable
 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(@Nullable
 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 final 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 final 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 final 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 final 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(@Nullable
 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(@Nullable
 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,
 @Nullable
 T arg)
                       throws Exception

Invoked when the startup procedure begins. Note that the startup procedure will be aborted if an exception is thrown.

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,
 @Nullable
 T arg,
 @Nullable
 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,
 @Nullable
 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,
 @Nullable
 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