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 * Logical DTAUS file (Inlandszahlungsverkehr).
027 *
028 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
029 * @version $JDTAUS: LogicalFile.java 8661 2012-09-27 11:29:58Z schulte $
030 */
031public interface LogicalFile
032{
033
034    /**
035     * Gets the A record of the logical file.
036     *
037     * @return The A record of the logical file.
038     *
039     * @throws IOException if reading fails.
040     */
041    Header getHeader() throws IOException;
042
043    /**
044     * Updates the A record of the logical file.
045     *
046     * @param header New A record for the logical file.
047     *
048     * @return The previous A record of the logical file.
049     *
050     * @throws NullPointerException if {@code header} is {@code null}.
051     * @throws IllegalHeaderException if {@code header} holds illegal values.
052     * @throws IOException if reading or writing fails.
053     */
054    Header setHeader( Header header ) throws IOException;
055
056    /**
057     * Gets the E record of the logical file.
058     *
059     * @return The E record of the logical file.
060     *
061     * @throws IOException if reading fails.
062     */
063    Checksum getChecksum() throws IOException;
064
065    /**
066     * Adds a C record to the logical file.
067     *
068     * @param transaction The transaction to add to the logical file.
069     *
070     * @throws IndexOutOfBoundsException if no more transactions can be added to the logical file.
071     * @throws NullPointerException if {@code transaction} is {@code null}.
072     * @throws IllegalTransactionException if {@code transaction} holds illegal values.
073     * @throws IOException if writing fails.
074     *
075     * @deprecated This method got replaced by {@link #addTransaction(Transaction)} which is capable of returning the
076     * index of the transaction in the file.
077     */
078     void createTransaction( Transaction transaction ) throws IOException;
079
080    /**
081     * Adds a C record to the logical file.
082     *
083     * @param transaction The transaction to add to the logical file.
084     *
085     * @return The index of the transaction in the logical file.
086     *
087     * @throws IndexOutOfBoundsException if no more transactions can be added to the logical file.
088     * @throws NullPointerException if {@code transaction} is {@code null}.
089     * @throws IllegalTransactionException if {@code transaction} holds illegal values.
090     * @throws IOException if writing fails.
091     */
092    int addTransaction( Transaction transaction ) throws IOException;
093
094    /**
095     * Gets a C record for an index.
096     *
097     * @param index The index of the transaction to return.
098     *
099     * @return The C record at {@code index}.
100     *
101     * @throws IndexOutOfBoundsException if the logical file holds transactions and {@code index} is either negative or
102     * greater or equal to the number of transactions stored in the file.
103     * @throws IOException if reading fails.
104     */
105    Transaction getTransaction( int index ) throws IOException;
106
107    /**
108     * Updates a C record at a given index.
109     *
110     * @param index The index of the transaction to update.
111     * @param transaction The transaction to overwrite the transaction at {@code index} with.
112     *
113     * @return The transaction previously stored at {@code index}.
114     *
115     * @throws IndexOutOfBoundsException if the logical file holds transactions and {@code index} is either negative or
116     * greater or equal to the number of transactions stored in the file.
117     * @throws NullPointerException if {@code transaction} is {@code null}.
118     * @throws IllegalTransactionException if {@code transaction} holds illegal values.
119     * @throws IOException if reading or writing fails.
120     */
121    Transaction setTransaction( int index, Transaction transaction ) throws IOException;
122
123    /**
124     * Removes a C record at a given index.
125     *
126     * @param index The index of the transaction to remove.
127     *
128     * @return The removed transaction.
129     *
130     * @throws IndexOutOfBoundsException if the logical file holds transactions and {@code index} is either negative or
131     * greater or equal to the number of transactions stored in the file.
132     * @throws IOException if reading or writing fails.
133     */
134    Transaction removeTransaction( int index ) throws IOException;
135
136}