View Javadoc

1   /*
2    * Copyright (c) 2005 The University of Reading
3    * All rights reserved.
4    *
5    * Redistribution and use in source and binary forms, with or without
6    * modification, are permitted provided that the following conditions
7    * are met:
8    * 1. Redistributions of source code must retain the above copyright
9    *    notice, this list of conditions and the following disclaimer.
10   * 2. Redistributions in binary form must reproduce the above copyright
11   *    notice, this list of conditions and the following disclaimer in the
12   *    documentation and/or other materials provided with the distribution.
13   * 3. Neither the name of the University of Reading, nor the names of the
14   *    authors or contributors may be used to endorse or promote products
15   *    derived from this software without specific prior written permission.
16   * 
17   * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18   * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20   * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22   * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24   * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26   * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27   */
28  
29  package uk.ac.rdg.resc.jstyx.client;
30  
31  import uk.ac.rdg.resc.jstyx.messages.StyxMessage;
32  import uk.ac.rdg.resc.jstyx.messages.RerrorMessage;
33  
34  /***
35   * Callback class that is associated with an outgoing Tmessage. When the reply
36   * arrives, the gotReply() method is called by StyxConnection.replyArrived().
37   * If the reply is of the correct type, the replyArrived() method of this class
38   * is called; otherwise the error() method is called.
39   *
40   * @author Jon Blower
41   * $Revision: 373 $
42   * $Date: 2005-08-31 09:15:57 +0100 (Wed, 31 Aug 2005) $
43   * $Log$
44   * Revision 1.6  2005/08/31 08:15:57  jonblower
45   * Corrections to comments
46   *
47   * Revision 1.5  2005/06/27 17:17:15  jonblower
48   * Changed MessageCallback to pass Tmessage as parameter, rather than storing in the instance
49   *
50   * Revision 1.4  2005/05/25 15:39:02  jonblower
51   * Bug fixes
52   *
53   * Revision 1.3  2005/05/23 16:48:17  jonblower
54   * Overhauled CStyxFile (esp. asynchronous methods) and StyxConnection (added cache of CStyxFiles)
55   *
56   * Revision 1.1.1.1  2005/02/16 18:58:18  jonblower
57   * Initial import
58   *
59   */
60  public abstract class MessageCallback
61  {
62      
63      /***
64       * Called by StyxConnection when a reply arrives to the Tmessage. If the
65       * reply is an Rerror message, the error() method of this class will be
66       * called with the error string. If the type of the reply is not as
67       * expected, the error() method will be called. Otherwise, the replyArrived()
68       * method will be called. Subclasses may not override this method.
69       */
70      final void gotReply(StyxMessage rMessage, StyxMessage tMessage)
71      {
72          if (rMessage instanceof RerrorMessage)
73          {
74              this.error(((RerrorMessage)rMessage).getMessage(), tMessage);
75          }
76          else
77          {
78              if (rMessage.getType() != tMessage.getType() + 1)
79              {
80                  this.error("Unexpected type of reply (" + rMessage.getType() +
81                      ") to message of type " + tMessage.getType(),
82                      tMessage);
83              }
84              else
85              {
86                  this.replyArrived(rMessage, tMessage);
87              }
88          }
89      }
90      
91      /***
92       * Called when the reply arrives.  If the reply is an RreadMessage, the
93       * message's buffer should be released when it is no longer needed, 
94       * using <code>rMessage.getData().release()</code>.
95       * @param rMessage the reply
96       * @param tMessage the original T-message
97       */
98      public abstract void replyArrived(StyxMessage rMessage, StyxMessage tMessage);
99      
100     /***
101      * Called when an error occurs (this may occur if the server returned an
102      * Rerror message, or if the reply was not of the expected type, or for 
103      * other reasons).
104      * @param message The error string
105      * @param tMessage The T-message that caused this error to happen
106      */
107     public abstract void error(String message, StyxMessage tMessage);
108     
109 }