]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.db/src/org/simantics/db/ExternalValueSupport.java
Merge commit '3b5069d' into develop
[simantics/platform.git] / 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