1 /*
2 * jDTAUS Core API
3 * Copyright (C) 2005 Christian Schulte
4 * <cs@schulte.it>
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 *
20 */
21 package org.jdtaus.core.io;
22
23 import java.io.IOException;
24 import java.io.InputStream;
25 import java.io.OutputStream;
26
27 /**
28 * Elementary I/O operations.
29 *
30 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
31 * @version $JDTAUS: FileOperations.java 8743 2012-10-07 03:06:20Z schulte $
32 */
33 public interface FileOperations
34 {
35 //--FileOperations----------------------------------------------------------
36
37 /**
38 * Constant returned by the {@link #read(byte[],int,int)} method if the
39 * end of the file has been reached.
40 */
41 int EOF = -1;
42
43 /**
44 * Gets the length of the file.
45 *
46 * @return the length measured in bytes.
47 *
48 * @throws IOException if getting the length fails.
49 */
50 long getLength() throws IOException;
51
52 /**
53 * Sets the length of the file.
54 * <p>If the present length of the file as returned by the
55 * {@code getLength()} method is greater than the {@code newLength} argument
56 * then the file will be truncated. In this case, if the file offset as
57 * returned by the {@code getFilePointer()} method is greater than
58 * {@code newLength} then after this method returns the offset will be equal
59 * to {@code newLength}.</p>
60 * <p>If the present length of the file as returned by the
61 * {@code getLength()} method is smaller than the {@code newLength} argument
62 * then the file will be extended. In this case, the contents of the
63 * extended portion of the file are not defined.</p>
64 *
65 * @param newLength The desired length of the file.
66 *
67 * @throws IllegalArgumentException if {@code newLength} is negative.
68 * @throws IOException if setting the length fails.
69 */
70 void setLength( long newLength ) throws IOException;
71
72 /**
73 * Returns the current offset in the file.
74 *
75 * @return the offset from the beginning of the file, in bytes, at which the
76 * next read or write occurs.
77 *
78 * @throws IOException if getting the current offset in the file fails.
79 */
80 long getFilePointer() throws IOException;
81
82 /**
83 * Sets the file-pointer offset, measured from the beginning of the file,
84 * at which the next read or write occurs. The offset may be set beyond the
85 * end of the file. Setting the offset beyond the end of the file does not
86 * change the file length. The file length will change only by writing after
87 * the offset has been set beyond the end of the file.
88 *
89 * @param pos the offset position, measured in bytes from the beginning of
90 * the file, at which to set the file pointer.
91 *
92 * @throws IllegalArgumentException if {@code pos} is negative.
93 * @throws IOException if setting the file-pointer offset fails.
94 */
95 void setFilePointer( long pos ) throws IOException;
96
97 /**
98 * Reads up to {@code len} bytes of data from the file into an array of
99 * bytes. An attempt is made to read as many as {@code len} bytes, but a
100 * smaller number may be read.
101 *
102 * @param buf the buffer into which the data is read.
103 * @param off the start offset of the data.
104 * @param len the maximum number of bytes read.
105 *
106 * @return the total number of bytes read into the buffer, or {@link #EOF}
107 * if there is no more data because the end of the file has been reached.
108 *
109 * @throws NullPointerException if {@code buf} is {@code null}.
110 * @throws IndexOutOfBoundsException if either {@code off} or {@code len}
111 * is negative or {@code off + len} is greater than the length of
112 * {@code buf}.
113 * @throws IOException if reading fails.
114 */
115 int read( byte[] buf, int off, int len ) throws IOException;
116
117 /**
118 * Writes {@code len} bytes from the specified byte array starting at
119 * offset {@code off} to the file.
120 *
121 * @param buf the data.
122 * @param off the start offset in the data.
123 * @param len the number of bytes to write.
124 *
125 * @throws IndexOutOfBoundsException if either {@code off} or {@code len}
126 * is negative or {@code off + len} is greater than the length of
127 * {@code buf}.
128 * @throws IOException if writing fails.
129 */
130 void write( byte[] buf, int off, int len ) throws IOException;
131
132 /**
133 * Reads all data from the file to some {@code OutputStream}. The stream
134 * will not get closed after all data has been written.
135 *
136 * @param out an output stream to stream to.
137 *
138 * @throws NullPointerException if {@code out} is {@code null}.
139 * @throws IOException if reading fails.
140 */
141 void read( OutputStream out ) throws IOException;
142
143 /**
144 * Writes all data available from some {@code InputStream}. The stream will
145 * not get closed after all data has been read.
146 *
147 * @param in an input stream providing the data to be written.
148 *
149 * @throws NullPointerException if {@code in} is {@code null}.
150 * @throws IOException if writing fails.
151 */
152 void write( InputStream in ) throws IOException;
153
154 /**
155 * Releases any system resources associated with an instance. A closed
156 * instance cannot perform input or output operations and cannot be
157 * reopened.
158 *
159 * @throws IOException if releasing system resources fails.
160 */
161 void close() throws IOException;
162
163 //----------------------------------------------------------FileOperations--
164 }