--- /dev/null
+/*******************************************************************************\r
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
+ * in Industry THTH ry.\r
+ * All rights reserved. This program and the accompanying materials\r
+ * are made available under the terms of the Eclipse Public License v1.0\r
+ * which accompanies this distribution, and is available at\r
+ * http://www.eclipse.org/legal/epl-v10.html\r
+ *\r
+ * Contributors:\r
+ * VTT Technical Research Centre of Finland - initial API and implementation\r
+ *******************************************************************************/\r
+package org.simantics.db;\r
+\r
+import org.simantics.db.exception.DatabaseException;\r
+import org.simantics.db.exception.ExternalValueException;\r
+\r
+/**\r
+ * This interface is for accessing external values of resources. External\r
+ * values are values of resources which are stored outside the cluster of the\r
+ * resource. These values support partial read and write.\r
+ *\r
+ * @author Kalle Kondelin\r
+ */\r
+public interface ExternalValueSupport {\r
+ /**\r
+ * Removes the value from the resource. Also truncates the value to zero\r
+ * length so that if the value is created again it does not have any content.\r
+ *\r
+ * @param graph to ensure that caller has write transaction.\r
+ * @param resource which value is to be removed.\r
+ * @throws DatabaseException\r
+ */\r
+ void removeValue(WriteGraph graph, Resource resource)\r
+ throws DatabaseException;\r
+ /**\r
+ * Write some or all bytes of an external value.\r
+ *\r
+ * IMPLEMENTATION NOTE:\r
+ * The current implementation for the value is a file and every transaction\r
+ * you write the value the whole file is copied and then the modification\r
+ * is applied.\r
+ * If you write internal value or create external value you must write the\r
+ * whole value because the value is not initialized.\r
+ * If you write a value that is so big that server can't hold it in memory\r
+ * during the commit you must split it in parts by using commitAndContinue\r
+ * method.\r
+ *\r
+ * @param graph to ensure that caller has write transaction.\r
+ * @param resource which value is modified.\r
+ * @param offset from start of the value. Must be within [0, MAX_VALUE_SIZE).\r
+ * MAX_VALUE_SIZE = (1<<58)-2. (1<<58)-1 reserved for special move message.\r
+ * @param length of the modified segment i.e. number of bytes to write.\r
+ * Must be positive. If zero then the value length is truncated to offset.\r
+ * If offset + length is greater then MAX_VALUE_SIZE then the behavior is\r
+ * undefined.\r
+ * @param bytes to write. Must have at least length bytes.\r
+ * @throws DatabaseException\r
+ */\r
+ void writeValue(WriteGraph graph, Resource resource, long offset, int length, byte[] bytes)\r
+ throws DatabaseException;\r
+ /**\r
+ * If there is an old value moves it to current change set. This means that\r
+ * old value is lost but space is saved. Must be called before first\r
+ * writeValue call for given change set to have any effect.\r
+ *\r
+ * @param graph to ensure that caller has write transaction.\r
+ * @param resource which value is to be modified i.e. the same value as\r
+ * given to following writeValue(s).\r
+ */\r
+// This breaks undo.\r
+// void moveValue(WriteGraph graph, Resource resource)\r
+// throws DatabaseException;\r
+ /**\r
+ * Sends commit message to server but does not end transaction. This\r
+ * enables server to release memory used by writeValue requests.\r
+ * Waits until most of the pending requests has been sent so that the\r
+ * memory used by the pending requests does not grow unreasonably large.\r
+ *\r
+ * @param graph to ensure that caller has write transaction.\r
+ * @param wtraits required by commit message. Usually the write request\r
+ * which is calling this method.\r
+ * @param resource which value is modified i.e. the same value as given to writeValue.\r
+ */\r
+// This breaks undo.\r
+// void commitAndContinue(WriteGraph graph, WriteTraits wtraits, Resource resource)\r
+// throws DatabaseException;\r
+ /**\r
+ * Read some or all bytes of an external value.\r
+ *\r
+ * @param graph to ensure that caller has read transaction.\r
+ * @param resource which value is to be read.\r
+ * @param offset from start of the value. Must be within [0, valueSize).\r
+ * @param length of the segment to read. Offset + length must be within [0, valueSize].\r
+ * @return the bytes of the segment that was asked.\r
+ * @throws DatabaseException\r
+ */\r
+ byte[] readValue(ReadGraph graph, Resource resource, long offset, int length)\r
+ throws DatabaseException;\r
+ /**\r
+ * @param graph to ensure that caller has read transaction.\r
+ * @param resource which value is to be read.\r
+ * @return size of the value.\r
+ * @throws DatabaseException\r
+ * @throws ExternalValueException if the value is not external.\r
+ */\r
+ long getValueSize(ReadGraph graph, Resource resource)\r
+ throws DatabaseException, ExternalValueException;\r
+\r
+ /**\r
+ * Wait until there is less than limit requests in outgoing request queue.\r
+ *\r
+ * @param limit value for requests in request queue. Must be greater than zero.\r
+ * @return Number of requests left in request queue.\r
+ * @throws DatabaseException\r
+ */\r
+ int wait4RequestsLess(int limit)\r
+ throws DatabaseException;\r
+}\r
Code Review / simantics / platform.git / blobdiff