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 org.apache.mina.common.ByteBuffer;
32  
33  import uk.ac.rdg.resc.jstyx.types.DirEntry;
34  import uk.ac.rdg.resc.jstyx.messages.TwriteMessage;
35  import uk.ac.rdg.resc.jstyx.messages.TreadMessage;
36  
37  /***
38   * Interface defining methods that will be fired when messages pertaining to 
39   * a StyxFile arrive at the client (e.g. data has been read, permissions changed
40   * etc)
41   *
42   * @author Jon Blower
43   * $Revision: 373 $
44   * $Date: 2005-08-31 09:15:57 +0100 (Wed, 31 Aug 2005) $
45   * $Log$
46   * Revision 1.10  2005/08/31 08:15:57  jonblower
47   * Corrections to comments
48   *
49   * Revision 1.9  2005/07/28 16:38:58  jonblower
50   * Added material to comments
51   *
52   * Revision 1.8  2005/06/20 17:20:43  jonblower
53   * Added download() and downloadAsync() to CStyxFile
54   *
55   * Revision 1.7  2005/05/25 16:57:07  jonblower
56   * Added fileCreated() event
57   *
58   * Revision 1.6  2005/05/12 14:20:55  jonblower
59   * Changed dataSent() method to dataWritten() (more accurate name)
60   *
61   * Revision 1.5  2005/05/12 08:00:34  jonblower
62   * Added getChildrenAsync() to CStyxFile and childrenFound() to CStyxFileChangeListener
63   *
64   * Revision 1.4  2005/05/05 07:08:37  jonblower
65   * Improved handling of buffers in change listeners
66   *
67   * Revision 1.3  2005/03/19 21:46:58  jonblower
68   * Further fixes relating to releasing ByteBuffers
69   *
70   * Revision 1.2  2005/03/16 17:55:52  jonblower
71   * Replaced use of java.nio.ByteBuffer with MINA's ByteBuffer to minimise copying of buffers
72   *
73   * Revision 1.1.1.1  2005/02/16 18:58:18  jonblower
74   * Initial import
75   *
76   */
77  public interface CStyxFileChangeListener
78  {
79      
80      /***
81       * Called when the file has been opened.
82       * @param file The file that has been opened
83       * @param mode The mode with which the file was opened
84       */
85      public void fileOpen(CStyxFile file, int mode);
86      
87      /***
88       * Called when the file has been created.
89       * @param file The file that has been created
90       * @param mode The mode with which the file was created
91       */
92      public void fileCreated(CStyxFile file, int mode);
93      
94      /***
95       * Called when new data have been read from the file (after the Rread message
96       * arrives). Note that the offset of the file (i.e. the file position) will
97       * not have changed before this method is called.  It is up to clients to 
98       * update the offset of the file if required (e.g.
99       * <code>file.setOffset(offset + data.remaining())</code>).
100      *
101      * After this method is finished, the ByteBuffer will automatically be returned to the pool.
102      * If you want to delay this happening, call data.acquire() within this
103      * method.  Then when you no longer need the data in the buffer, call 
104      * data.release().
105      *
106      * @param file The CStyxFile containing the data
107      * @param tReadMsg The original TreadMessage that was sent (contains the offset,
108      * tag etc of the message)
109      * @param data The new data that have been read from the file
110      */
111     public void dataArrived(CStyxFile file, TreadMessage tReadMsg, ByteBuffer data);
112     
113     /***
114      * Called when data have been written to the file (after the Rwrite message
115      * arrives). Note that the offset of the file (i.e. the file position) will
116      * not have changed before this method is called.  It is up to clients to 
117      * update the offset of the file if required (e.g.
118      * <code>file.setOffset(offset + data.remaining())</code>).
119      * @param file The CStyxFile containing the data
120      * @param tWriteMsg The TwriteMessage that caused this event to be fired
121      */
122     public void dataWritten(CStyxFile file, TwriteMessage tWriteMsg);
123     
124     /***
125      * Called when an Rerror message arrives
126      * @param file the CStyxFile from which the error originated
127      * @param message the error message
128      */
129     public void error(CStyxFile file, String message);
130     
131     /***
132      * Called after the stat of a file (permissions etc) has been changed.
133      * Actually, this is called after an Rstat message arrives; it does not
134      * necessarily mean that the stat has changed.
135      */
136     public void statChanged(CStyxFile file, DirEntry newDirEntry);
137     
138     /***
139      * Called after a successful read on a directory. (Result of a call to
140      * CStyxFile.getChildrenAsync()).  All the dirEntries of the children will
141      * have been set, so it is safe to call getDirEntry() on any of the children
142      * without worrying about the method blocking.
143      */
144     public void childrenFound(CStyxFile file, CStyxFile[] children);
145     
146     /***
147      * Called after a file has been successfully uploaded
148      * @param targetFile The file to which we have written
149      */
150     public void uploadComplete(CStyxFile targetFile);
151     
152     /***
153      * Called after a file has been successfully downloaded
154      * @param sourceFile The file from which the data have been downloaded.
155      */
156     public void downloadComplete(CStyxFile sourceFile);
157     
158 }