bundles/org.simantics.databoard/src/org/simantics/databoard/util/binary/RandomAccessBinary.java

   1 /*******************************************************************************
   2  * Copyright (c) 2010, 2016 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  *     Semantum Oy - Implement java.io.Closeable
  12  *******************************************************************************/
  13 package org.simantics.databoard.util.binary;
  14
  15 import java.io.Closeable;
  16 import java.io.IOException;
  17
  18 import org.simantics.databoard.file.RandomAccessBinaryList;
  19
  20 /**
  21  * Random access binary is a interface to access a binary object (BLOB).
  22  * Binary object is random accessible and has a length.
  23  * It can be read and written, enlarged and shrunk at any position.
  24  * <p>
  25  * There is a pointer which moves on every read and write operation. It can
  26  * moved with {@link #position()}. If bytes are written and the pointer is
  27  * moved outside the blob or moves while writing, the blob is enlarged.
  28  *
  29  * @see Blob Cascading implementation
  30  * @see BinaryFile RandomAccessFile implementation
  31  * @see RandomAccessBinaryList java.util.List implementation
  32  * @author Toni Kalajainen
  33  */
  34 public interface RandomAccessBinary extends Closeable, BinaryWriteable, BinaryReadable {
  35
  36         /**
  37          * Flush write buffer
  38          *
  39          * @throws IOException
  40          */
  41         void flush() throws IOException;
  42
  43         /**
  44          * Reset internal cache. Before reseting unwritten changes are flushed to
  45          * disc.
  46          */
  47         void reset() throws IOException;
  48
  49         enum ByteSide { Left, Neither, Right }
  50
  51         /**
  52          * Remove bytes from the position of the current pointer. If the pointer is
  53          * outside the blob, an error is thrown.
  54          *
  55          * @param bytes
  56          * @param side
  57          * @throws IOException
  58          */
  59         void removeBytes(long bytes, ByteSide side) throws IOException;
  60
  61         /**
  62          * Insert bytes at current pointer. If the pointer is outside the size of
  63          * the blob, the blob is enlarged to fit the insertion.
  64          *
  65          * The operation does not move pointer.
  66          *
  67          * @param bytes
  68          * @param side
  69          * @throws IOException
  70          */
  71         void insertBytes(long bytes, ByteSide side) throws IOException;
  72
  73         /**
  74          * Set length of the binary object.
  75          *
  76          * @param newLength
  77          * @throws IOException
  78          */
  79         void setLength(long newLength) throws IOException;
  80
  81         /**
  82          * Get the length of the binary object.
  83          *
  84          * @return the length
  85          * @throws IOException
  86          */
  87         long length() throws IOException;
  88
  89         /**
  90          * Flush and close the blob.
  91          */
  92         void close() throws IOException;
  93
  94         /**
  95          * Check if binary is open.
  96          *
  97          * @return true if file is open
  98          */
  99         boolean isOpen();
 100
 101         /**
 102          * Set new cursor position.
 103          *
 104          * The position can be set outside the binary object.
 105          *
 106          * @param newPosition
 107          */
 108         void position(long newPosition) throws IOException;
 109
 110         /**
 111          * Get the position of the cursor
 112          *
 113          * @return cursor
 114          */
 115         long position() throws IOException;
 116
 117 }
 118