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