bundles/org.simantics.db/src/org/simantics/db/ExternalValueSupport.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2010 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.db;
  13
  14 import org.simantics.db.exception.DatabaseException;
  15 import org.simantics.db.exception.ExternalValueException;
  16
  17 /**
  18  * This interface is for accessing external values of resources. External
  19  * values are values of resources which are stored outside the cluster of the
  20  * resource. These values support partial read and write.
  21  *
  22  * @author Kalle Kondelin
  23  */
  24 public interface ExternalValueSupport {
  25     /**
  26      * Removes the value from the resource. Also truncates the value to zero
  27      * length so that if the value is created again it does not have any content.
  28      *
  29      * @param graph to ensure that caller has write transaction.
  30      * @param resource which value is to be removed.
  31      * @throws DatabaseException
  32      */
  33     void removeValue(WriteGraph graph, Resource resource)
  34     throws DatabaseException;
  35     /**
  36      * Write some or all bytes of an external value.
  37      *
  38      * IMPLEMENTATION NOTE:
  39      * The current implementation for the value is a file and every transaction
  40      * you write the value the whole file is copied and then the modification
  41      * is applied.
  42      * If you write internal value or create external value you must write the
  43      * whole value because the value is not initialized.
  44      * If you write a value that is so big that server can't hold it in memory
  45      * during the commit you must split it in parts by using commitAndContinue
  46      * method.
  47      *
  48      * @param graph to ensure that caller has write transaction.
  49      * @param resource which value is modified.
  50      * @param offset from start of the value. Must be within [0, MAX_VALUE_SIZE).
  51      * MAX_VALUE_SIZE = (1<<58)-2. (1<<58)-1 reserved for special move message.
  52      * @param length of the modified segment i.e. number of bytes to write.
  53      * Must be positive. If zero then the value length is truncated to offset.
  54      * If offset + length is greater then MAX_VALUE_SIZE then the behavior is
  55      * undefined.
  56      * @param bytes to write. Must have at least length bytes.
  57      * @throws DatabaseException
  58      */
  59     void writeValue(WriteGraph graph, Resource resource, long offset, int length, byte[] bytes)
  60     throws DatabaseException;
  61     /**
  62      * If there is an old value moves it to current change set. This means that
  63      * old value is lost but space is saved. Must be called before first
  64      * writeValue call for given change set to have any effect.
  65      *
  66      * @param graph to ensure that caller has write transaction.
  67      * @param resource which value is to be modified i.e. the same value as
  68      * given to following writeValue(s).
  69      */
  70 // This breaks undo.
  71 //    void moveValue(WriteGraph graph, Resource resource)
  72 //    throws DatabaseException;
  73     /**
  74      * Sends commit message to server but does not end transaction. This
  75      * enables server to release memory used by writeValue requests.
  76      * Waits until most of the pending requests has been sent so that the
  77      * memory used by the pending requests does not grow unreasonably large.
  78      *
  79      * @param graph to ensure that caller has write transaction.
  80      * @param wtraits required by commit message. Usually the write request
  81      * which is calling this method.
  82      * @param resource which value is modified i.e. the same value as given to writeValue.
  83      */
  84 // This breaks undo.
  85 //    void commitAndContinue(WriteGraph graph, WriteTraits wtraits, Resource resource)
  86 //    throws DatabaseException;
  87     /**
  88      * Read some or all bytes of an external value.
  89      *
  90      * @param graph to ensure that caller has read transaction.
  91      * @param resource which value is to be read.
  92      * @param offset from start of the value. Must be within [0, valueSize).
  93      * @param length of the segment to read. Offset + length must be within [0, valueSize].
  94      * @return the bytes of the segment that was asked.
  95      * @throws DatabaseException
  96      */
  97     byte[] readValue(ReadGraph graph, Resource resource, long offset, int length)
  98     throws DatabaseException;
  99     /**
 100      * @param graph to ensure that caller has read transaction.
 101      * @param resource which value is to be read.
 102      * @return size of the value.
 103      * @throws DatabaseException
 104      * @throws ExternalValueException if the value is not external.
 105      */
 106     long getValueSize(ReadGraph graph, Resource resource)
 107     throws DatabaseException, ExternalValueException;
 108
 109     /**
 110      * Wait until there is less than limit requests in outgoing request queue.
 111      *
 112      * @param limit value for requests in request queue. Must be greater than zero.
 113      * @return Number of requests left in request queue.
 114      * @throws DatabaseException
 115      */
 116     int wait4RequestsLess(int limit)
 117     throws DatabaseException;
 118 }