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 * https://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 */ 019package org.apache.commons.compress.archivers; 020 021import java.io.File; 022import java.io.IOException; 023import java.io.OutputStream; 024import java.nio.file.LinkOption; 025import java.nio.file.Path; 026 027import org.apache.commons.compress.CompressFilterOutputStream; 028 029/** 030 * Archive output stream implementations are expected to override the {@link #write(byte[], int, int)} method to improve performance. They should also override 031 * {@link #close()} to ensure that any necessary trailers are added. 032 * 033 * <p> 034 * The normal sequence of calls when working with ArchiveOutputStreams is: 035 * </p> 036 * <ul> 037 * <li>Create ArchiveOutputStream object,</li> 038 * <li>optionally write SFX header (Zip only),</li> 039 * <li>repeat as needed: 040 * <ul> 041 * <li>{@link #putArchiveEntry(ArchiveEntry)} (writes entry header), 042 * <li>{@link #write(byte[])} (writes entry data, as often as needed), 043 * <li>{@link #closeArchiveEntry()} (closes entry), 044 * </ul> 045 * </li> 046 * <li>{@link #finish()} (ends the addition of entries),</li> 047 * <li>optionally write additional data, provided format supports it,</li> 048 * <li>{@link #close()}.</li> 049 * </ul> 050 * 051 * @param <E> The type of {@link ArchiveEntry} consumed. 052 */ 053public abstract class ArchiveOutputStream<E extends ArchiveEntry> extends CompressFilterOutputStream<OutputStream> { 054 055 static final int BYTE_MASK = 0xFF; 056 057 /** Temporary buffer used for the {@link #write(int)} method. */ 058 private final byte[] oneByte = new byte[1]; 059 060 /** Holds the number of bytes written to this stream. */ 061 private long bytesWritten; 062 063 /** 064 * Constructs a new instance without a backing OutputStream. 065 * <p> 066 * You must initialize {@code this.out} after construction. 067 * </p> 068 */ 069 public ArchiveOutputStream() { 070 // empty 071 } 072 073 /** 074 * Constructs a new instance with the given backing OutputStream. 075 * 076 * @param out the underlying output stream to be assigned to the field {@code this.out} for later use, or {@code null} if this instance is to be created 077 * without an underlying stream. 078 * @since 1.27.0. 079 */ 080 public ArchiveOutputStream(final OutputStream out) { 081 super(out); 082 } 083 084 /** 085 * Tests whether this stream is able to write the given entry. 086 * 087 * <p> 088 * Some archive formats support variants or details that are not supported (yet). 089 * </p> 090 * 091 * @param archiveEntry the entry to test 092 * @return This implementation always returns true. 093 * @since 1.1 094 */ 095 public boolean canWriteEntryData(final ArchiveEntry archiveEntry) { 096 return true; 097 } 098 099 /** 100 * Throws an {@link IOException} if this instance is already finished. 101 * 102 * @throws IOException if this instance is already finished. 103 * @since 1.27.0 104 */ 105 protected void checkFinished() throws IOException { 106 if (isFinished()) { 107 throw new IOException("Stream has already been finished."); 108 } 109 } 110 111 /** 112 * Closes the archive entry, writing any trailer information that may be required. 113 * 114 * @throws IOException if an I/O error occurs 115 */ 116 public abstract void closeArchiveEntry() throws IOException; 117 118 /** 119 * Increments the counter of already written bytes. Doesn't increment if EOF has been hit ({@code written == -1}). 120 * 121 * @param written the number of bytes written 122 */ 123 protected void count(final int written) { 124 count((long) written); 125 } 126 127 /** 128 * Increments the counter of already written bytes. Doesn't increment if EOF has been hit ({@code written == -1}). 129 * 130 * @param written the number of bytes written 131 * @since 1.1 132 */ 133 protected void count(final long written) { 134 if (written != -1) { 135 bytesWritten += written; 136 } 137 } 138 139 /** 140 * Creates an archive entry using the inputFile and entryName provided. 141 * 142 * @param inputFile the file to create the entry from 143 * @param entryName name to use for the entry 144 * @return the ArchiveEntry set up with details from the file 145 * @throws IOException if an I/O error occurs 146 */ 147 public abstract E createArchiveEntry(File inputFile, String entryName) throws IOException; 148 149 /** 150 * Creates an archive entry using the inputPath and entryName provided. 151 * <p> 152 * The default implementation calls simply delegates as: 153 * </p> 154 * 155 * <pre> 156 * return createArchiveEntry(inputFile.toFile(), entryName); 157 * </pre> 158 * <p> 159 * Subclasses should override this method. 160 * </p> 161 * 162 * @param inputPath the file to create the entry from 163 * @param entryName name to use for the entry 164 * @param options options indicating how symbolic links are handled. 165 * @return the ArchiveEntry set up with details from the file 166 * @throws IOException if an I/O error occurs 167 * @since 1.21 168 */ 169 public E createArchiveEntry(final Path inputPath, final String entryName, final LinkOption... options) throws IOException { 170 return createArchiveEntry(inputPath.toFile(), entryName); 171 } 172 173 /** 174 * Gets the current number of bytes written to this stream. 175 * 176 * @return the number of written bytes 177 * @since 1.1 178 */ 179 public long getBytesWritten() { 180 return bytesWritten; 181 } 182 183 /** 184 * Gets the current number of bytes written to this stream. 185 * 186 * @return the number of written bytes 187 * @deprecated this method may yield wrong results for large archives, use #getBytesWritten instead 188 */ 189 @Deprecated 190 public int getCount() { 191 return (int) bytesWritten; 192 } 193 194 /** 195 * Writes the headers for an archive entry to the output stream. The caller must then write the content to the stream and call {@link #closeArchiveEntry()} 196 * to complete the process. 197 * 198 * @param entry describes the entry 199 * @throws IOException if an I/O error occurs 200 */ 201 public abstract void putArchiveEntry(E entry) throws IOException; 202 203 /** 204 * Writes a byte to the current archive entry. 205 * 206 * <p> 207 * This method simply calls {@code write( byte[], 0, 1 )}. 208 * 209 * <p> 210 * MUST be overridden if the {@link #write(byte[], int, int)} method is not overridden; may be overridden otherwise. 211 * 212 * @param b The byte to be written. 213 * @throws IOException on error 214 */ 215 @Override 216 public void write(final int b) throws IOException { 217 oneByte[0] = (byte) (b & BYTE_MASK); 218 write(oneByte, 0, 1); 219 } 220}