001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019 package org.apache.commons.compress.archivers;
020
021 import java.io.File;
022 import java.io.IOException;
023 import java.io.OutputStream;
024
025 /**
026 * Archive output stream implementations are expected to override the
027 * {@link #write(byte[], int, int)} method to improve performance.
028 * They should also override {@link #close()} to ensure that any necessary
029 * trailers are added.
030 *
031 * <p>
032 * The normal sequence of calls for working with ArchiveOutputStreams is:
033 * + create ArchiveOutputStream object
034 * + write SFX header (optional, Zip only)
035 * + repeat as needed:
036 * - putArchiveEntry() (writes entry header)
037 * - write() (writes entry data)
038 * - closeArchiveEntry() (closes entry)
039 * + finish() (ends the addition of entries)
040 * + write additional data if format supports it (optional)
041 * + close()
042 * </p>
043 *
044 * <p>
045 * Example usage:<br/>
046 * TBA
047 * </p>
048 */
049 public abstract class ArchiveOutputStream extends OutputStream {
050
051 /** Temporary buffer used for the {@link #write(int)} method */
052 private final byte[] oneByte = new byte[1];
053 static final int BYTE_MASK = 0xFF;
054
055 /** holds the number of bytes read in this stream */
056 private int bytesRead = 0;
057 // Methods specific to ArchiveOutputStream
058
059 /**
060 * Writes the headers for an archive entry to the output stream.
061 * The caller must then write the content to the stream and call
062 * {@link #closeArchiveEntry()} to complete the process.
063 *
064 * @param entry describes the entry
065 * @throws IOException
066 */
067 public abstract void putArchiveEntry(ArchiveEntry entry) throws IOException;
068
069 /**
070 * Closes the archive entry, writing any trailer information that may
071 * be required.
072 * @throws IOException
073 */
074 public abstract void closeArchiveEntry() throws IOException;
075
076 /**
077 * Finishes the addition of entries to this stream, without closing it.
078 * Additional data can be written, if the format supports it.
079 *
080 * The finish() method throws an Exception if the user forgets to close the entry
081 * .
082 * @throws IOException
083 */
084 public abstract void finish() throws IOException;
085
086 /**
087 * Create an archive entry using the inputFile and entryName provided.
088 *
089 * @param inputFile
090 * @param entryName
091 * @return the ArchiveEntry set up with details from the file
092 *
093 * @throws IOException
094 */
095 public abstract ArchiveEntry createArchiveEntry(File inputFile, String entryName) throws IOException;
096
097 // Generic implementations of OutputStream methods that may be useful to sub-classes
098
099 /**
100 * Writes a byte to the current archive entry.
101 *
102 * This method simply calls write( byte[], 0, 1 ).
103 *
104 * MUST be overridden if the {@link #write(byte[], int, int)} method
105 * is not overridden; may be overridden otherwise.
106 *
107 * @param b The byte to be written.
108 * @throws IOException on error
109 */
110 public void write(int b) throws IOException {
111 oneByte[0] = (byte) (b & BYTE_MASK);
112 write(oneByte, 0, 1);
113 }
114
115 /**
116 * Increments the counter of already read bytes.
117 * Doesn't increment if the EOF has been hit (read == -1)
118 *
119 * @param read the number of bytes read
120 */
121 protected void count(int read) {
122 if(read != -1) {
123 bytesRead = bytesRead + read;
124 }
125 }
126
127 /**
128 * Returns the current number of bytes read from this stream.
129 * @return the number of read bytes
130 */
131 public int getCount() {
132 return bytesRead;
133 }
134 }