commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject svn commit: r1559094 - in /commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers: ArchiveFormat.java spi/AbstractArchiveFormat.java
Date Fri, 17 Jan 2014 12:54:41 GMT
Author: bodewig
Date: Fri Jan 17 12:54:41 2014
New Revision: 1559094

URL: http://svn.apache.org/r1559094
Log:
first cut a self-describing archive formats

Added:
    commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/ArchiveFormat.java
  (with props)
    commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/spi/AbstractArchiveFormat.java
  (with props)

Added: commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/ArchiveFormat.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/ArchiveFormat.java?rev=1559094&view=auto
==============================================================================
--- commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/ArchiveFormat.java
(added)
+++ commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/ArchiveFormat.java
Fri Jan 17 12:54:41 2014
@@ -0,0 +1,135 @@
+/*
+ * 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.compress2.archivers;
+
+import java.nio.ByteBuffer;
+import java.nio.channels.Channel;
+import java.nio.charset.Charset;
+import java.io.File;
+import java.io.IOException;
+
+/**
+ * Describes a given archive format and works as factory and content-probe at the same time.
+ * @Immutable
+ */
+public interface ArchiveFormat {
+    /**
+     * The name by which this format is known.
+     * @return the name by which this format is known
+     */
+    String getName();
+
+    /**
+     * Does the format support writing?
+     * @return whether writing is supported
+     */
+    boolean supportsWriting();
+    /**
+     * Does the format support random access reading?
+     * @return whether random access reading is supported
+     */
+    boolean supportsRandomAccessInput();
+    /**
+     * Does the format support writing to arbitrary non-seekable channels?
+     * @return whether writing to arbitrary non-seekable channels is supported
+     */
+    boolean supportsWritingToChannels();
+    /**
+     * Does the format support reading from arbitrary non-seekable channels?
+     * @return whether writing to arbitrary non-seekable channels is supported
+     */
+    boolean supportsReadingFromChannels();
+
+    /**
+     * Does the format support content-based detection?
+     * @return whether the format supports content-based detection.
+     */
+    boolean supportsAutoDetection();
+    /**
+     * If this format supports content-based detection, how many bytes does it need to read
to know a channel is
+     * readable by this format?
+     * @return the minimal number of bytes needed
+     * @throws UnsupportedOperationException if this format doesn't support content based
detection.
+     */
+    int getNumberOfBytesRequiredForAutodetection() throws UnsupportedOperationException;
+    /**
+     * Lists formats that must not be consulted before this format during content-based detection.
+     *
+     * <p>For example JAR would return ZIP here so it first has a chance to claim the
archive for itself.</p>
+     *
+     * @return the names of the formats (as returned by {@link #getName}) that must not be
consulted before this format during content-based detection.
+     */
+    Iterable<String> formatsToConsultLater();
+    /**
+     * Verifies the given input is readable by this format.
+     * @param probe a buffer holding at least {@link #getNumberOfBytesRequiredForAutodetection}
bytes
+     * @return whether the input is readable by this format
+     * @throws UnsupportedOperationException if this format doesn't support content based
detection.
+     */
+    boolean matches(ByteBuffer probe) throws UnsupportedOperationException;
+
+    /**
+     * Reads an archive assuming the given charset for entry names.
+     * @param channel the channel to read from
+     * @param charset the charset used for encoding the entry names.
+     * @throws IOException
+     * @throws UnsupportedOperationException if this format cannot read from non-seekable
channels.
+     */
+    ArchiveInput readFrom(Channel channel, Charset charset) throws IOException, UnsupportedOperationException;
+    /**
+     * Reads an archive assuming the given charset for entry names.
+     * @param file the file to read from
+     * @param charset the charset used for encoding the entry names.
+     * @throws IOException
+     */
+    // TODO go for SeekableByteChannel rather than File when embracing Java7?
+    // TODO use Path rather than File?
+    ArchiveInput readFrom(File file, Charset charset) throws IOException;
+    /**
+     * Provides random access to an archive assuming the given charset for entry names.
+     * @param file the file to read from
+     * @param charset the charset used for encoding the entry names.
+     * @throws IOException
+     * @throws UnsupportedOperationException if this format doesn't support random access
+     */
+    // TODO go for SeekableByteChannel rather than File when embracing Java7?
+    // TODO use Path rather than File?
+    RandomAccessArchiveInput readWithRandomAccessFrom(File file, Charset charset)
+        throws IOException, UnsupportedOperationException;
+
+    /**
+     * Writes an archive using the given charset for entry names.
+     * @param channel the channel to write to
+     * @param charset the charset to use for encoding the entry names.
+     * @throws IOException
+     * @throws UnsupportedOperationException if this format cannot write to non-seekable
channels or doesn't support
+     * writing at all.
+     */
+    ArchiveOutput writeTo(Channel channel, Charset charset) throws IOException, UnsupportedOperationException;
+    /**
+     * Writes an archive using the given charset for entry names.
+     * @param file the file to write to
+     * @param charset the charset to use for encoding the entry names.
+     * @throws IOException
+     * @throws UnsupportedOperationException if this format doesn't support writing
+     */
+    // TODO go for SeekableByteChannel rather than File when embracing Java7?
+    // TODO use Path rather than File?
+    ArchiveOutput writeTo(File file, Charset charset) throws IOException, UnsupportedOperationException;
+}

Propchange: commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/ArchiveFormat.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/spi/AbstractArchiveFormat.java
URL: http://svn.apache.org/viewvc/commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/spi/AbstractArchiveFormat.java?rev=1559094&view=auto
==============================================================================
--- commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/spi/AbstractArchiveFormat.java
(added)
+++ commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/spi/AbstractArchiveFormat.java
Fri Jan 17 12:54:41 2014
@@ -0,0 +1,146 @@
+/*
+ * 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.compress2.archivers.spi;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.nio.channels.Channel;
+//import java.nio.channels.FileChannel;
+import java.nio.charset.Charset;
+import java.util.Collections;
+import org.apache.commons.compress2.archivers.ArchiveFormat;
+import org.apache.commons.compress2.archivers.ArchiveInput;
+import org.apache.commons.compress2.archivers.ArchiveOutput;
+import org.apache.commons.compress2.archivers.RandomAccessArchiveInput;
+
+/**
+ * Base class implementations may use.
+ * @Immutable
+ */
+public abstract class AbstractArchiveFormat implements ArchiveFormat {
+
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always returns false.</p>
+     */
+    @Override
+    public boolean supportsWriting() { return false; }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always returns false.</p>
+     */
+    @Override
+    public boolean supportsRandomAccessInput() { return false; }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always returns false.</p>
+     */
+    @Override
+    public boolean supportsWritingToChannels() { return false; }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always returns false.</p>
+     */
+    @Override
+    public boolean supportsReadingFromChannels() { return false; }
+
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always returns false.</p>
+     */
+    @Override
+    public boolean supportsAutoDetection() { return false; }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always throws an UnsupportedOperationException.</p>
+     */
+    @Override
+    public int getNumberOfBytesRequiredForAutodetection() throws UnsupportedOperationException
{
+        throw new UnsupportedOperationException("this format doesn't support content-based
detection");
+    }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always returns an empty collection.</p>
+     */
+    @Override
+    public Iterable<String> formatsToConsultLater() {
+        return Collections.emptyList();
+    }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always throws an UnsupportedOperationException.</p>
+     */
+    @Override
+    public boolean matches(ByteBuffer probe) throws UnsupportedOperationException {
+        throw new UnsupportedOperationException("this format doesn't support content-based
detection");
+    }
+
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always throws an UnsupportedOperationException.</p>
+     */
+    @Override
+    public ArchiveInput readFrom(Channel channel, Charset charset) throws IOException, UnsupportedOperationException
{
+        throw new UnsupportedOperationException("this format cannot read from non-seekable
channels");
+    }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation delegates to {@link #readWithRandomAccessFrom} if random
access is supported or {@link
+     * #readFrom(File, Charset)} otherwise.</p>
+     */
+    @Override
+    public ArchiveInput readFrom(File file, Charset charset) throws IOException {
+        if (supportsRandomAccessInput()) {
+            return readWithRandomAccessFrom(file, charset);
+        }
+
+        // TODO use FileChannel.open in Java7
+        return readFrom(new FileInputStream(file).getChannel(), charset);
+    }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always throws an UnsupportedOperationException.</p>
+     */
+    @Override
+    public RandomAccessArchiveInput readWithRandomAccessFrom(File file, Charset charset)
+        throws IOException, UnsupportedOperationException {
+        throw new UnsupportedOperationException("this format cannot doesn't support random
access");
+    }
+
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always throws an UnsupportedOperationException.</p>
+     */
+    @Override
+    public ArchiveOutput writeTo(Channel channel, Charset charset) throws IOException, UnsupportedOperationException
{
+        throw new UnsupportedOperationException("this format is read-only");
+    }
+    /**
+     * {@inheritDoc}
+     * <p>This implementation always delegates to {@link #writeTo(Channel, Charset)}.</p>
+     */
+    @Override
+    public ArchiveOutput writeTo(File file, Charset charset) throws IOException, UnsupportedOperationException
{
+        // TODO use FileChannel.open in Java7
+        return writeTo(new FileOutputStream(file).getChannel(), charset);
+    }
+}

Propchange: commons/proper/compress/branches/compress-2.0/src/main/java/org/apache/commons/compress2/archivers/spi/AbstractArchiveFormat.java
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message