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
027 /**
028 * Block oriented I/O operations.
029 *
030 * @author <a href="mailto:schulte2005@users.sourceforge.net">Christian Schulte</a>
031 * @version $Id: StructuredFile.java 8044 2009-07-02 01:29:05Z schulte2005 $
032 */
033 public interface StructuredFile
034 {
035 //--StructuredFile----------------------------------------------------------
036
037 /**
038 * Reads the length of one block in byte.
039 *
040 * @return length of one block in byte.
041 *
042 * @throws IOException if getting the block size fails.
043 */
044 int getBlockSize() throws IOException;
045
046 /**
047 * Reads the total amount of existing blocks.
048 *
049 * @return total amount of existing blocks.
050 *
051 * @throws IOException if getting the block count fails.
052 */
053 long getBlockCount() throws IOException;
054
055 /**
056 * Inserts new blocks. The content of the new blocks is not further
057 * specified. The new index of the block previously at {@code index} will
058 * be at {@code index + count}.
059 *
060 * @param index index of the first new block.
061 * @param count number of blocks to insert starting at {@code index}.
062 *
063 * @throws IndexOutOfBoundsException if {@code index} or {@code count} is
064 * negativ or {@code index} is greater than {@code getBlockCount()} or
065 * {@code count} is zero or greater than
066 * {@code Long.MAX_VALUE - getBlockCount()}.
067 * @throws IOException if inserting blocks fails.
068 */
069 void insertBlocks( long index, long count ) throws IOException;
070
071 /**
072 * Removes blocks. The new index of the block previously at
073 * {@code index + count} will be at {@code index}.
074 *
075 * @param index index of the first block to start removing {@code count}
076 * blocks.
077 * @param count number of blocks to remove.
078 *
079 * @throws IndexOutOfBoundsException if {@code index} is negative or
080 * {@code count} is negative or zero or {@code index} is greater than
081 * {@code getBlockCount() - count}.
082 * @throws IOException if deleting blocks fails.
083 */
084 void deleteBlocks( long index, long count ) throws IOException;
085
086 /**
087 * Reads {@code buf.length} byte starting at position {@code off} in
088 * {@code block}. Same as {@code readBlock(block, off, buf, 0, buf.length)}.
089 *
090 * @param block index of the block to read data from.
091 * @param off starting offset to the data to read from {@code block}.
092 * @param buf array to store the data in.
093 *
094 * @throws NullPointerException if {@code buf} is {@code null}.
095 * @throws IndexOutOfBoundsException if {@code block} is negative,
096 * greater than or equal to {@code getBlockCount()}, or {@code off} is
097 * negative, greater than or equal to {@code getBlockSize()}, or the length
098 * of {@code buf} is greater than {@code getBlockSize() - off}.
099 * @throws IOException if reading fails.
100 */
101 void readBlock( long block, int off, byte[] buf ) throws IOException;
102
103 /**
104 * Reads {@code length} byte starting at position {@code off} in
105 * {@code block} into {@code buf} starting at {@code index} inclusive.
106 *
107 * @param block index of the block to read data from.
108 * @param off starting offset of the data to read from {@code block}.
109 * @param buf array to store the data in.
110 * @param index offset to start writing data into {@code buf}.
111 * @param length number of byte to read.
112 *
113 * @throws NullPointerException if {@code buf} is {@code null}.
114 * @throws IndexOutOfBoundsException if {@code block} is negative,
115 * greater than or equal to {@code getBlockCount()}, or {@code off} is
116 * negative, greater than or equal to {@code getBlockSize()}, or
117 * {@code index} is negative, greater than or equal to the length of
118 * {@code buf}, or {@code length} is negative or greater than the
119 * length of {@code buf} minus {@code index} or greater than
120 * {@code getBlockSize() - off}.
121 * @throws IOException if reading fails.
122 */
123 void readBlock( long block, int off, byte[] buf, int index,
124 int length ) throws IOException;
125
126 /**
127 * Writes {@code buf.length} byte from {@code buf} into {@code block}
128 * starting at {@code off} inclusive. Same as
129 * {@code writeBlock(block, off, buf, 0, buf.length)}.
130 *
131 * @param block index of the block to write into.
132 * @param off inclusive offset to start writing into {@code block}.
133 * @param buf data to write into {@code block} beginning at {@code offset}.
134 *
135 * @throws NullPointerException if {@code buf} is {@code null}.
136 * @throws IndexOutOfBoundsException if {@code block} is negative,
137 * greater than or equal to {@code getBlockCount()}, or {@code off} is
138 * greater than or equal to {@code getBlockSize()}, or the length of
139 * {@code buf} is greater than {@code getBlockSize() - off}.
140 * @throws IOException if writing fails.
141 */
142 void writeBlock( long block, int off, byte[] buf ) throws IOException;
143
144 /**
145 * Writes {@code length} byte from {@code buf} starting at {@code index}
146 * inclusive into {@code block} starting at {@code off} inclusive.
147 *
148 * @param block index of the block to write into.
149 * @param off inclusive offset to start writing into {@code block}.
150 * @param buf data to write into {@code block} beginning at {@code offset}.
151 * @param index inclusive offset to start reading data from {@code buf}.
152 * @param length number of byte to read from {@code buf} starting at
153 * {@code index}.
154 *
155 * @throws NullPointerException if {@code buf} is {@code null}.
156 * @throws IndexOutOfBoundsException if {@code block} is negative,
157 * greater than or equal to {@code getBlockCount()}, or {@code off} is
158 * negative, greater than or equal to {@code getBlockSize()}, or
159 * {@code index} is negative, greater than or equal to the length of
160 * {@code buf}, or {@code length} is negative or greater than the
161 * length of {@code buf} minus {@code index} or greater than
162 * {@code getBlockSize() - off}.
163 * @throws IOException if writing fails.
164 */
165 void writeBlock( long block, int off, byte[] buf, int index,
166 int length ) throws IOException;
167
168 /**
169 * Releases any system resources associated with an instance. A closed
170 * instance cannot perform input or output operations and cannot be
171 * reopened.
172 *
173 * @throws IOException if releasing system resources fails.
174 */
175 void close() throws IOException;
176
177 /**
178 * Adds a {@code StructuredFileListener} to the listener list.
179 *
180 * @param listener The listener to be added to the listener list.
181 *
182 * @throws NullPointerException if {@code listener} is {@code null}.
183 */
184 void addStructuredFileListener( StructuredFileListener listener );
185
186 /**
187 * Removes a {@code StructuredFileListener} from the listener list.
188 *
189 * @param listener The listener to be removed from the listener list.
190 *
191 * @throws NullPointerException if {@code listener} is {@code null}.
192 */
193 void removeStructuredFileListener( StructuredFileListener listener );
194
195 /**
196 * Gets all currently registered {@code StructuredFileListener}s.
197 *
198 * @return all currently registered {@code StructuredFileListener}s.
199 */
200 StructuredFileListener[] getStructuredFileListeners();
201
202 //----------------------------------------------------------StructuredFile--
203 }