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

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