001/*
002 *  jDTAUS Banking 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.banking.dtaus;
022
023import java.io.IOException;
024
025/**
026 * Physical DTAUS file (Inlandszahlungsverkehr).
027 *
028 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
029 * @version $JDTAUS: PhysicalFile.java 8661 2012-09-27 11:29:58Z schulte $
030 */
031public interface PhysicalFile
032{
033
034    /**
035     * Gets the number of logical files stored in the physical file.
036     *
037     * @return The number of logical files stored in the physical file.
038     *
039     * @throws IOException if reading fails.
040     *
041     * @deprecated This method got renamed to {@link #getLogicalFileCount()}.
042     */
043     int count() throws IOException;
044
045    /**
046     * Gets the number of logical files stored in the physical file.
047     *
048     * @return Number of logical files stored in the physical file.
049     *
050     * @throws IOException if reading fails.
051     */
052    int getLogicalFileCount() throws IOException;
053
054    /**
055     * Adds a logical file to the physical file.
056     *
057     * @param header The A record of the new logical file.
058     *
059     * @return The added logical file.
060     *
061     * @throws NullPointerException if {@code header} is {@code null}.
062     * @throws IllegalHeaderException if {@code header} holds illegal values.
063     * @throws IOException if reading or writing fails.
064     *
065     * @deprecated This method got renamed to {@link #addLogicalFile(Header)}.
066     */
067     LogicalFile add( Header header ) throws IOException;
068
069    /**
070     * Adds a logical file to the physical file.
071     *
072     * @param header The A record of the new logical file.
073     *
074     * @return The added logical file.
075     *
076     * @throws NullPointerException if {@code header} is {@code null}.
077     * @throws IllegalHeaderException if {@code header} holds illegal values.
078     * @throws IOException if reading or writing fails.
079     */
080    LogicalFile addLogicalFile( Header header ) throws IOException;
081
082    /**
083     * Gets a logical file for an index.
084     *
085     * @param index The index of the logical file to return.
086     *
087     * @return The logical file at {@code index}.
088     *
089     * @throws IndexOutOfBoundsException if {@code index} is either negative, or greater or equal to {@code count()}.
090     * @throws IOException if reading fails.
091     *
092     * @deprecated This method got renamed to {@link #getLogicalFile(int)}.
093     */
094     LogicalFile get( int index ) throws IOException;
095
096    /**
097     * Gets a logical file for an index.
098     *
099     * @param index The index of the logical file to return.
100     *
101     * @return The logical file at {@code index}.
102     *
103     * @throws IndexOutOfBoundsException if {@code index} is either negative, or greater or equal to {@code count()}.
104     * @throws IOException if reading fails.
105     */
106    LogicalFile getLogicalFile( int index ) throws IOException;
107
108    /**
109     * Removes a logical file from the physical file.
110     *
111     * @param index The index of the logical file to remove.
112     *
113     * @throws IndexOutOfBoundsException if {@code index} is either negative, or greater or equal to {@code count()}.
114     * @throws IOException if reading or writing fails.
115     *
116     * @deprecated This method got renamed to {@link #removeLogicalFile(int)}.
117     */
118     void remove( int index ) throws IOException;
119
120    /**
121     * Removes a logical file from the physical file.
122     *
123     * @param index The index of the logical file to remove.
124     *
125     * @throws IndexOutOfBoundsException if {@code index} is either negative, or greater or equal to {@code count()}.
126     * @throws IOException if reading or writing fails.
127     */
128    void removeLogicalFile( int index ) throws IOException;
129
130    /**
131     * Commits any pending changes.
132     * <p><b>Note:</b><br/>
133     * This method should be called once after finishing work with an instance. Implementations may close any open files
134     * when calling this method so that no more operations will be possible after the method returns. Therefore state of
135     * an instance is undefined after calling this method. Also note that not calling this method may lead to leaking
136     * open file descriptors in the system.</p>
137     *
138     * @throws IOException if reading or writing fails.
139     */
140    void commit() throws IOException;
141
142}