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         /** Whether the result is complete. */
  44         private boolean resultComplete = false;
  45
  46         /** The result of the operation. */
  47         private R result = null;
  48
  49         /**
  50          * Package-private construtor.
  51          *
  52          * @param result
  53          *            The result of the operation
  54          */
  55         HighLevelCallback(R result) {
  56                 this.result = result;
  57         }
  58
  59         /**
  60          * Adds a callback listener to this callback. The callback listener will be
  61          * called as soon as the result of the operation is known. If the result is
  62          * already known, the listener will be called immediately. Also, as soon as
  63          * a listener was notified the listener is automatically removed from this
  64          * callback.
  65          *
  66          * @param highLevelCallbackListener
  67          *            The listener to add
  68          */
  69         public void addHighLevelCallbackListener(HighLevelCallbackListener<R> highLevelCallbackListener) {
  70                 highLevelCallbackListeners.add(highLevelCallbackListener);
  71                 if (isDone()) {
  72                         fireGotResult();
  73                 }
  74         }
  75
  76         /**
  77          * Removes a callback listener from this callback.
  78          *
  79          * @param highLevelCallbackListener
  80          *            The listener to remove
  81          */
  82         public void removeHighLevelCallbackListener(HighLevelCallbackListener<R> highLevelCallbackListener) {
  83                 highLevelCallbackListeners.remove(highLevelCallbackListener);
  84         }
  85
  86         /**
  87          * Notifies all listeners that the result of the operation is now known.
  88          *
  89          * @see HighLevelCallbackListener#gotResult(HighLevelCallback)
  90          */
  91         private synchronized void fireGotResult() {
  92                 for (HighLevelCallbackListener<R> highLevelCallbackListener: highLevelCallbackListeners) {
  93                         highLevelCallbackListeners.remove(highLevelCallbackListener);
  94                         highLevelCallbackListener.gotResult(this);
  95                 }
  96         }
  97
  98         /**
  99          * Returns whether the result of the operation is already known. If the
 100          * result is already known a call to {@link #getResult()} will not block.
 101          *
 102          * @return <code>true</code> if the result is already known,
 103          *         <code>false</code> otherwise
 104          */
 105         public boolean isDone() {
 106                 synchronized (syncObject) {
 107                         return resultComplete;
 108                 }
 109         }
 110
 111         /**
 112          * Returns the result of the operation, blocking until it is known.
 113          *
 114          * @return The result of the operation
 115          * @throws InterruptedException
 116          *             if {@link Object#wait()} was interrupted
 117          */
 118         public R getResult() throws InterruptedException {
 119                 return getResult(0);
 120         }
 121
 122         /**
 123          * Returns the result of the operation, blocking until it is known or the
 124          * given time (in milliseconds) has passed.
 125          *
 126          * @param waitTime
 127          *            The time to wait for a result
 128          * @return The result of the operation, or <code>null</code> if the result
 129          *         is still not known after <code>waitTime</code> milliseconds
 130          *         have passed
 131          * @throws InterruptedException
 132          *             if {@link Object#wait()} is interrupted
 133          */
 134         public R getResult(long waitTime) throws InterruptedException {
 135                 synchronized (syncObject) {
 136                         if (!resultComplete) {
 137                                 syncObject.wait(waitTime);
 138                         }
 139                         return result;
 140                 }
 141         }
 142
 143         /**
 144          * Returns the result even if it is not yet complete.
 145          *
 146          * @return The result of the operation
 147          */
 148         R getIntermediaryResult() {
 149                 synchronized (syncObject) {
 150                         return result;
 151                 }
 152         }
 153
 154         /**
 155          * Marks the result as complete and notify the listeners. If the result was
 156          * already complete, nothing will be done.
 157          */
 158         void setDone() {
 159                 synchronized (syncObject) {
 160                         if (resultComplete) {
 161                                 return;
 162                         }
 163                         resultComplete = true;
 164                         syncObject.notify();
 165                 }
 166                 fireGotResult();
 167         }
 168
 169 }