Trimmed down the Request class and provided it with a clear way to pass results to the user of the request

git-svn-id: file:///srv/devel/repo-conversion/nusu@63 d2e56fa2-650e-0410-a79f-9358c0239efd

Source/Tracking/Request.cs

@@ -37,7 +37,7 @@ namespace Nuclex.Support.Tracking {
   ///     OnAsyncEnded(), no matter what the outcome of your background operation is.
   ///   </para>
   /// </remarks>
-  public class Request : Progression {
+  public abstract class Request : Progression {
 
     #region class EndedDummyRequest
 
@@ -48,21 +48,25 @@ namespace Nuclex.Support.Tracking {
       /// <summary>Creates a new failed dummy request</summary>
       /// <param name="exception">Exception that caused the dummy to fail</param>
       public EndedDummyRequest(Exception exception) {
+        this.exception = exception;
         OnAsyncEnded();
-
-        // Only call SetException() if an actual exception was provided. Who knows what
-        // evil code might be inside SetException() after all ;)
-        if(exception != null)
-          SetException(exception);
       }
+      /// <summary>
+      ///   Allows the specific request implementation to re-throw an exception if
+      ///   the background process finished unsuccessfully
+      /// </summary>
+      protected override void ReraiseExceptions() {
+        if(this.exception != null)
+          throw this.exception;
+      }
+      /// <summary>Exception that supposedly caused the request to fail</summary>
+      private Exception exception;
     }
 
     #endregion // EndedDummyRequest
 
     /// <summary>Creates a new failed dummy request</summary>
-    /// <param name="error">
-    ///   Exception that supposedly caused the progression to fail
-    /// </param>
+    /// <param name="exception">Exception that supposedly caused the request to fail</param>
     /// <returns>
     ///   A failed request that reports the provided exception as cause for its failure
     /// </returns>
@@ -83,36 +87,76 @@ namespace Nuclex.Support.Tracking {
       if(!Ended)
         WaitHandle.WaitOne();
 
-      // If an exception occured during the background execution
-      if(this.occuredException != null)
-        throw this.occuredException;
+      // Allow the implementor to throw an exception in case an error has occured
+      ReraiseExceptions();
 
     }
 
-    /// <summary>Exception that occured while the operation was executing</summary>
+    /// <summary>
+    ///   Allows the specific request implementation to re-throw an exception if
+    ///   the background process finished unsuccessfully
+    /// </summary>
+    protected virtual void ReraiseExceptions() {}
+ 
+  }
+
+  /// <summary>Request providing a result that can be passed to the caller</summary>
+  /// <typeparam name="ResultType">
+  ///   Type of the result being provided by the request
+  /// </typeparam>
+  public abstract class Request<ResultType> : Request {
+
+    #region class EndedDummyRequest
+
+    /// <summary>Dummy request that is always in the ended state</summary>
+    private class EndedDummyRequest : Request<ResultType> {
+      /// <summary>Creates a new failed dummy request</summary>
+      /// <param name="exception">Exception that caused the dummy to fail</param>
+      public EndedDummyRequest(Exception exception) {
+        this.exception = exception;
+        OnAsyncEnded();
+      }
+      /// <summary>
+      ///   Allows the specific request implementation to re-throw an exception if
+      ///   the background process finished unsuccessfully
+      /// </summary>
+      protected override ResultType GatherResults() {
+        throw this.exception;
+      }
+      /// <summary>Exception that supposedly caused the request to fail</summary>
+      private Exception exception;
+    }
+
+    #endregion // EndedDummyRequest
+
+    /// <summary>Creates a new failed dummy request</summary>
+    /// <param name="exception">Exception that supposedly caused the request to fail</param>
+    /// <returns>
+    ///   A failed request that reports the provided exception as cause for its failure
+    /// </returns>
+    public static new Request CreateFailedDummyRequest(Exception exception) {
+      return new EndedDummyRequest(exception);
+    }
+
+    /// <summary>Waits for the background operation to end</summary>
     /// <remarks>
-    ///   If this field is null, it is assumed that no exception has occured
-    ///   in the background process. If it is set, however, the End() method will
-    ///   re-raise the exception to the calling thread when it is called.
+    ///   Any exceptions raised in the background operation will be thrown
+    ///   in this method. If you decide to override this method, you should
+    ///   call End() first (and let any possible exception through to your
+    ///   caller).
     /// </remarks>
-    public Exception OccuredException {
-      get { return this.occuredException; }
+    public new ResultType Join() {
+      base.Join();
+
+      // Return the results of the request
+      return GatherResults();
     }
 
-    /// <summary>Sets the exception to raise to the caller of the End() method</summary>
-    /// <param name="exception">Exception to raise to the caller of the End() method</param>
-    protected void SetException(Exception exception) {
-
-      // We allow the caller to set the exception multiple times. While I certainly
-      // can't think of a scenario where this would happen, throwing an exception
-      // in that case seems worse. The caller might just be executing an exception
-      // handling block and locking + throwing here could cause all kinds of problems.
-      this.occuredException = exception;
-
-    }
-
-    /// <summary>Exception that occured while the operation was executing</summary>
-    private volatile Exception occuredException;
+    /// <summary>
+    ///   Allows the specific request implementation to re-throw an exception if
+    ///   the background process finished unsuccessfully
+    /// </summary>
+    protected abstract ResultType GatherResults();
 
   }