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