OutputArchive


1   /*
2    * OutputArchive.java
3    *
4    * Created on 27. Februar 2006, 00:57
5    */
6   /*
7    * Copyright 2006 Schlichtherle IT Services
8    *
9    * Licensed under the Apache License, Version 2.0 (the "License");
10   * you may not use this file except in compliance with the License.
11   * You may obtain a copy of the License at
12   *
13   *     http://www.apache.org/licenses/LICENSE-2.0
14   *
15   * Unless required by applicable law or agreed to in writing, software
16   * distributed under the License is distributed on an "AS IS" BASIS,
17   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18   * See the License for the specific language governing permissions and
19   * limitations under the License.
20   */
21  
22  package de.schlichtherle.io.archive.spi;
23  
24  import de.schlichtherle.io.OutputArchiveMetaData;
25  import de.schlichtherle.io.archive.spi.InputArchiveBusyException;
26  
27  import java.io.FileNotFoundException  ;
28  import java.io.IOException  ;
29  import java.io.OutputStream  ;
30  import java.util.Enumeration  ;
31  
32  /**
33   * Defines the interface used to write entries to an archive file.
34   * <p>
35   * Implementations do <em>not</em> need to be thread safe.
36   *
37   * @author Christian Schlichtherle
38   * @version @version@
39   * @since TrueZIP 6.0
40   */
41  public interface OutputArchive {
42  
43      /**
44       * Returns the number of {@link ArchiveEntry} instances in this archive.
45       * <p>
46       * This method may be called before the archive is closed and must also
47       * reflect entries which have not yet been completed.
48       */
49      int getNumArchiveEntries();
50  
51      /**
52       * Returns an enumeration of the {@link ArchiveEntry} instances in this
53       * archive (i.e. written so far).
54       * <p>
55       * This method may be called before the archive is closed and must also
56       * reflect entries which have not yet been completed.
57       */
58      Enumeration   getArchiveEntries();
59  
60      /**
61       * Returns the {@link ArchiveEntry} for the given name or
62       * <code>null</code> if no entry with this path name has been written
63       * or just started to be written.
64       * <p>
65       * This method may be called before the archive is closed and must also
66       * reflect entries which have not yet been completed.
67       * 
68       * @param name The name of the <code>ArchiveEntry</code>.
69       */
70      ArchiveEntry getArchiveEntry(String   name);
71  
72      /**
73       * Returns an <code>OutputStream</code> for writing the contents of the
74       * given archive entry.
75       * <p>
76       * The returned stream should preferrably be unbuffered, as buffering is
77       * usually done on higher layers (all copy routines in TrueZIP do this
78       * and most client applications do it, too).
79       * Buffering twice does not increase, but decrease performance.
80       * <p>
81       * Note that the stream is guaranteed to be closed before the
82       * {@link #close()} method of this archive is called!
83       * 
84       * @param entry The archive entry to write. This is <em>never</em>
85       *        <code>null</code> and safe to be casted to the archive entry
86       *        type actually created by the
87       *        {@link ArchiveDriver#createArchiveEntry} method.
88       * @param srcEntry If not <code>null</code>, this identifies the entry
89       *        from which TrueZIP is actually copying data from and should be
90       *        used to implement the Direct Data Copying (DDC) feature.
91       *        Note that there is no guarantee on the runtime type of this
92       *        object; it may have been created by other drivers.
93       *        Furthermore, this <em>not</em> exclusively used for archive
94       *        copies, so you should <em>not</em> simply copy all properties
95       *        of the source entry to the entry (see
96       *        {@link ArchiveDriver#createArchiveEntry(Archive, String, ArchiveEntry)}
97       *        for comparison).
98       *        <p>
99       *        For example, the {@link de.schlichtherle.io.archive.zip.Zip32Driver}
100      *        uses this to copy the already deflated data if the source entry
101      *        is another {@link de.schlichtherle.io.archive.zip.Zip32Entry}.
102      *        As another example, the {@link de.schlichtherle.io.archive.tar.TarDriver}
103      *        uses this to determine the size of the input file, thereby
104      *        removing the need to create (yet another) temporary file.
105      * @return A (preferrably unbuffered) {@link OutputStream} to write the
106      *         archive entry data to.
107      *         <code>null</code> is not allowed!
108      * @throws OutputArchiveBusyException If the archive is currently busy
109      *         on output for another entry.
110      *         This exception is guaranteed to be recoverable, meaning it
111      *         should be possible to write the same entry again as soon as
112      *         the archive is not busy on output anymore.
113      * @throws FileNotFoundException If the archive entry is not accessible
114      *         for some reason.
115      * @throws IOException On any other exceptional condition.
116      */
117     OutputStream   getOutputStream(ArchiveEntry entry, ArchiveEntry srcEntry)
118     throws InputArchiveBusyException, FileNotFoundException  , IOException  ;
119 
120     /**
121      * Writes the given <code>entry</code> as a directory enry.
122      *
123      * @param entry The archive entry to write. This is <em>never</em>
124      *        <code>null</code> and safe to be casted to the archive entry
125      *        type actually created by the
126      *        {@link ArchiveDriver#createArchiveEntry} method.
127      */
128     void storeDirectory(ArchiveEntry entry) throws IOException  ;
129     
130     /**
131      * Closes this output archive and releases any system resources
132      * associated with it.
133      * 
134      * @throws IOException On any I/O related issue.
135      */
136     void close() throws IOException  ;
137 
138     /**
139      * Returns the meta data for this output archive.
140      * This property is used by TrueZIP's virtual file system class and is
141      * transparent to the driver implementation.
142      */
143     OutputArchiveMetaData getMetaData();
144 
145     /**
146      * Sets the meta data for this output archive.
147      * This property is used by TrueZIP's virtual file system class and is
148      * transparent to the driver implementation.
149      */
150     void setMetaData(OutputArchiveMetaData metaData);
151 }
152
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags