Review comments from Emmanuel Bourg
- Added @since tags
- Improved javadocs in several places
- Extracted ScatterStatistics class
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/compress/trunk@1654291 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java b/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java
index 4a3d407..559e7b5 100644
--- a/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java
+++ b/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java
@@ -21,6 +21,13 @@
import java.io.InputStream;
+/**
+ * Supplies input streams.
+ *
+ * Implementations are required to be thread safe.
+ *
+ * @since 1.10
+ */
public interface InputStreamSupplier {
/**
diff --git a/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java b/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java
index 9f6e845..91ccfed 100644
--- a/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java
+++ b/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java
@@ -44,6 +44,7 @@
* The client can supply an ExecutorService, but for reasons of memory model consistency,
* this will be shut down by this class prior to completion.
* </p>
+ * @since 1.10
*/
public class ParallelScatterZipCreator {
private final List<ScatterZipOutputStream> streams = synchronizedList(new ArrayList<ScatterZipOutputStream>());
@@ -85,7 +86,8 @@
};
/**
- * Create a ParallelScatterZipCreator with default threads
+ * Create a ParallelScatterZipCreator with default threads, which is set to the number of available
+ * processors, as defined by java.lang.Runtime#availableProcessors()
*/
public ParallelScatterZipCreator() {
this(Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors()));
@@ -129,8 +131,11 @@
}
/**
- * Submit a callable for compression
- * @param callable The callable to run
+ * Submit a callable for compression.
+ *
+ * @see #createCallable for details of if/when to use this.
+ *
+ * @param callable The callable to run, created by #createCallable, possibly wrapped by caller.
*/
public final void submit(Callable<Object> callable) {
futures.add(es.submit(callable));
@@ -141,18 +146,22 @@
*
* <p>This method is expected to be called from a single client thread.</p>
* <p>
- * This method is used by clients that want finer grained control over how the callable is
- * created, possibly wanting to wrap this callable in a different callable</p>
+ * Consider using #addArchiveEntry, which wraps this method and #submit. The most common use case
+ * for using #createCallable and #submit from a client is if you want to wrap the callable in something
+ * that can be prioritized by the supplied #ExecutorService, for instance to process large or slow files first.
+ * Since the creation of the #ExecutorService is handled by the client, all of this is up to the client.
*
* @param zipArchiveEntry The entry to add.
* @param source The source input stream supplier
- * @return A callable that will be used to check for errors
+ * @return A callable that should subsequently passed to #submit, possibly in a wrapped/adapted from. The
+ * value of this callable is not used, but any exceptions happening inside the compression
+ * will be propagated through the callable.
*/
public final Callable<Object> createCallable(ZipArchiveEntry zipArchiveEntry, InputStreamSupplier source) {
final int method = zipArchiveEntry.getMethod();
if (method == ZipMethod.UNKNOWN_CODE) {
- throw new IllegalArgumentException("Method must be set on the supplied zipArchiveEntry");
+ throw new IllegalArgumentException("Method must be set on zipArchiveEntry: " + zipArchiveEntry);
}
final ZipArchiveEntryRequest zipArchiveEntryRequest = createZipArchiveEntryRequest(zipArchiveEntry, source);
return new Callable<Object>() {
@@ -203,9 +212,8 @@
*
* @return A string
*/
- public String getStatisticsMessage() {
- return "Compression: " + (compressionDoneAt - startedAt) + "ms," +
- "Merging files: " + (scatterDoneAt - compressionDoneAt) + "ms";
+ public ScatterStatistics getStatisticsMessage() {
+ return new ScatterStatistics(compressionDoneAt - startedAt, scatterDoneAt - compressionDoneAt);
}
}
diff --git a/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java b/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java
index 54359dc..9583f5d 100644
--- a/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java
+++ b/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java
@@ -20,6 +20,11 @@
import java.io.IOException;
+/**
+ * Supplies ScatterGatherBackingStore instances.
+ *
+ * @since 1.10
+ */
public interface ScatterGatherBackingStoreSupplier {
/**
* Get a ScatterGatherBackingStore.
diff --git a/src/main/java/org/apache/commons/compress/archivers/zip/ScatterStatistics.java b/src/main/java/org/apache/commons/compress/archivers/zip/ScatterStatistics.java
new file mode 100644
index 0000000..3839af1
--- /dev/null
+++ b/src/main/java/org/apache/commons/compress/archivers/zip/ScatterStatistics.java
@@ -0,0 +1,56 @@
+/*
+ * 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.
+ */
+ package org.apache.commons.compress.archivers.zip;
+
+/**
+ * Provides information about a scatter compression run.
+ *
+ * @since 1.10
+ */
+public class ScatterStatistics {
+ private final long compressionElapsed;
+ private final long mergingElapsed;
+
+ ScatterStatistics(long compressionElapsed, long mergingElapsed) {
+ this.compressionElapsed = compressionElapsed;
+ this.mergingElapsed = mergingElapsed;
+ }
+
+ /**
+ * The number of milliseconds elapsed in the parallel compression phase
+ * @return The number of milliseconds elapsed
+ */
+ public long getCompressionElapsed() {
+ return compressionElapsed;
+ }
+
+ /**
+ * The number of milliseconds elapsed in merging the results of the parallel compression, the IO phase
+ * @return The number of milliseconds elapsed
+ */
+ public long getMergingElapsed() {
+ return mergingElapsed;
+ }
+
+ @Override
+ public String toString() {
+ return "compressionElapsed=" + compressionElapsed + "ms, mergingElapsed=" + mergingElapsed + "ms";
+ }
+
+}
diff --git a/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java b/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java
index 8808248..e7122b9 100644
--- a/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java
+++ b/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java
@@ -21,6 +21,8 @@
/**
* A predicate to test if a #ZipArchiveEntry matches a criteria.
* Some day this can extend java.util.function.Predicate
+ *
+ * @since 1.10
*/
public interface ZipArchiveEntryPredicate {
/**
diff --git a/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java b/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java
index 5d88372..9090500 100644
--- a/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java
+++ b/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java
@@ -21,6 +21,8 @@
/**
* A Thread-safe representation of a ZipArchiveEntry that is used to add entries to parallel archives.
+ *
+ * @since 1.10
*/
public class ZipArchiveEntryRequest {
/*