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
