From 2e173531a72bdae763f1d171cef14334bcf88e20 Mon Sep 17 00:00:00 2001
From: mdb <mdb@6335cc39-0255-0410-8fd6-9bcaacd3b74c>
Date: Wed, 20 Mar 2002 07:07:48 +0000
Subject: [PATCH] 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
---
 .../samskivert/util/IntResultListener.java    | 52 +++++++++++++++++++
 .../com/samskivert/util/ResultListener.java   | 50 ++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 100644 projects/samskivert/src/java/com/samskivert/util/IntResultListener.java
 create mode 100644 projects/samskivert/src/java/com/samskivert/util/ResultListener.java

diff --git a/projects/samskivert/src/java/com/samskivert/util/IntResultListener.java b/projects/samskivert/src/java/com/samskivert/util/IntResultListener.java
new file mode 100644
index 00000000..be08c740
--- /dev/null
+++ b/projects/samskivert/src/java/com/samskivert/util/IntResultListener.java
@@ -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);
+}
diff --git a/projects/samskivert/src/java/com/samskivert/util/ResultListener.java b/projects/samskivert/src/java/com/samskivert/util/ResultListener.java
new file mode 100644
index 00000000..b93ad587
--- /dev/null
+++ b/projects/samskivert/src/java/com/samskivert/util/ResultListener.java
@@ -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);
+}