001 /*
002 * jDTAUS Core API
003 * Copyright (c) 2005 Christian Schulte
004 *
005 * Christian Schulte, Haldener Strasse 72, 58095 Hagen, Germany
006 * <schulte2005@users.sourceforge.net> (+49 2331 3543887)
007 *
008 * This library is free software; you can redistribute it and/or
009 * modify it under the terms of the GNU Lesser General Public
010 * License as published by the Free Software Foundation; either
011 * version 2.1 of the License, or any later version.
012 *
013 * This library is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016 * Lesser General Public License for more details.
017 *
018 * You should have received a copy of the GNU Lesser General Public
019 * License along with this library; if not, write to the Free Software
020 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
021 *
022 */
023 package org.jdtaus.core.io;
024
025 import java.io.IOException;
026 import java.io.InputStream;
027 import java.io.OutputStream;
028
029 /**
030 * Elementary I/O operations.
031 *
032 * @author <a href="mailto:schulte2005@users.sourceforge.net">Christian Schulte</a>
033 * @version $Id: FileOperations.java 8044 2009-07-02 01:29:05Z schulte2005 $
034 */
035 public interface FileOperations
036 {
037 //--FileOperations----------------------------------------------------------
038
039 /**
040 * Constant returned by the {@link #read(byte[],int,int)} method if the
041 * end of the file has been reached.
042 */
043 final int EOF = -1;
044
045 /**
046 * Gets the length of the file.
047 *
048 * @return the length measured in bytes.
049 *
050 * @throws IOException if getting the length fails.
051 */
052 long getLength() throws IOException;
053
054 /**
055 * Sets the length of the file.
056 * <p>If the present length of the file as returned by the
057 * {@code getLength()} method is greater than the {@code newLength} argument
058 * then the file will be truncated. In this case, if the file offset as
059 * returned by the {@code getFilePointer()} method is greater than
060 * {@code newLength} then after this method returns the offset will be equal
061 * to {@code newLength}.</p>
062 * <p>If the present length of the file as returned by the
063 * {@code getLength()} method is smaller than the {@code newLength} argument
064 * then the file will be extended. In this case, the contents of the
065 * extended portion of the file are not defined.</p>
066 *
067 * @param newLength The desired length of the file.
068 *
069 * @throws IllegalArgumentException if {@code newLength} is negative.
070 * @throws IOException if setting the length fails.
071 */
072 void setLength( long newLength ) throws IOException;
073
074 /**
075 * Returns the current offset in the file.
076 *
077 * @return the offset from the beginning of the file, in bytes, at which the
078 * next read or write occurs.
079 *
080 * @throws IOException if getting the current offset in the file fails.
081 */
082 long getFilePointer() throws IOException;
083
084 /**
085 * Sets the file-pointer offset, measured from the beginning of the file,
086 * at which the next read or write occurs. The offset may be set beyond the
087 * end of the file. Setting the offset beyond the end of the file does not
088 * change the file length. The file length will change only by writing after
089 * the offset has been set beyond the end of the file.
090 *
091 * @param pos the offset position, measured in bytes from the beginning of
092 * the file, at which to set the file pointer.
093 *
094 * @throws IllegalArgumentException if {@code pos} is negative.
095 * @throws IOException if setting the file-pointer offset fails.
096 */
097 void setFilePointer( long pos ) throws IOException;
098
099 /**
100 * Reads up to {@code len} bytes of data from the file into an array of
101 * bytes. An attempt is made to read as many as {@code len} bytes, but a
102 * smaller number may be read.
103 *
104 * @param buf the buffer into which the data is read.
105 * @param off the start offset of the data.
106 * @param len the maximum number of bytes read.
107 *
108 * @return the total number of bytes read into the buffer, or {@link #EOF}
109 * if there is no more data because the end of the file has been reached.
110 *
111 * @throws NullPointerException if {@code buf} is {@code null}.
112 * @throws IndexOutOfBoundsException if either {@code off} or {@code len}
113 * is negative or {@code off + len} is greater than the length of
114 * {@code buf}.
115 * @throws IOException if reading fails.
116 */
117 int read( byte[] buf, int off, int len ) throws IOException;
118
119 /**
120 * Writes {@code len} bytes from the specified byte array starting at
121 * offset {@code off} to the file.
122 *
123 * @param buf the data.
124 * @param off the start offset in the data.
125 * @param len the number of bytes to write.
126 *
127 * @throws IndexOutOfBoundsException if either {@code off} or {@code len}
128 * is negative or {@code off + len} is greater than the length of
129 * {@code buf}.
130 * @throws IOException if writing fails.
131 */
132 void write( byte[] buf, int off, int len ) throws IOException;
133
134 /**
135 * Reads all data from the file to some {@code OutputStream}. The stream
136 * will not get closed after all data has been written.
137 *
138 * @param out an output stream to stream to.
139 *
140 * @throws NullPointerException if {@code out} is {@code null}.
141 * @throws IOException if reading fails.
142 */
143 void read( OutputStream out ) throws IOException;
144
145 /**
146 * Writes all data available from some {@code InputStream}. The stream will
147 * not get closed after all data has been read.
148 *
149 * @param in an input stream providing the data to be written.
150 *
151 * @throws NullPointerException if {@code in} is {@code null}.
152 * @throws IOException if writing fails.
153 */
154 void write( InputStream in ) throws IOException;
155
156 /**
157 * Releases any system resources associated with an instance. A closed
158 * instance cannot perform input or output operations and cannot be
159 * reopened.
160 *
161 * @throws IOException if releasing system resources fails.
162 */
163 void close() throws IOException;
164
165 //----------------------------------------------------------FileOperations--
166 }