dagger.producers.monitoring

Class ProducerMonitor

java.lang.Object

dagger.producers.monitoring.ProducerMonitor

public abstract class ProducerMonitor
extends Object

A hook for monitoring the execution of individual producer methods. See ProductionComponentMonitor for how to install these monitors.

The lifecycle of the monitor, under normal conditions, is:

• requested()
• methodStarting()
• The method is called
• methodFinished()
• If the method returns a value, then:
  • succeeded(Object) if the method returned normally; or
  • failed(Throwable) if the method threw an exception.
• If the method returns a future, then:
  • succeeded(Object) if the method returned normally, and the future succeeded; or
  • failed(Throwable) if the method threw an exception, or returned normally and the future failed.

If any input to the monitored producer fails, failed(Throwable) will be called immediately with the failed input's exception. If more than one input fails, an arbitrary failed input's exception is used.

For example, given an entry point A that depends on B, which depends on C, when the entry point A is called, this will trigger the following sequence of events, assuming all methods and futures complete successfully:

• A requested
• B requested
• C requested
• C methodStarting
• C methodFinished
• C succeeded
• B methodStarting
• B methodFinished
• B succeeded
• A methodStarting
• A methodFinished
• A succeeded

If any of the monitor's methods throw, then the exception will be logged and processing will continue unaffected.

Constructor Summary

Constructors

Constructor and Description
ProducerMonitor()

Method Summary

Modifier and Type	Method and Description
<T> void	addCallbackTo(ListenableFuture<T> future) Adds this monitor's completion methods as a callback to the future.
void	failed(Throwable t) Called when the producer's future has failed with an exception.
void	methodFinished() Called when the producer method has finished executing.
void	methodStarting() Called when the producer method is about to start executing.
static ProducerMonitor	noOp() Returns a monitor that does no monitoring.
void	ready() Called when all of the producer's inputs are available.
void	requested() Called when the producer's output is requested; that is, when the first method is called that requires the production of this producer's output.
void	succeeded(Object value) Called when the producer’s future has completed successfully with a value.

Methods inherited from class java.lang.Object

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

Constructor Detail

ProducerMonitor

public ProducerMonitor()

Method Detail

requested

public void requested()

Called when the producer's output is requested; that is, when the first method is called that requires the production of this producer's output.

Note that if a method depends on Producer<T>, then this does not count as requesting T; that is only triggered by calling Producer.get().

Depending on how this producer is requested, the following threading constraints are guaranteed:

1. If the producer is requested directly by a method on a component, then requested will be called on the same thread as the component method call.
2. If the producer is requested by value from another producer (i.e., injected as T or Produced<T>), then requested will be called from the same thread as the other producer's requested.
3. If the producer is requested by calling Producer.get(), then requested will be called from the same thread as that get() call.

When multiple monitors are installed, the order that each monitor will call this method is unspecified, but will remain consistent throughout the course of the execution of a component.

This implementation is a no-op.

ready

public void ready()

Called when all of the producer's inputs are available. This is called regardless of whether the inputs have succeeded or not; when the inputs have succeeded, this is called prior to scheduling the method on the executor, and if an input has failed and the producer will be skipped, this method will be called before failed(Throwable) is called.

When multiple monitors are installed, the order that each monitor will call this method is unspecified, but will remain consistent throughout the course of the execution of a component.

This implementation is a no-op.

methodStarting

public void methodStarting()

Called when the producer method is about to start executing. This will be called from the same thread as the producer method itself.

When multiple monitors are installed, calls to this method will be in the reverse order from calls to requested().

This implementation is a no-op.

methodFinished

public void methodFinished()

Called when the producer method has finished executing. This will be called from the same thread as methodStarting() and the producer method itself.

When multiple monitors are installed, calls to this method will be in the reverse order from calls to requested().

This implementation is a no-op.

succeeded

public void succeeded(Object value)

Called when the producer’s future has completed successfully with a value.

When multiple monitors are installed, calls to this method will be in the reverse order from calls to requested().

This implementation is a no-op.

failed

public void failed(Throwable t)

Called when the producer's future has failed with an exception.

When multiple monitors are installed, calls to this method will be in the reverse order from calls to requested().

This implementation is a no-op.

addCallbackTo

public <T> void addCallbackTo(ListenableFuture<T> future)

Adds this monitor's completion methods as a callback to the future. This is only intended to be overridden in the framework!

noOp

public static ProducerMonitor noOp()

Returns a monitor that does no monitoring.