001: /*
002:
003: This software is OSI Certified Open Source Software.
004: OSI Certified is a certification mark of the Open Source Initiative.
005:
006: The license (Mozilla version 1.0) can be read at the MMBase site.
007: See http://www.MMBase.org/license
008:
009: */
010: package org.mmbase.storage;
011:
012: import org.mmbase.module.core.*;
013: import org.mmbase.core.CoreField;
014: import java.io.InputStream;
015:
016: /**
017: * The StorageManager interface defines how to access a storage device.
018: * It contains methods that can be used to query the storage, insert, update, or remove objects,
019: * or to change object definitions (adding fields, etc.).
020: *
021: * @author Pierre van Rooden
022: * @since MMBase-1.7
023: * @version $Id: StorageManager.java,v 1.7 2005/10/02 16:16:43 michiel Exp $
024: */
025: public interface StorageManager {
026:
027: /**
028: * Returns the version of this factory implementation.
029: * The factory uses this number to verify whether it can handle storage configuration files
030: * that list version requirements.
031: * @return the version as an integer
032: */
033: public double getVersion();
034:
035: /**
036: * Initializes the manager.
037: * Called by a StorageManagerFactory when instantiating the manager with the getStorageManager() method.
038: * @param factory the StorageManagerFactory instance that created this storage manager.
039: * @throws StorageConfigurationException if the initialization failed
040: */
041: public void init(StorageManagerFactory factory)
042: throws StorageException;
043:
044: /**
045: * Starts a transaction on this StorageManager instance.
046: * All commands passed to the instance will be treated as being in this transaction.
047: * If transactions are not supported by the storage, no actual storage transaction is started, but the code continues as if it has.
048: * @throws StorageException if the transaction could not be created
049: */
050: public void beginTransaction() throws StorageException;
051:
052: /**
053: * Closes any transaction that was started and commits all changes.
054: * If transactions are not supported by the storage, nothing really happens (as changes are allready committed), but the code continues as if it has.
055: * @throws StorageException if a transaction is not currently active, or an error occurred while committing
056: */
057: public void commit() throws StorageException;
058:
059: /**
060: * Cancels any transaction that was started and rollback changes if possible.
061: * If transactions are not supported by the storage, nothing really happens (as changes are allready committed),
062: * but the code continues as if it has (through in that case it will return false).
063: * @return <code>true</code> if changes were rolled back, <code>false</code> if the transaction was
064: * canceled but the storage does not support rollback
065: * @throws StorageException if a transaction is not currently active, or an error occurred during rollback
066: */
067: public boolean rollback() throws StorageException;
068:
069: /**
070: * Gives an unique number for a new node, to be inserted in the storage.
071: * This method should work with multiple mmbases
072: * @return unique number
073: */
074: public int createKey() throws StorageException;
075:
076: /**
077: * Retrieve a large text for a specified object field.
078: * Implement this method to allow for optimization of storing and retrieving large texts.
079: * @param node the node to retrieve the text from
080: * @param field the Type of the field to retrieve
081: * @return the retrieved text
082: * @throws StorageException if an error occurred while retrieving the text value
083: */
084: public String getStringValue(MMObjectNode node, CoreField field)
085: throws StorageException;
086:
087: /**
088: * Retrieve a large binary object (byte array) for a specified object field.
089: * Implement this method to allow for optimization of storing and retrieving binary objects.
090: * @param node the node to retrieve the byte array from
091: * @param field the CoreField of the field to retrieve
092: * @return the retrieved byte array
093: * @throws StorageException if an error occurred while retrieving the binary value
094: */
095: public byte[] getBinaryValue(MMObjectNode node, CoreField field)
096: throws StorageException;
097:
098: /**
099: * @since MMBase-1.8
100: */
101: public InputStream getInputStreamValue(MMObjectNode node,
102: CoreField field) throws StorageException;
103:
104: /**
105: * This method creates a new object in the storage, and registers the change.
106: * Only fields with states of DBSTATE_PERSISTENT or DBSTATE_SYSTEM are stored.
107: * @param node The node to insert
108: * @return The (new) number for this node, or -1 if an error occurs.
109: * @throws StorageException if an error occurred during insert
110: */
111: public int create(MMObjectNode node) throws StorageException;
112:
113: /**
114: * Commit this node to the specified builder.
115: * @param node The node to commit
116: * @throws StorageException if an error occurred during commit
117: */
118: public void change(MMObjectNode node) throws StorageException;
119:
120: /**
121: * Delete a node
122: * @param node The node to delete
123: * @throws StorageException if an error occurred during delete
124: */
125: public void delete(MMObjectNode node) throws StorageException;
126:
127: /**
128: * Select a node from a specified builder
129: * @param builder The builder to select from
130: * @param number the number of the node
131: * @return the MMObjectNode that was found, or null f it doesn't exist
132: * @throws StorageException if an error occurred during the get
133: */
134: public MMObjectNode getNode(MMObjectBuilder builder, int number)
135: throws StorageException;
136:
137: /**
138: * Returns the nodetype for a specified nodereference
139: * @param number the number of the node
140: * @return int the object type or -1 if not found
141: * @throws StorageException if an error occurred during selection
142: */
143: public int getNodeType(int number) throws StorageException;
144:
145: /**
146: * Create a storage element to store the specified builder's objects.
147: * @param builder the builder to create the storage element for
148: * @throws StorageException if an error occurred during the creation of the storage element
149: */
150: public void create(MMObjectBuilder builder) throws StorageException;
151:
152: /**
153: * Create the basic elements for this storage
154: * @throws StorageException if an error occurred during the creation of the object storage
155: */
156: public void create() throws StorageException;
157:
158: /**
159: * Changes the storage of a builder to match its new configuration.
160: * @param builder the builder whose storage to change
161: */
162: public void change(MMObjectBuilder builder) throws StorageException;
163:
164: /**
165: * Drops the storage of this builder.
166: * @param builder the builder whose storage to drop
167: */
168: public void delete(MMObjectBuilder builder) throws StorageException;
169:
170: /**
171: * Determine if a storage element exists for storing the given builder's objects
172: * @param builder the builder to check
173: * @return <code>true</code> if the storage element exists, false if it doesn't
174: * @throws StorageException if an error occurred while querying the storage
175: */
176: public boolean exists(MMObjectBuilder builder)
177: throws StorageException;
178:
179: /**
180: * Determine if the basic storage elements exist
181: * Basic storage elements include the 'object' storage (where all objects and their types are registered).
182: * @return <code>true</code> if basic storage elements exist
183: * @throws StorageException if an error occurred while querying the storage
184: */
185: public boolean exists() throws StorageException;
186:
187: /**
188: * Return the number of objects of a builder in the storage
189: * @param builder the builder whose objects to count
190: * @return the number of objects the builder has
191: * @throws StorageException if the storage element for the builder does not exists
192: */
193: public int size(MMObjectBuilder builder) throws StorageException;
194:
195: /**
196: * Return the total number of objects in the storage
197: * @return the number of objects
198: * @throws StorageException if the basic storage elements do not exist
199: */
200: public int size() throws StorageException;
201:
202: /**
203: * Creates a field and adds it to the storage of this builder.
204: * @param field the CoreField of the field to add
205: */
206: public void create(CoreField field) throws StorageException;
207:
208: /**
209: * Changes a field to the storage of this builder.
210: * @param field the CoreField of the field to change
211: */
212: public void change(CoreField field) throws StorageException;
213:
214: /**
215: * Deletes a field from the storage of this builder.
216: * @param field the CoreField of the field to delete
217: */
218: public void delete(CoreField field) throws StorageException;
219:
220: }
|