Created general purpose classes to support a standard callback pattern

that we've been using in a few places in Narya and Yohoho. git-svn-id: https://samskivert.googlecode.com/svn/trunk@679 6335cc39-0255-0410-8fd6-9bcaacd3b74c
2002-03-20 07:07:48 +00:00
parent 53d25e736b
commit 2e173531a7
2 changed files with 102 additions and 0 deletions
@@ -0,0 +1,52 @@
+//
+// $Id: IntResultListener.java,v 1.1 2002/03/20 07:07:48 mdb Exp $
+
+package com.samskivert.util;
+
+/**
+ * Provides access to an integer result, or the exception associated with
+ * failure. In the trying course of implementing a method, one is often
+ * left with no choice but to foist control off onto another thread or
+ * generally postpone things beyond the lifetime of the current call. In
+ * such circumstances, it is handy to have a general purpose mechanism for
+ * leting the caller know when things are done and whether or not the
+ * succeeded; this class serves that purpose.
+ *
+ * <p> The following contrived example will hopefully communicate its use
+ * more clearly than the previous paragraph of flowery prose:
+ *
+ * <pre>
+ * public void doSomeStuff (IntResultListener listener)
+ * {
+ *     Runnable run = new Runnable () {
+ *         public void run () {
+ *             try {
+ *                 // do our thing
+ *                 listener.requestCompleted(42);
+ *             } catch (Exception e) {
+ *                 listener.requestFailed(e);
+ *             }
+ *         }
+ *     };
+ *     new Thread(run).start();
+ * }
+ * </pre>
+ *
+ * This interface is a convenience-variation on the plain old {@link
+ * ResultListener}, which communicates the result back in the form of an
+ * {@link Object} rather than an integer.
+ */
+public interface IntResultListener
+{
+    /**
+     * Called to communicate that the request succeeded and that the
+     * result is available.
+     */
+    public void requestCompleted (int result);
+
+    /**
+     * Called to communicate that the request failed and to provide the
+     * reason for failure.
+     */
+    public void requestFailed (Exception cause);
+}
@@ -0,0 +1,50 @@
+//
+// $Id: ResultListener.java,v 1.1 2002/03/20 07:07:48 mdb Exp $
+
+package com.samskivert.util;
+
+/**
+ * Provides access to a future result, or the exception associated with
+ * failure. In the trying course of implementing a method, one is often
+ * left with no choice but to foist control off onto another thread or
+ * generally postpone things beyond the lifetime of the current call. In
+ * such circumstances, it is handy to have a general purpose mechanism for
+ * leting the caller know when things are done and whether or not the
+ * succeeded; this class serves that purpose.
+ *
+ * <p> The following contrived example will hopefully communicate its use
+ * more clearly than the previous paragraph of flowery prose:
+ *
+ * <pre>
+ * public void doSomeStuff (ResultListener listener)
+ * {
+ *     Runnable run = new Runnable () {
+ *         public void run () {
+ *             try {
+ *                 // do our thing
+ *                 listener.requestCompleted("Elvis!");
+ *             } catch (Exception e) {
+ *                 listener.requestFailed(e);
+ *             }
+ *         }
+ *     };
+ *     new Thread(run).start();
+ * }
+ * </pre>
+ *
+ * @see IntResultListener
+ */
+public interface ResultListener
+{
+    /**
+     * Called to communicate that the request succeeded and that the
+     * result is available.
+     */
+    public void requestCompleted (Object result);
+
+    /**
+     * Called to communicate that the request failed and to provide the
+     * reason for failure.
+     */
+    public void requestFailed (Exception cause);
+}