1 package fr.in2p3.jsaga.sync.file;
2
3
4 import fr.in2p3.jsaga.sync.namespace.SyncNSEntry;
5 import org.ogf.saga.buffer.Buffer;
6 import org.ogf.saga.error.*;
7 import org.ogf.saga.file.IOVec;
8 import org.ogf.saga.file.SeekMode;
9
10 import java.util.List;
11
12 /**
13 * The File interface represents an open file descriptor for reads/writes on a
14 * physical file. Errors result in an SagaIOException, not a POSIX error code.
15 */
16 public interface SyncFile extends SyncNSEntry {
17
18 // Inspection
19
20 /**
21 * Returns the number of bytes in the file.
22 *
23 * @return the size.
24 */
25 public long getSizeSync() throws NotImplementedException,
26 AuthenticationFailedException, AuthorizationFailedException,
27 PermissionDeniedException, IncorrectStateException,
28 TimeoutException, NoSuccessException;
29
30 // POSIX-like I/O
31
32 /**
33 * Reads up to <code>len</code> bytes from the file into the buffer.
34 * Returns the number of bytes read, or 0 at end-of-file. Note: this call is
35 * blocking. The async version can be used to implement non-blocking reads.
36 *
37 * @param buffer
38 * the buffer to read data into.
39 * @param len
40 * the number of bytes to be read.
41 * @return the number of bytes read.
42 */
43 public int readSync(Buffer buffer, int len) throws NotImplementedException,
44 AuthenticationFailedException, AuthorizationFailedException,
45 PermissionDeniedException, BadParameterException,
46 IncorrectStateException, TimeoutException, NoSuccessException,
47 SagaIOException;
48
49 /**
50 * Reads up to <code>len</code> bytes from the file into the buffer, at
51 * the specified <code>offset</code>. Returns the number of bytes read,
52 * or 0 at end-of-file. Note: this call is blocking. The async version can
53 * be used to implement non-blocking reads.
54 *
55 * @param buffer
56 * the buffer to read data into.
57 * @param offset
58 * ths offset in the buffer.
59 * @param len
60 * the number of bytes to be read.
61 * @return the number of bytes read.
62 */
63 public int readSync(Buffer buffer, int offset, int len)
64 throws NotImplementedException, AuthenticationFailedException,
65 AuthorizationFailedException, PermissionDeniedException,
66 BadParameterException, IncorrectStateException, TimeoutException,
67 NoSuccessException, SagaIOException;
68
69 /**
70 * Reads up to the buffer's size from the file into the buffer. Returns the
71 * number of bytes read, or 0 at end-of-file. Note: this call is blocking.
72 * The async version can be used to implement non-blocking reads.
73 *
74 * @param buffer
75 * the buffer to read data into.
76 * @return the number of bytes read.
77 */
78 public int readSync(Buffer buffer) throws NotImplementedException,
79 AuthenticationFailedException, AuthorizationFailedException,
80 PermissionDeniedException, BadParameterException,
81 IncorrectStateException, TimeoutException, NoSuccessException,
82 SagaIOException;
83
84 /**
85 * Writes up to <code>len</code> bytes from the buffer at the specified
86 * buffer <code>offset</code> to the file at the current file position.
87 * Returns the number of bytes written.
88 *
89 * @param buffer
90 * the buffer to write data from.
91 * @param offset
92 * the buffer offset.
93 * @param len
94 * the number of bytes to be written.
95 * @return the number of bytes written.
96 */
97 public int writeSync(Buffer buffer, int offset, int len)
98 throws NotImplementedException, AuthenticationFailedException,
99 AuthorizationFailedException, PermissionDeniedException,
100 BadParameterException, IncorrectStateException, TimeoutException,
101 NoSuccessException, SagaIOException;
102
103 /**
104 * Writes up to <code>len</code> bytes from the buffer to the file at the
105 * current file position. Returns the number of bytes written.
106 *
107 * @param buffer
108 * the buffer to write data from.
109 * @param len
110 * the number of bytes to be written.
111 * @return the number of bytes written.
112 */
113 public int writeSync(Buffer buffer, int len) throws NotImplementedException,
114 AuthenticationFailedException, AuthorizationFailedException,
115 PermissionDeniedException, BadParameterException,
116 IncorrectStateException, TimeoutException, NoSuccessException,
117 SagaIOException;
118
119 /**
120 * Writes up to the buffer's size bytes from the buffer to the file at the
121 * current file position. Returns the number of bytes written.
122 *
123 * @param buffer
124 * the buffer to write data from.
125 * @return the number of bytes written.
126 */
127 public int writeSync(Buffer buffer) throws NotImplementedException,
128 AuthenticationFailedException, AuthorizationFailedException,
129 PermissionDeniedException, BadParameterException,
130 IncorrectStateException, TimeoutException, NoSuccessException,
131 SagaIOException;
132
133 /**
134 * Repositions the current file position as requested.
135 *
136 * @param offset
137 * offset in bytes to move pointer.
138 * @param whence
139 * determines from where the offset is relative.
140 * @return the position after the seek.
141 */
142 public long seekSync(long offset, SeekMode whence)
143 throws NotImplementedException, AuthenticationFailedException,
144 AuthorizationFailedException, PermissionDeniedException,
145 IncorrectStateException, TimeoutException, NoSuccessException,
146 SagaIOException;
147
148 // Scattered I/O
149
150 /**
151 * Gather/scatter read.
152 *
153 * @param iovecs
154 * array of IOVecs determining how much to read and where to
155 * store it.
156 */
157 public void readVSync(IOVec[] iovecs) throws NotImplementedException,
158 AuthenticationFailedException, AuthorizationFailedException,
159 PermissionDeniedException, BadParameterException,
160 IncorrectStateException, TimeoutException, NoSuccessException,
161 SagaIOException;
162
163 /**
164 * Gather/scatter write.
165 *
166 * @param iovecs
167 * array of IOVecs determining how much to write and where to
168 * obtain the data from.
169 */
170 public void writeVSync(IOVec[] iovecs) throws NotImplementedException,
171 AuthenticationFailedException, AuthorizationFailedException,
172 PermissionDeniedException, BadParameterException,
173 IncorrectStateException, TimeoutException, NoSuccessException,
174 SagaIOException;
175
176 // Pattern-based I/O
177
178 /**
179 * Determines the storage size required for a pattern I/O operation.
180 *
181 * @param pattern
182 * to determine size for.
183 * @return the size.
184 */
185 public int sizePSync(String pattern) throws NotImplementedException,
186 AuthenticationFailedException, AuthorizationFailedException,
187 IncorrectStateException, PermissionDeniedException,
188 BadParameterException, TimeoutException, NoSuccessException;
189
190 /**
191 * Pattern-based read.
192 *
193 * @param pattern
194 * specification for the read operation.
195 * @param buffer
196 * to store data into.
197 * @return number of succesfully read bytes.
198 */
199 public int readPSync(String pattern, Buffer buffer)
200 throws NotImplementedException, AuthenticationFailedException,
201 AuthorizationFailedException, PermissionDeniedException,
202 BadParameterException, IncorrectStateException, TimeoutException,
203 NoSuccessException, SagaIOException;
204
205 /**
206 * Pattern-based write.
207 *
208 * @param pattern
209 * specification for the write operation.
210 * @param buffer
211 * to be written.
212 * @return number of succesfully written bytes.
213 */
214 public int writePSync(String pattern, Buffer buffer)
215 throws NotImplementedException, AuthenticationFailedException,
216 AuthorizationFailedException, PermissionDeniedException,
217 BadParameterException, IncorrectStateException, TimeoutException,
218 NoSuccessException, SagaIOException;
219
220 // extended I/O
221
222 /**
223 * Lists the extended modes available in this implementation and/or on the
224 * server side.
225 *
226 * @return list of available modes.
227 */
228 public List<String> modesESync() throws NotImplementedException,
229 AuthenticationFailedException, AuthorizationFailedException,
230 PermissionDeniedException, IncorrectStateException,
231 TimeoutException, NoSuccessException;
232
233 /**
234 * Determines the storage size required for an extended I/O operation.
235 *
236 * @param emode
237 * extended mode to use.
238 * @param spec
239 * to determine size for.
240 * @return the size.
241 */
242 public int sizeESync(String emode, String spec) throws NotImplementedException,
243 AuthenticationFailedException, AuthorizationFailedException,
244 IncorrectStateException, PermissionDeniedException,
245 BadParameterException, TimeoutException, NoSuccessException;
246
247 /**
248 * Extended read.
249 *
250 * @param emode
251 * extended mode to use.
252 * @param spec
253 * specification of read operation.
254 * @param buffer
255 * to store the data read.
256 * @return the number of successfully read bytes.
257 */
258 public int readESync(String emode, String spec, Buffer buffer)
259 throws NotImplementedException, AuthenticationFailedException,
260 AuthorizationFailedException, PermissionDeniedException,
261 BadParameterException, IncorrectStateException, TimeoutException,
262 NoSuccessException, SagaIOException;
263
264 /**
265 * Extended write.
266 *
267 * @param emode
268 * extended mode to use.
269 * @param spec
270 * specification of write operation.
271 * @param buffer
272 * data to write.
273 * @return the number of successfully written bytes.
274 */
275 public int writeESync(String emode, String spec, Buffer buffer)
276 throws NotImplementedException, AuthenticationFailedException,
277 AuthorizationFailedException, PermissionDeniedException,
278 BadParameterException, IncorrectStateException, TimeoutException,
279 NoSuccessException, SagaIOException;
280 }