bundles/org.simantics.compressions/src/org/simantics/compressions/CompressionCodec.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2012 Association for Decentralized Information Management
   3  * in Industry THTH ry.
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.compressions;
  13
  14 import java.io.File;
  15 import java.io.FileNotFoundException;
  16 import java.io.FileOutputStream;
  17 import java.io.InputStream;
  18 import java.io.OutputStream;
  19 import java.nio.ByteBuffer;
  20
  21 /**
  22  * @author Tuukka Lehtonen
  23  */
  24 public interface CompressionCodec {
  25
  26     /**
  27      * @param inputSize size of uncompressed input data in bytes
  28      * @return maximum amount of bytes needed for the compressed data
  29      */
  30     int compressBound(int inputSize);
  31
  32     int compress(byte[] uncompressedData, int i, int length,
  33             byte[] compressedData, int j);
  34
  35     /**
  36      * Compress a block of data in the input buffer and returns the size of
  37      * compressed block. The size of input buffer is specified by length. The
  38      * minimum input buffer size is 16.
  39      *
  40      * <p>
  41      * The output buffer size must be at least what is reported y
  42      * {@link #compressBound(int)} for the input data size.
  43      *
  44      * <p>
  45      * If the input is not compressible, the return value might be larger than
  46      * length (input buffer size).
  47      *
  48      * <p>
  49      * The input buffer and the output buffer can not overlap.
  50      *
  51      * <p>
  52      * It is recommended to have both input buffers as direct or heap buffers,
  53      * not mixed. Mixing different types of buffers will hurt performance a lot.
  54      * If both buffers are direct byte buffers and native decompression is
  55      * available, it will be employed.
  56      */
  57     int compressBuffer(ByteBuffer input, int inputOffset, int length,
  58             ByteBuffer output, int outputOffset);
  59
  60     byte[] decompress(byte[] compressedData, int i, int uncompressedLength);
  61
  62     /**
  63      * Decompress a block of compressed data and returns the size of the
  64      * decompressed block. If error occurs, e.g. the compressed data is
  65      * corrupted or the output buffer is not large enough, then 0 (zero) will be
  66      * returned instead.
  67      *
  68      * <p>
  69      * The input buffer and the output buffer can not overlap.
  70      *
  71      * <p>
  72      * Decompression is memory safe and guaranteed not to write the output
  73      * buffer more than what is specified in maxout.
  74      *
  75      * <p>
  76      * It is recommended to have both input buffers as direct or heap buffers,
  77      * not mixed. Mixing different types of buffers will hurt performance a lot.
  78      * If both buffers are direct byte buffers and native decompression is
  79      * available, it will be employed.
  80      */
  81     int decompressBuffer(ByteBuffer input, int inputOffset, int length,
  82             ByteBuffer output, int outputOffset, int maxout);
  83
  84     /**
  85      * @param file
  86      *            the compressed file to read
  87      * @return input stream that decompresses its output using the codec's
  88      *         algorithm
  89      * @throws FileNotFoundException
  90      *             see {@link FileOutputStream#FileOutputStream(File)} for when
  91      *             this is thrown
  92      */
  93     InputStream read(File file) throws FileNotFoundException;
  94
  95     /**
  96      * @param file
  97      *            the compressed file to write
  98      * @return output stream that compresses its input using the codec's
  99      *         algorithm
 100      * @throws FileNotFoundException
 101      *             see {@link FileOutputStream#FileOutputStream(File)} for when
 102      *             this is thrown
 103      */
 104     OutputStream write(File file) throws FileNotFoundException;
 105
 106     String getId();
 107
 108 }