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

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