Publish

1 files changed, 39 insertions, 0 deletions

diff --git a/jdisc_core/src/main/java/com/yahoo/jdisc/handler/CompletionHandler.java b/jdisc_core/src/main/java/com/yahoo/jdisc/handler/CompletionHandler.java
new file mode 100644
index 00000000000..ca2e61fff52
--- /dev/null
+++ b/jdisc_core/src/main/java/com/yahoo/jdisc/handler/CompletionHandler.java
@@ -0,0 +1,39 @@
+// Copyright 2016 Yahoo Inc. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
+package com.yahoo.jdisc.handler;
+
+import com.yahoo.jdisc.Container;
+
+/**
+ * This interface defines a handler for consuming the result of an asynchronous I/O operation.
+ * <p>
+ * The asynchronous channels defined in this package allow a completion handler to be specified to consume the result of
+ * an asynchronous operation. The {@link #completed()} method is invoked when the I/O operation completes successfully.
+ * The {@link #failed(Throwable)} method is invoked if the I/O operations fails. The implementations of these methods
+ * should complete in a timely manner so as to avoid keeping the invoking thread from dispatching to other completion
+ * handlers.
+ * <p>
+ * Because a CompletionHandler might have a completely different lifespan than the originating ContentChannel objects,
+ * all instances of this interface are internally backed by a reference to the {@link Container} that was active when
+ * the initial Request was created. This ensures that the configured environment of the CompletionHandler is stable
+ * throughout its lifetime. This also means that the either {@link #completed()} or {@link #failed(Throwable)} MUST be
+ * called in order to release that reference. Failure to do so will prevent the Container from ever shutting down.
+ *
+ * @author <a href="mailto:simon@yahoo-inc.com">Simon Thoresen</a>
+ */
+public interface CompletionHandler {
+
+    /**
+     * Invoked when an operation has completed. Notice that you MUST call either this or {@link #failed(Throwable)} to
+     * release the internal {@link Container} reference. Failure to do so will prevent the Container from ever shutting
+     * down.
+     */
+    public void completed();
+
+    /**
+     * Invoked when an operation fails. Notice that you MUST call either this or {@link #completed()} to release the
+     * internal {@link Container} reference. Failure to do so will prevent the Container from ever shutting down.
+     *
+     * @param t The exception to indicate why the I/O operation failed.
+     */
+    public void failed(Throwable t);
+}