Author: krosenvold
Date: Fri Jan 23 18:22:05 2015
New Revision: 1654291
URL: http://svn.apache.org/r1654291
Log:
Review comments from Emmanuel Bourg
- Added @since tags
- Improved javadocs in several places
- Extracted ScatterStatistics class
Added:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterStatistics.java
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java?rev=1654291&r1=1654290&r2=1654291&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/InputStreamSupplier.java
Fri Jan 23 18:22:05 2015
@@ -21,6 +21,13 @@ package org.apache.commons.compress.arch
import java.io.InputStream;
+/**
+ * Supplies input streams.
+ *
+ * Implementations are required to be thread safe.
+ *
+ * @since 1.10
+ */
public interface InputStreamSupplier {
/**
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java?rev=1654291&r1=1654290&r2=1654291&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ParallelScatterZipCreator.java
Fri Jan 23 18:22:05 2015
@@ -44,6 +44,7 @@ import static org.apache.commons.compres
* 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 @@ public class ParallelScatterZipCreator {
};
/**
- * 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 @@ public class ParallelScatterZipCreator {
}
/**
- * 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 @@ public class ParallelScatterZipCreator {
*
* <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 @@ public class ParallelScatterZipCreator {
*
* @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);
}
}
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java?rev=1654291&r1=1654290&r2=1654291&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterGatherBackingStoreSupplier.java
Fri Jan 23 18:22:05 2015
@@ -20,6 +20,11 @@ package org.apache.commons.compress.arch
import java.io.IOException;
+/**
+ * Supplies ScatterGatherBackingStore instances.
+ *
+ * @since 1.10
+ */
public interface ScatterGatherBackingStoreSupplier {
/**
* Get a ScatterGatherBackingStore.
Added:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterStatistics.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterStatistics.java?rev=1654291&view=auto
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterStatistics.java
(added)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ScatterStatistics.java
Fri Jan 23 18:22:05 2015
@@ -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";
+ }
+
+}
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java?rev=1654291&r1=1654290&r2=1654291&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryPredicate.java
Fri Jan 23 18:22:05 2015
@@ -21,6 +21,8 @@ package org.apache.commons.compress.arch
/**
* 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 {
/**
Modified:
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java
URL:
http://svn.apache.org/viewvc/commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java?rev=1654291&r1=1654290&r2=1654291&view=diff
==============================================================================
---
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java
(original)
+++
commons/proper/compress/trunk/src/main/java/org/apache/commons/compress/archivers/zip/ZipArchiveEntryRequest.java
Fri Jan 23 18:22:05 2015
@@ -21,6 +21,8 @@ import java.io.InputStream;
/**
* A Thread-safe representation of a ZipArchiveEntry that is used to add
entries to parallel archives.
+ *
+ * @since 1.10
*/
public class ZipArchiveEntryRequest {
/*
