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.File;
024import java.io.IOException;
025import java.util.Properties;
026import org.jdtaus.core.io.FileOperations;
027
028/**
029 * Factory for {@code PhysicalFile} instances.
030 * <p>Example: Getting the jDTAUS Banking SPI implementation.<br/><pre>
031 * PhysicalFileFactory factory =
032 *     (PhysicalFileFactory) ContainerFactory.getContainer().
033 *     getObject( PhysicalFileFactory.class );
034 * </pre></p>
035 *
036 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
037 * @version $JDTAUS: PhysicalFileFactory.java 8661 2012-09-27 11:29:58Z schulte $
038 *
039 * @see org.jdtaus.core.container.Container
040 */
041public interface PhysicalFileFactory
042{
043
044    /** Constant for the DTAUS disk format. */
045    int FORMAT_DISK = 128;
046
047    /** Constant for the DTAUS tape format. */
048    int FORMAT_TAPE = 150;
049
050    /**
051     * Creates a new {@code PhysicalFile} on a given {@code File}.
052     *
053     * @param file The file to create a new DTAUS file with.
054     * @param format Constant for the format of the new DTAUS file.
055     *
056     * @return An empty DTAUS file.
057     *
058     * @throws NullPointerException if {@code file} is {@code null}.
059     * @throws IllegalArgumentException if {@code format} is neither {@code FORMAT_DISK} nor {@code FORMAT_TAPE}.
060     * @throws IOException if creating a new DTAUS file fails.
061     *
062     * @see #FORMAT_DISK
063     * @see #FORMAT_TAPE
064     * @see PhysicalFile#commit()
065     */
066    PhysicalFile createPhysicalFile( File file, int format ) throws IOException;
067
068    /**
069     * Creates a new {@code PhysicalFile} on a given {@code File} taking properties to configure the implementation.
070     *
071     * @param file The file to create a new DTAUS file with.
072     * @param format Constant for the format of the new DTAUS file.
073     * @param properties Properties to be passed to implementations.
074     *
075     * @return An empty DTAUS file.
076     *
077     * @throws NullPointerException if either {@code file} or {@code properties} is {@code null}.
078     * @throws IllegalArgumentException if {@code format} is neither {@code FORMAT_DISK} nor {@code FORMAT_TAPE}.
079     * @throws IOException if creating a new DTAUS file fails.
080     *
081     * @see #FORMAT_DISK
082     * @see #FORMAT_TAPE
083     * @see PhysicalFile#commit()
084     */
085    PhysicalFile createPhysicalFile( File file, int format, Properties properties ) throws IOException;
086
087    /**
088     * Creates a new {@code PhysicalFile} on given {@code FileOperations}.
089     *
090     * @param ops The {@code FileOperations} to create a new DTAUS file with.
091     * @param format Constant for the format of the new DTAUS file.
092     *
093     * @return An empty DTAUS file.
094     *
095     * @throws NullPointerException if {@code ops} is {@code null}.
096     * @throws IllegalArgumentException if {@code format} is neither {@code FORMAT_DISK} nor {@code FORMAT_TAPE}.
097     * @throws IOException if creating a new DTAUS file fails.
098     *
099     * @see #FORMAT_DISK
100     * @see #FORMAT_TAPE
101     * @see PhysicalFile#commit()
102     */
103    PhysicalFile createPhysicalFile( FileOperations ops, int format ) throws IOException;
104
105    /**
106     * Creates a new {@code PhysicalFile} on given {@code FileOperations} taking properties to configure the implementation.
107     *
108     * @param ops The {@code FileOperations} to create a new DTAUS file with.
109     * @param format Constant for the format of the new DTAUS file.
110     * @param properties Properties to be passed to implementations.
111     *
112     * @return An empty DTAUS file.
113     *
114     * @throws NullPointerException if either {@code ops} or {@code properties} is {@code null}.
115     * @throws IllegalArgumentException if {@code format} is neither {@code FORMAT_DISK} nor {@code FORMAT_TAPE}.
116     * @throws IOException if creating a new DTAUS file fails.
117     *
118     * @see #FORMAT_DISK
119     * @see #FORMAT_TAPE
120     * @see PhysicalFile#commit()
121     */
122    PhysicalFile createPhysicalFile( FileOperations ops, int format, Properties properties ) throws IOException;
123
124    /**
125     * Detects the format by analysing the given {@code File}.
126     *
127     * @param file The file to analyse.
128     *
129     * @return Constant for the detected format.
130     *
131     * @throws NullPointerException if {@code file} is {@code null}.
132     * @throws PhysicalFileException if {@code file} provides a file containing errors.
133     * @throws IOException if reading fails.
134     *
135     * @see #FORMAT_DISK
136     * @see #FORMAT_TAPE
137     * @see PhysicalFile#commit()
138     */
139    int analyse( File file ) throws PhysicalFileException, IOException;
140
141    /**
142     * Detects the format by analysing the given {@code FileOperations}.
143     *
144     * @param ops {@code FileOperations} to analyse.
145     *
146     * @return Constant for the detected format.
147     *
148     * @throws NullPointerException if {@code ops} is {@code null}.
149     * @throws PhysicalFileException if {@code ops} provides a file containing errors.
150     * @throws IOException if reading fails.
151     *
152     * @see #FORMAT_DISK
153     * @see #FORMAT_TAPE
154     * @see PhysicalFile#commit()
155     */
156    int analyse( FileOperations ops ) throws PhysicalFileException, IOException;
157
158    /**
159     * Reads a {@code PhysicalFile} from a given {@code File}.
160     *
161     * @param file The file to create a {@code PhysicalFile} instance from.
162     *
163     * @return New {@code PhysicalFile} instance for {@code file}.
164     *
165     * @throws NullPointerException if {@code file} is {@code null}.
166     * @throws PhysicalFileException if {@code file} provides a file containing errors.
167     * @throws IOException if reading fails.
168     *
169     * @see PhysicalFile#commit()
170     */
171    PhysicalFile getPhysicalFile( File file ) throws PhysicalFileException, IOException;
172
173    /**
174     * Reads a {@code PhysicalFile} from a given {@code File} taking properties to configure the implementation.
175     *
176     * @param file The file to create a {@code PhysicalFile} instance from.
177     * @param properties Properties to be passed to implementations.
178     *
179     * @return New {@code PhysicalFile} instance for {@code file}.
180     *
181     * @throws NullPointerException if either {@code file} or {@code properties} is {@code null}.
182     * @throws PhysicalFileException if {@code file} provides a file containing errors.
183     * @throws IOException if reading fails.
184     *
185     * @see PhysicalFile#commit()
186     */
187    PhysicalFile getPhysicalFile( File file, Properties properties ) throws PhysicalFileException, IOException;
188
189    /**
190     * Reads a {@code PhysicalFile} from given {@code FileOperations}.
191     *
192     * @param ops {@code FileOperations} to create a {@code PhysicalFile} instance from.
193     *
194     * @return New {@code PhysicalFile} instance for {@code ops}.
195     *
196     * @throws NullPointerException if {@code ops} is {@code null}.
197     * @throws PhysicalFileException if {@code ops} provides a file containing errors.
198     * @throws IOException if reading fails.
199     *
200     * @see PhysicalFile#commit()
201     */
202    PhysicalFile getPhysicalFile( FileOperations ops ) throws PhysicalFileException, IOException;
203
204    /**
205     * Reads a {@code PhysicalFile} from given {@code FileOperations} taking properties to configure the implementation.
206     *
207     * @param ops {@code FileOperations} to create a {@code PhysicalFile} instance from.
208     * @param properties properties to be passed to implementations.
209     *
210     * @return new {@code PhysicalFile} instance for {@code ops}.
211     *
212     * @throws NullPointerException if either {@code ops} or {@code properties} is {@code null}.
213     * @throws PhysicalFileException if {@code ops} provides a file containing errors.
214     * @throws IOException if reading fails.
215     *
216     * @see PhysicalFile#commit()
217     */
218    PhysicalFile getPhysicalFile( FileOperations ops, Properties properties ) throws PhysicalFileException, IOException;
219
220}