1 /*******************************************************************************
2 * Copyright (c) 2007, 2010 Association for Decentralized Information Management
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
10 * VTT Technical Research Centre of Finland - initial API and implementation
11 *******************************************************************************/
12 package org.simantics.db;
14 import org.simantics.db.exception.DatabaseException;
15 import org.simantics.db.exception.ExternalValueException;
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.
22 * @author Kalle Kondelin
24 public interface ExternalValueSupport {
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.
29 * @param graph to ensure that caller has write transaction.
30 * @param resource which value is to be removed.
31 * @throws DatabaseException
33 void removeValue(WriteGraph graph, Resource resource)
34 throws DatabaseException;
36 * Write some or all bytes of an external value.
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
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
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
56 * @param bytes to write. Must have at least length bytes.
57 * @throws DatabaseException
59 void writeValue(WriteGraph graph, Resource resource, long offset, int length, byte[] bytes)
60 throws DatabaseException;
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.
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).
71 // void moveValue(WriteGraph graph, Resource resource)
72 // throws DatabaseException;
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.
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.
85 // void commitAndContinue(WriteGraph graph, WriteTraits wtraits, Resource resource)
86 // throws DatabaseException;
88 * Read some or all bytes of an external value.
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
97 byte[] readValue(ReadGraph graph, Resource resource, long offset, int length)
98 throws DatabaseException;
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.
106 long getValueSize(ReadGraph graph, Resource resource)
107 throws DatabaseException, ExternalValueException;
110 * Wait until there is less than limit requests in outgoing request queue.
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
116 int wait4RequestsLess(int limit)
117 throws DatabaseException;