bundles/org.simantics.databoard/src/org/simantics/databoard/accessor/file/FileAccessor.java

   1 /*******************************************************************************\r
   2  *  Copyright (c) 2010 Association for Decentralized Information Management in\r
   3  *  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.databoard.accessor.file;
  13
  14 import java.io.File;\r
  15 \r
  16 import org.simantics.databoard.accessor.Accessor;\r
  17 import org.simantics.databoard.accessor.CloseableAccessor;\r
  18 import org.simantics.databoard.accessor.binary.BinaryObject;\r
  19 import org.simantics.databoard.accessor.error.AccessorException;\r
  20 import org.simantics.databoard.binding.Binding;\r
  21 \r
  22 /**\r
  23  * File accessor is an interface for data that is located in a file in byte format.\r
  24  * There are two ways of writing to the files. \r
  25  *   A) Using the writing methods of Accessor+subtypes, eg. setValue, putValue, ...\r
  26  *      They guarantee the value is flushed to the file upon return\r
  27  *   B) Using the write methods of FileAccessor+subtypes, eg. setValueNoflush, putValueNoflush ...\r
  28  *      They do not guarantee flush upon return. Explicit flush() call is required.\r
  29  *      The value resides in memory cache and are available for reading event before flushing.\r
  30  *\r
  31  * see FileAccessorExample\r
  32  * @see BinaryObject File/Memory Byte[] implementation\r
  33  * @see FileArrayAccessor\r
  34  * @see FileBooleanAccessor\r
  35  * @see FileByteAccessor\r
  36  * @see FileDoubleAccessor\r
  37  * @see FileFloatAccessor\r
  38  * @see FileIntegerAccessor\r
  39  * @see FileLongAccessor\r
  40  * @see FileMapAccessor\r
  41  * @see FileOptionalAccessor\r
  42  * @see FileRecordAccessor\r
  43  * @see FileStringAccessor\r
  44  * @see FileUnionAccessor\r
  45  * @see FileVariantAccessor\r
  46  * @author Toni Kalajainen <toni.kalajainen@vtt.fi>\r
  47  */
  48 public interface FileAccessor extends Accessor, CloseableAccessor {
  49
  50         /**
  51          * Get the file
  52          *
  53          * @return file
  54          */
  55         File file();
  56
  57         /**
  58          * Close the file. It is allowed to call this method more than once.
  59          *
  60          * @throws AccessorException
  61          */
  62         void close() throws AccessorException;
  63
  64         /**
  65          * Flush the internal write buffer to the disc. This is needed if
  66          * setXXNoFlush() methods are used.
  67          * <p>
  68          *
  69          * Note, all the write methods of {@link Accessor} and its sub-interfaces
  70          * guarantee Durability. They flush the value immediately and do not require
  71          * separate {@link #flush()}.
  72          *
  73          * @throws AccessorException
  74          */
  75         void flush() throws AccessorException;
  76         \r
  77         /**\r
  78          * Reset internal buffer. If there unwritten changes, they are flushed.\r
  79          * \r
  80          * @throws AccessorException\r
  81          */\r
  82         void reset() throws AccessorException;\r
  83
  84         /**
  85          * Write a value to the file without flushing the writebuffer yet.
  86          * The write doesn't become durable until the value is flushed
  87          * with {@link #flush()}.
  88          *
  89          * @param binding
  90          * @param newValue
  91          * @throws AccessorException
  92          */
  93         void setValueNoflush(Binding binding, Object newValue) throws AccessorException;\r
  94         \r
  95
  96
  97 }
  98