001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    package org.apache.hadoop.io.compress;
020    
021    import java.io.IOException;
022    import java.io.InputStream;
023    import java.io.OutputStream;
024    
025    import org.apache.hadoop.classification.InterfaceAudience;
026    import org.apache.hadoop.classification.InterfaceStability;
027    
028    /**
029     * This class encapsulates a streaming compression/decompression pair.
030     */
031    @InterfaceAudience.Public
032    @InterfaceStability.Evolving
033    public interface CompressionCodec {
034    
035      /**
036       * Create a {@link CompressionOutputStream} that will write to the given 
037       * {@link OutputStream}.
038       * 
039       * @param out the location for the final output stream
040       * @return a stream the user can write uncompressed data to have it compressed
041       * @throws IOException
042       */
043      CompressionOutputStream createOutputStream(OutputStream out) 
044      throws IOException;
045      
046      /**
047       * Create a {@link CompressionOutputStream} that will write to the given 
048       * {@link OutputStream} with the given {@link Compressor}.
049       * 
050       * @param out the location for the final output stream
051       * @param compressor compressor to use
052       * @return a stream the user can write uncompressed data to have it compressed
053       * @throws IOException
054       */
055      CompressionOutputStream createOutputStream(OutputStream out, 
056                                                 Compressor compressor) 
057      throws IOException;
058    
059      /**
060       * Get the type of {@link Compressor} needed by this {@link CompressionCodec}.
061       * 
062       * @return the type of compressor needed by this codec.
063       */
064      Class<? extends Compressor> getCompressorType();
065      
066      /**
067       * Create a new {@link Compressor} for use by this {@link CompressionCodec}.
068       * 
069       * @return a new compressor for use by this codec
070       */
071      Compressor createCompressor();
072      
073      /**
074       * Create a {@link CompressionInputStream} that will read from the given
075       * input stream.
076       * 
077       * @param in the stream to read compressed bytes from
078       * @return a stream to read uncompressed bytes from
079       * @throws IOException
080       */
081      CompressionInputStream createInputStream(InputStream in) throws IOException;
082      
083      /**
084       * Create a {@link CompressionInputStream} that will read from the given 
085       * {@link InputStream} with the given {@link Decompressor}.
086       * 
087       * @param in the stream to read compressed bytes from
088       * @param decompressor decompressor to use
089       * @return a stream to read uncompressed bytes from
090       * @throws IOException
091       */
092      CompressionInputStream createInputStream(InputStream in, 
093                                               Decompressor decompressor) 
094      throws IOException;
095    
096    
097      /**
098       * Get the type of {@link Decompressor} needed by this {@link CompressionCodec}.
099       * 
100       * @return the type of decompressor needed by this codec.
101       */
102      Class<? extends Decompressor> getDecompressorType();
103      
104      /**
105       * Create a new {@link Decompressor} for use by this {@link CompressionCodec}.
106       * 
107       * @return a new decompressor for use by this codec
108       */
109      Decompressor createDecompressor();
110      
111      /**
112       * Get the default filename extension for this kind of compression.
113       * @return the extension including the '.'
114       */
115      String getDefaultExtension();
116    }