001/*
002 *  jDTAUS Core API
003 *  Copyright (C) 2005 Christian Schulte
004 *  <cs@schulte.it>
005 *
006 *  This library is free software; you can redistribute it and/or
007 *  modify it under the terms of the GNU Lesser General Public
008 *  License as published by the Free Software Foundation; either
009 *  version 2.1 of the License, or any later version.
010 *
011 *  This library is distributed in the hope that it will be useful,
012 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 *  Lesser General Public License for more details.
015 *
016 *  You should have received a copy of the GNU Lesser General Public
017 *  License along with this library; if not, write to the Free Software
018 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
019 *
020 */
021package org.jdtaus.core.io;
022
023import java.io.IOException;
024
025/**
026 * Block oriented I/O operations.
027 *
028 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
029 * @version $JDTAUS: StructuredFile.java 8641 2012-09-27 06:45:17Z schulte $
030 */
031public interface StructuredFile
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     * 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}