Torsten Curdt | ca16539 | 2008-07-10 10:17:44 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Licensed to the Apache Software Foundation (ASF) under one |
| 3 | * or more contributor license agreements. See the NOTICE file |
| 4 | * distributed with this work for additional information |
| 5 | * regarding copyright ownership. The ASF licenses this file |
| 6 | * to you under the Apache License, Version 2.0 (the |
| 7 | * "License"); you may not use this file except in compliance |
| 8 | * with the License. You may obtain a copy of the License at |
| 9 | * |
| 10 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | * |
| 12 | * Unless required by applicable law or agreed to in writing, |
| 13 | * software distributed under the License is distributed on an |
| 14 | * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | * KIND, either express or implied. See the License for the |
| 16 | * specific language governing permissions and limitations |
| 17 | * under the License. |
| 18 | */ |
| 19 | package org.apache.commons.compress.archivers; |
| 20 | |
Sebastian Bazley | fec51a1 | 2009-03-31 00:35:56 +0000 | [diff] [blame] | 21 | import java.io.File; |
Torsten Curdt | ca16539 | 2008-07-10 10:17:44 +0000 | [diff] [blame] | 22 | import java.io.IOException; |
| 23 | import java.io.OutputStream; |
| 24 | |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 25 | /** |
| 26 | * Archive output stream implementations are expected to override the |
| 27 | * {@link #write(byte[], int, int)} method to improve performance. |
| 28 | * They should also override {@link #close()} to ensure that any necessary |
| 29 | * trailers are added. |
Christian Grobmeier | 6dfdfb5 | 2009-04-22 05:19:58 +0000 | [diff] [blame] | 30 | * |
Stefan Bodewig | d244dc6 | 2013-04-25 15:25:04 +0000 | [diff] [blame] | 31 | * <p>The normal sequence of calls when working with ArchiveOutputStreams is:</p> |
| 32 | * <ul> |
| 33 | * <li>Create ArchiveOutputStream object,</li> |
| 34 | * <li>optionally write SFX header (Zip only),</li> |
| 35 | * <li>repeat as needed: |
| 36 | * <ul> |
| 37 | * <li>{@link #putArchiveEntry(ArchiveEntry)} (writes entry header), |
| 38 | * <li>{@link #write(byte[])} (writes entry data, as often as needed), |
| 39 | * <li>{@link #closeArchiveEntry()} (closes entry), |
| 40 | * </ul> |
| 41 | * </li> |
| 42 | * <li> {@link #finish()} (ends the addition of entries),</li> |
| 43 | * <li> optionally write additional data, provided format supports it,</li> |
| 44 | * <li>{@link #close()}.</li> |
| 45 | * </ul> |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 46 | */ |
Stefan Bodewig | c30b588 | 2009-02-10 15:35:35 +0000 | [diff] [blame] | 47 | public abstract class ArchiveOutputStream extends OutputStream { |
Sebastian Bazley | 39c93f4 | 2012-03-31 12:30:09 +0000 | [diff] [blame] | 48 | |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 49 | /** Temporary buffer used for the {@link #write(int)} method */ |
| 50 | private final byte[] oneByte = new byte[1]; |
| 51 | static final int BYTE_MASK = 0xFF; |
Stefan Bodewig | f77e1f1 | 2009-02-06 17:24:01 +0000 | [diff] [blame] | 52 | |
Stefan Bodewig | 2dca661 | 2010-02-18 16:10:20 +0000 | [diff] [blame] | 53 | /** holds the number of bytes written to this stream */ |
| 54 | private long bytesWritten = 0; |
Sebastian Bazley | cf003d1 | 2009-03-30 20:35:08 +0000 | [diff] [blame] | 55 | // Methods specific to ArchiveOutputStream |
Sebastian Bazley | 39c93f4 | 2012-03-31 12:30:09 +0000 | [diff] [blame] | 56 | |
Sebastian Bazley | cf003d1 | 2009-03-30 20:35:08 +0000 | [diff] [blame] | 57 | /** |
| 58 | * Writes the headers for an archive entry to the output stream. |
| 59 | * The caller must then write the content to the stream and call |
| 60 | * {@link #closeArchiveEntry()} to complete the process. |
| 61 | * |
| 62 | * @param entry describes the entry |
| 63 | * @throws IOException |
| 64 | */ |
Stefan Bodewig | f77e1f1 | 2009-02-06 17:24:01 +0000 | [diff] [blame] | 65 | public abstract void putArchiveEntry(ArchiveEntry entry) throws IOException; |
Stefan Bodewig | 3f9bcc6 | 2009-02-10 14:20:05 +0000 | [diff] [blame] | 66 | |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 67 | /** |
| 68 | * Closes the archive entry, writing any trailer information that may |
| 69 | * be required. |
| 70 | * @throws IOException |
| 71 | */ |
Torsten Curdt | ca16539 | 2008-07-10 10:17:44 +0000 | [diff] [blame] | 72 | public abstract void closeArchiveEntry() throws IOException; |
Sebastian Bazley | 39c93f4 | 2012-03-31 12:30:09 +0000 | [diff] [blame] | 73 | |
Christian Grobmeier | 6dfdfb5 | 2009-04-22 05:19:58 +0000 | [diff] [blame] | 74 | /** |
| 75 | * Finishes the addition of entries to this stream, without closing it. |
| 76 | * Additional data can be written, if the format supports it. |
Christian Grobmeier | d170f34 | 2009-04-22 06:05:23 +0000 | [diff] [blame] | 77 | * |
Stefan Bodewig | d244dc6 | 2013-04-25 15:25:04 +0000 | [diff] [blame] | 78 | * @throws IOException if the user forgets to close the entry. |
Christian Grobmeier | 6dfdfb5 | 2009-04-22 05:19:58 +0000 | [diff] [blame] | 79 | */ |
| 80 | public abstract void finish() throws IOException; |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 81 | |
Sebastian Bazley | fec51a1 | 2009-03-31 00:35:56 +0000 | [diff] [blame] | 82 | /** |
| 83 | * Create an archive entry using the inputFile and entryName provided. |
| 84 | * |
| 85 | * @param inputFile |
| 86 | * @param entryName |
| 87 | * @return the ArchiveEntry set up with details from the file |
| 88 | * |
| 89 | * @throws IOException |
| 90 | */ |
| 91 | public abstract ArchiveEntry createArchiveEntry(File inputFile, String entryName) throws IOException; |
Sebastian Bazley | 39c93f4 | 2012-03-31 12:30:09 +0000 | [diff] [blame] | 92 | |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 93 | // Generic implementations of OutputStream methods that may be useful to sub-classes |
Sebastian Bazley | 39c93f4 | 2012-03-31 12:30:09 +0000 | [diff] [blame] | 94 | |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 95 | /** |
| 96 | * Writes a byte to the current archive entry. |
| 97 | * |
Stefan Bodewig | d244dc6 | 2013-04-25 15:25:04 +0000 | [diff] [blame] | 98 | * <p>This method simply calls {@code write( byte[], 0, 1 )}. |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 99 | * |
Stefan Bodewig | d244dc6 | 2013-04-25 15:25:04 +0000 | [diff] [blame] | 100 | * <p>MUST be overridden if the {@link #write(byte[], int, int)} method |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 101 | * is not overridden; may be overridden otherwise. |
| 102 | * |
| 103 | * @param b The byte to be written. |
| 104 | * @throws IOException on error |
| 105 | */ |
Sebastian Bazley | fb06e3a | 2011-08-15 15:10:46 +0000 | [diff] [blame] | 106 | @Override |
Sebastian Bazley | 52fcfa0 | 2009-03-30 17:17:58 +0000 | [diff] [blame] | 107 | public void write(int b) throws IOException { |
| 108 | oneByte[0] = (byte) (b & BYTE_MASK); |
| 109 | write(oneByte, 0, 1); |
| 110 | } |
| 111 | |
Christian Grobmeier | ab26943 | 2009-04-24 06:30:17 +0000 | [diff] [blame] | 112 | /** |
Stefan Bodewig | 2dca661 | 2010-02-18 16:10:20 +0000 | [diff] [blame] | 113 | * Increments the counter of already written bytes. |
Stefan Bodewig | d244dc6 | 2013-04-25 15:25:04 +0000 | [diff] [blame] | 114 | * Doesn't increment if EOF has been hit ({@code written == -1}). |
Christian Grobmeier | ab26943 | 2009-04-24 06:30:17 +0000 | [diff] [blame] | 115 | * |
Stefan Bodewig | b0d75e6 | 2010-02-18 16:30:37 +0000 | [diff] [blame] | 116 | * @param written the number of bytes written |
Christian Grobmeier | ab26943 | 2009-04-24 06:30:17 +0000 | [diff] [blame] | 117 | */ |
Stefan Bodewig | 58568f4 | 2010-02-18 16:24:31 +0000 | [diff] [blame] | 118 | protected void count(int written) { |
| 119 | count((long) written); |
Stefan Bodewig | 2dca661 | 2010-02-18 16:10:20 +0000 | [diff] [blame] | 120 | } |
| 121 | |
| 122 | /** |
| 123 | * Increments the counter of already written bytes. |
Stefan Bodewig | d244dc6 | 2013-04-25 15:25:04 +0000 | [diff] [blame] | 124 | * Doesn't increment if EOF has been hit ({@code written == -1}). |
Stefan Bodewig | 2dca661 | 2010-02-18 16:10:20 +0000 | [diff] [blame] | 125 | * |
| 126 | * @param written the number of bytes written |
Gary D. Gregory | 2bd0dd4 | 2012-04-01 13:02:39 +0000 | [diff] [blame] | 127 | * @since 1.1 |
Stefan Bodewig | 2dca661 | 2010-02-18 16:10:20 +0000 | [diff] [blame] | 128 | */ |
| 129 | protected void count(long written) { |
| 130 | if (written != -1) { |
| 131 | bytesWritten = bytesWritten + written; |
Christian Grobmeier | ab26943 | 2009-04-24 06:30:17 +0000 | [diff] [blame] | 132 | } |
| 133 | } |
Sebastian Bazley | 39c93f4 | 2012-03-31 12:30:09 +0000 | [diff] [blame] | 134 | |
Christian Grobmeier | ab26943 | 2009-04-24 06:30:17 +0000 | [diff] [blame] | 135 | /** |
Stefan Bodewig | 2dca661 | 2010-02-18 16:10:20 +0000 | [diff] [blame] | 136 | * Returns the current number of bytes written to this stream. |
| 137 | * @return the number of written bytes |
| 138 | * @deprecated this method may yield wrong results for large |
| 139 | * archives, use #getBytesWritten instead |
Christian Grobmeier | ab26943 | 2009-04-24 06:30:17 +0000 | [diff] [blame] | 140 | */ |
Stefan Bodewig | 4a82530 | 2011-08-06 13:20:22 +0000 | [diff] [blame] | 141 | @Deprecated |
Christian Grobmeier | ab26943 | 2009-04-24 06:30:17 +0000 | [diff] [blame] | 142 | public int getCount() { |
Stefan Bodewig | 2dca661 | 2010-02-18 16:10:20 +0000 | [diff] [blame] | 143 | return (int) bytesWritten; |
| 144 | } |
| 145 | |
| 146 | /** |
| 147 | * Returns the current number of bytes written to this stream. |
| 148 | * @return the number of written bytes |
Gary D. Gregory | 2bd0dd4 | 2012-04-01 13:02:39 +0000 | [diff] [blame] | 149 | * @since 1.1 |
Stefan Bodewig | 2dca661 | 2010-02-18 16:10:20 +0000 | [diff] [blame] | 150 | */ |
| 151 | public long getBytesWritten() { |
| 152 | return bytesWritten; |
Christian Grobmeier | ab26943 | 2009-04-24 06:30:17 +0000 | [diff] [blame] | 153 | } |
Stefan Bodewig | a33505b | 2010-02-19 12:23:27 +0000 | [diff] [blame] | 154 | |
| 155 | /** |
| 156 | * Whether this stream is able to write the given entry. |
| 157 | * |
| 158 | * <p>Some archive formats support variants or details that are |
| 159 | * not supported (yet).</p> |
| 160 | * |
Gary D. Gregory | 6311a90 | 2013-12-20 17:41:43 +0000 | [diff] [blame] | 161 | * @param archiveEntry |
| 162 | * the entry to test |
| 163 | * @return This implementation always returns true. |
Gary D. Gregory | 2bd0dd4 | 2012-04-01 13:02:39 +0000 | [diff] [blame] | 164 | * @since 1.1 |
Stefan Bodewig | a33505b | 2010-02-19 12:23:27 +0000 | [diff] [blame] | 165 | */ |
Gary D. Gregory | 6311a90 | 2013-12-20 17:41:43 +0000 | [diff] [blame] | 166 | public boolean canWriteEntryData(ArchiveEntry archiveEntry) { |
Stefan Bodewig | a33505b | 2010-02-19 12:23:27 +0000 | [diff] [blame] | 167 | return true; |
| 168 | } |
Torsten Curdt | ca16539 | 2008-07-10 10:17:44 +0000 | [diff] [blame] | 169 | } |