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
25 /**
26 * Block oriented I/O operations.
27 *
28 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
29 * @version $JDTAUS: StructuredFile.java 8641 2012-09-27 06:45:17Z schulte $
30 */
31 public interface StructuredFile
32 {
33 //--StructuredFile----------------------------------------------------------
34
35 /**
36 * Reads the length of one block in byte.
37 *
38 * @return length of one block in byte.
39 *
40 * @throws IOException if getting the block size fails.
41 */
42 int getBlockSize() throws IOException;
43
44 /**
45 * Reads the total amount of existing blocks.
46 *
47 * @return total amount of existing blocks.
48 *
49 * @throws IOException if getting the block count fails.
50 */
51 long getBlockCount() throws IOException;
52
53 /**
54 * Inserts new blocks. The content of the new blocks is not further
55 * specified. The new index of the block previously at {@code index} will
56 * be at {@code index + count}.
57 *
58 * @param index index of the first new block.
59 * @param count number of blocks to insert starting at {@code index}.
60 *
61 * @throws IndexOutOfBoundsException if {@code index} or {@code count} is
62 * negativ or {@code index} is greater than {@code getBlockCount()} or
63 * {@code count} is zero or greater than
64 * {@code Long.MAX_VALUE - getBlockCount()}.
65 * @throws IOException if inserting blocks fails.
66 */
67 void insertBlocks( long index, long count ) throws IOException;
68
69 /**
70 * Removes blocks. The new index of the block previously at
71 * {@code index + count} will be at {@code index}.
72 *
73 * @param index index of the first block to start removing {@code count}
74 * blocks.
75 * @param count number of blocks to remove.
76 *
77 * @throws IndexOutOfBoundsException if {@code index} is negative or
78 * {@code count} is negative or zero or {@code index} is greater than
79 * {@code getBlockCount() - count}.
80 * @throws IOException if deleting blocks fails.
81 */
82 void deleteBlocks( long index, long count ) throws IOException;
83
84 /**
85 * Reads {@code buf.length} byte starting at position {@code off} in
86 * {@code block}. Same as {@code readBlock(block, off, buf, 0, buf.length)}.
87 *
88 * @param block index of the block to read data from.
89 * @param off starting offset to the data to read from {@code block}.
90 * @param buf array to store the data in.
91 *
92 * @throws NullPointerException if {@code buf} is {@code null}.
93 * @throws IndexOutOfBoundsException if {@code block} is negative,
94 * greater than or equal to {@code getBlockCount()}, or {@code off} is
95 * negative, greater than or equal to {@code getBlockSize()}, or the length
96 * of {@code buf} is greater than {@code getBlockSize() - off}.
97 * @throws IOException if reading fails.
98 */
99 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 * Releases any system resources associated with an instance. A closed
168 * instance cannot perform input or output operations and cannot be
169 * reopened.
170 *
171 * @throws IOException if releasing system resources fails.
172 */
173 void close() throws IOException;
174
175 /**
176 * Adds a {@code StructuredFileListener} to the listener list.
177 *
178 * @param listener The listener to be added to the listener list.
179 *
180 * @throws NullPointerException if {@code listener} is {@code null}.
181 */
182 void addStructuredFileListener( StructuredFileListener listener );
183
184 /**
185 * Removes a {@code StructuredFileListener} from the listener list.
186 *
187 * @param listener The listener to be removed from the listener list.
188 *
189 * @throws NullPointerException if {@code listener} is {@code null}.
190 */
191 void removeStructuredFileListener( StructuredFileListener listener );
192
193 /**
194 * Gets all currently registered {@code StructuredFileListener}s.
195 *
196 * @return all currently registered {@code StructuredFileListener}s.
197 */
198 StructuredFileListener[] getStructuredFileListeners();
199
200 //----------------------------------------------------------StructuredFile--
201 }