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