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

   1 /*******************************************************************************
   2  *  Copyright (c) 2010 Association for Decentralized Information Management in
   3  *  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.databoard.accessor.file;
  13
  14 import java.io.File;
  15
  16 import org.simantics.databoard.accessor.Accessor;
  17 import org.simantics.databoard.accessor.CloseableAccessor;
  18 import org.simantics.databoard.accessor.binary.BinaryObject;
  19 import org.simantics.databoard.accessor.error.AccessorException;
  20 import org.simantics.databoard.binding.Binding;
  21
  22 /**
  23  * File accessor is an interface for data that is located in a file in byte format.
  24  * There are two ways of writing to the files.
  25  *   A) Using the writing methods of Accessor+subtypes, eg. setValue, putValue, ...
  26  *      They guarantee the value is flushed to the file upon return
  27  *   B) Using the write methods of FileAccessor+subtypes, eg. setValueNoflush, putValueNoflush ...
  28  *      They do not guarantee flush upon return. Explicit flush() call is required.
  29  *      The value resides in memory cache and are available for reading event before flushing.
  30  *
  31  * see FileAccessorExample
  32  * @see BinaryObject File/Memory Byte[] implementation
  33  * @see FileArrayAccessor
  34  * @see FileBooleanAccessor
  35  * @see FileByteAccessor
  36  * @see FileDoubleAccessor
  37  * @see FileFloatAccessor
  38  * @see FileIntegerAccessor
  39  * @see FileLongAccessor
  40  * @see FileMapAccessor
  41  * @see FileOptionalAccessor
  42  * @see FileRecordAccessor
  43  * @see FileStringAccessor
  44  * @see FileUnionAccessor
  45  * @see FileVariantAccessor
  46  * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
  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
  77         /**
  78          * Reset internal buffer. If there unwritten changes, they are flushed.
  79          *
  80          * @throws AccessorException
  81          */
  82         void reset() throws AccessorException;
  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;
  94
  95
  96
  97 }
  98