You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/03/18 12:56:09 UTC
[commons-compress] 21/35: Javadoc: Convert package.html to package-info.java
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-compress.git
commit 1f8a12412793ed250e2218ebe0620c6344c590f4
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sat Mar 18 08:46:24 2023 -0400
Javadoc: Convert package.html to package-info.java
---
.../compress/compressors/pack200/package-info.java | 61 +++++++++++++++
.../compress/compressors/pack200/package.html | 86 ----------------------
2 files changed, 61 insertions(+), 86 deletions(-)
diff --git a/src/main/java/org/apache/commons/compress/compressors/pack200/package-info.java b/src/main/java/org/apache/commons/compress/compressors/pack200/package-info.java
new file mode 100644
index 00000000..802b5111
--- /dev/null
+++ b/src/main/java/org/apache/commons/compress/compressors/pack200/package-info.java
@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * <p>
+ * Provides stream classes for compressing and decompressing streams using the Pack200 algorithm used to compress Java archives.
+ * </p>
+ * <p>
+ * The streams of this package only work on JAR archives, i.e. a {@link org.apache.commons.compress.compressors.pack200.Pack200CompressorOutputStream
+ * Pack200CompressorOutputStream} expects to be wrapped around a stream that a valid JAR archive will be written to and a
+ * {@link org.apache.commons.compress.compressors.pack200.Pack200CompressorInputStream Pack200CompressorInputStream} provides a stream to read from a JAR
+ * archive.
+ * </p>
+ * <p>
+ * JAR archives compressed with Pack200 will in general be different from the original archive when decompressed again. For details see the
+ * <a href="https://download.oracle.com/javase/1.5.0/docs/api/java/util/jar/Pack200.html">API documentation of Pack200</a>.
+ * </p>
+ * <p>
+ * The streams of this package work on non-deflated streams, i.e. archives like those created with the <code>--no-gzip</code> option of the JDK's
+ * <code>pack200</code> command line tool. If you want to work on deflated streams you must use an additional stream layer - for example by using Apache Commons
+ * Compress' gzip package.
+ * </p>
+ * <p>
+ * The Pack200 API provided by the Java class library doesn't lend itself to real stream processing. <code>Pack200CompressorInputStream</code> will uncompress
+ * its input immediately and then provide an <code>InputStream</code> to a cached result. Likewise <code>Pack200CompressorOutputStream</code> will not write
+ * anything to the given OutputStream until <code>finish</code> or <code>close</code> is called - at which point the cached output written so far gets
+ * compressed.
+ * </p>
+ * <p>
+ * Two different caching modes are available - "in memory", which is the default, and "temporary file". By default data is cached in memory but you should
+ * switch to the temporary file option if your archives are really big.
+ * </p>
+ * <p>
+ * Given there always is an intermediate result the <code>getBytesRead</code> and <code>getCount</code> methods of <code>Pack200CompressorInputStream</code> are
+ * meaningless (read from the real stream or from the intermediate result?) and always return 0.
+ * </p>
+ * <p>
+ * During development of the initial version several attempts have been made to use a real streaming API based for example on
+ * <code>Piped(In|Out)putStream</code> or explicit stream pumping like Commons Exec's <code>InputStreamPumper</code> but they have all failed because they rely
+ * on the output end to be consumed completely or else the <code>(un)pack</code> will block forever. Especially for <code>Pack200InputStream</code> it is very
+ * likely that it will be wrapped in a <code>ZipArchiveInputStream</code> which will never read the archive completely as it is not interested in the ZIP
+ * central directory data at the end of the JAR archive.
+ * </p>
+ */
+package org.apache.commons.compress.compressors.pack200;
\ No newline at end of file
diff --git a/src/main/java/org/apache/commons/compress/compressors/pack200/package.html b/src/main/java/org/apache/commons/compress/compressors/pack200/package.html
deleted file mode 100644
index 8c1cc81d..00000000
--- a/src/main/java/org/apache/commons/compress/compressors/pack200/package.html
+++ /dev/null
@@ -1,86 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-
--->
- <head>
- <title>pack200 package</title>
- </head>
- <body>
- <p>Provides stream classes for compressing and decompressing
- streams using the Pack200 algorithm used to compress Java
- archives.</p>
-
- <p>The streams of this package only work on JAR archives, i.e. a
- {@link
- org.apache.commons.compress.compressors.pack200.Pack200CompressorOutputStream
- Pack200CompressorOutputStream} expects to be wrapped around a
- stream that a valid JAR archive will be written to and a {@link
- org.apache.commons.compress.compressors.pack200.Pack200CompressorInputStream
- Pack200CompressorInputStream} provides a stream to read from a
- JAR archive.</p>
-
- <p>JAR archives compressed with Pack200 will in general be
- different from the original archive when decompressed again.
- For details see
- the <a href="https://download.oracle.com/javase/1.5.0/docs/api/java/util/jar/Pack200.html">API
- documentation of Pack200</a>.</p>
-
- <p>The streams of this package work on non-deflated streams,
- i.e. archives like those created with the <code>--no-gzip</code>
- option of the JDK's <code>pack200</code> command line tool. If
- you want to work on deflated streams you must use an additional
- stream layer - for example by using Apache Commons Compress'
- gzip package.</p>
-
- <p>The Pack200 API provided by the Java class library doesn't lend
- itself to real stream
- processing. <code>Pack200CompressorInputStream</code> will
- uncompress its input immediately and then provide
- an <code>InputStream</code> to a cached result.
- Likewise <code>Pack200CompressorOutputStream</code> will not
- write anything to the given OutputStream
- until <code>finish</code> or <code>close</code> is called - at
- which point the cached output written so far gets
- compressed.</p>
-
- <p>Two different caching modes are available - "in memory", which
- is the default, and "temporary file". By default data is cached
- in memory but you should switch to the temporary file option if
- your archives are really big.</p>
-
- <p>Given there always is an intermediate result
- the <code>getBytesRead</code> and <code>getCount</code> methods
- of <code>Pack200CompressorInputStream</code> are meaningless
- (read from the real stream or from the intermediate result?)
- and always return 0.</p>
-
- <p>During development of the initial version several attempts have
- been made to use a real streaming API based for example
- on <code>Piped(In|Out)putStream</code> or explicit stream
- pumping like Commons Exec's <code>InputStreamPumper</code> but
- they have all failed because they rely on the output end to be
- consumed completely or else the <code>(un)pack</code> will block
- forever. Especially for <code>Pack200InputStream</code> it is
- very likely that it will be wrapped in
- a <code>ZipArchiveInputStream</code> which will never read the
- archive completely as it is not interested in the ZIP central
- directory data at the end of the JAR archive.</p>
-
- </body>
-</html>