src/net/pterodactylus/fcp/highlevel/HighLevelCallback.java

   1 /*
   2  * fcplib - HighLevelCallback.java -
   3  * Copyright © 2008 David Roden
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  18  */
  19
  20 package net.pterodactylus.fcp.highlevel;
  21
  22 import java.util.ArrayList;
  23 import java.util.Collections;
  24 import java.util.List;
  25
  26 /**
  27  * A callback is used to notify users of the {@link HighLevelClient} that an
  28  * operation was completed.
  29  *
  30  * @param <R>
  31  *            The type of the high-level operation result
  32  * @author David ‘Bombe’ Roden &lt;bombe@freenetproject.org&gt;
  33  * @version $Id$
  34  */
  35 public class HighLevelCallback<R extends HighLevelResult> {
  36
  37         /** Object used for synchronization. */
  38         private final Object syncObject = new Object();
  39
  40         /** The list of callback listeners. */
  41         private final List<HighLevelCallbackListener<R>> highLevelCallbackListeners = Collections.synchronizedList(new ArrayList<HighLevelCallbackListener<R>>());
  42
  43         /** The result of the operation. */
  44         private R result = null;
  45
  46         /**
  47          * Package-private construtor.
  48          */
  49         HighLevelCallback() {
  50         }
  51
  52         /**
  53          * Adds a callback listener to this callback. The callback listener will be
  54          * called as soon as the result of the operation is known. If the result is
  55          * already known, the listener will be called immediately. Also, as soon as
  56          * a listener was notified the listener is automatically removed from this
  57          * callback.
  58          *
  59          * @param highLevelCallbackListener
  60          *            The listener to add
  61          */
  62         public void addHighLevelCallbackListener(HighLevelCallbackListener<R> highLevelCallbackListener) {
  63                 highLevelCallbackListeners.add(highLevelCallbackListener);
  64                 if (isDone()) {
  65                         fireGotResult();
  66                 }
  67         }
  68
  69         /**
  70          * Removes a callback listener from this callback.
  71          *
  72          * @param highLevelCallbackListener
  73          *            The listener to remove
  74          */
  75         public void removeHighLevelCallbackListener(HighLevelCallbackListener<R> highLevelCallbackListener) {
  76                 highLevelCallbackListeners.remove(highLevelCallbackListener);
  77         }
  78
  79         /**
  80          * Notifies all listeners that the result of the operation is now known.
  81          *
  82          * @see HighLevelCallbackListener#gotResult(HighLevelCallback)
  83          */
  84         private synchronized void fireGotResult() {
  85                 for (HighLevelCallbackListener<R> highLevelCallbackListener: highLevelCallbackListeners) {
  86                         highLevelCallbackListeners.remove(highLevelCallbackListener);
  87                         highLevelCallbackListener.gotResult(this);
  88                 }
  89         }
  90
  91         /**
  92          * Returns whether the result of the operation is already known. If the
  93          * result is already known a call to {@link #getResult()} will not block.
  94          *
  95          * @return <code>true</code> if the result is already known,
  96          *         <code>false</code> otherwise
  97          */
  98         public boolean isDone() {
  99                 synchronized (syncObject) {
 100                         return result != null;
 101                 }
 102         }
 103
 104         /**
 105          * Returns the result of the operation, blocking until it is known.
 106          *
 107          * @return The result of the operation
 108          * @throws InterruptedException
 109          *             if {@link Object#wait()} was interrupted
 110          */
 111         public R getResult() throws InterruptedException {
 112                 return getResult(0);
 113         }
 114
 115         /**
 116          * Returns the result of the operation, blocking until it is known or the
 117          * given time (in milliseconds) has passed.
 118          *
 119          * @param waitTime
 120          *            The time to wait for a result
 121          * @return The result of the operation, or <code>null</code> if the result
 122          *         is still not known after <code>waitTime</code> milliseconds
 123          *         have passed
 124          * @throws InterruptedException
 125          *             if {@link Object#wait()} is interrupted
 126          */
 127         public R getResult(long waitTime) throws InterruptedException {
 128                 synchronized (syncObject) {
 129                         if (result == null) {
 130                                 syncObject.wait(waitTime);
 131                         }
 132                         return result;
 133                 }
 134         }
 135
 136         /**
 137          * Sets the result of the operation. Calling this method will result in all
 138          * listeners being notified.
 139          *
 140          * @see #fireGotResult()
 141          * @param result
 142          *            The result of the operation
 143          */
 144         void setResult(R result) {
 145                 synchronized (syncObject) {
 146                         this.result = result;
 147                         syncObject.notifyAll();
 148                 }
 149                 fireGotResult();
 150         }
 151
 152 }