StorageManager


1   /*
2   
3   This software is OSI Certified Open Source Software.
4   OSI Certified is a certification mark of the Open Source Initiative.
5   
6   The license (Mozilla version 1.0) can be read at the MMBase site.
7   See http://www.MMBase.org/license
8   
9   */
10  package org.mmbase.storage;
11  
12  import org.mmbase.module.core.*;
13  import org.mmbase.core.CoreField;
14  import java.io.InputStream  ;
15  
16  /**
17   * The StorageManager interface defines how to access a storage device.
18   * It contains methods that can be used to query the storage, insert, update, or remove objects,
19   * or to change object definitions (adding fields, etc.).
20   *
21   * @author Pierre van Rooden
22   * @since MMBase-1.7
23   * @version $Id: StorageManager.java,v 1.7 2005/10/02 16:16:43 michiel Exp $
24   */
25  public interface StorageManager {
26  
27      /**
28       * Returns the version of this factory implementation.
29       * The factory uses this number to verify whether it can handle storage configuration files
30       * that list version requirements.
31       * @return the version as an integer
32       */
33      public double getVersion();
34  
35      /**
36       * Initializes the manager.
37       * Called by a StorageManagerFactory when instantiating the manager with the getStorageManager() method.
38       * @param factory the StorageManagerFactory instance that created this storage manager.
39       * @throws StorageConfigurationException if the initialization failed
40       */
41      public void init(StorageManagerFactory factory) throws StorageException;
42  
43      /**
44       * Starts a transaction on this StorageManager instance.
45       * All commands passed to the instance will be treated as being in this transaction.
46       * If transactions are not supported by the storage, no actual storage transaction is started, but the code continues as if it has.
47       * @throws StorageException if the transaction could not be created
48       */
49      public void beginTransaction() throws StorageException;
50  
51      /**
52       * Closes any transaction that was started and commits all changes.
53       * If transactions are not supported by the storage, nothing really happens (as changes are allready committed), but the code continues as if it has.
54       * @throws StorageException if a transaction is not currently active, or an error occurred while committing
55       */
56      public void commit() throws StorageException;
57  
58      /**
59       * Cancels any transaction that was started and rollback changes if possible.
60       * If transactions are not supported by the storage, nothing really happens (as changes are allready committed),
61       * but the code continues as if it has (through in that case it will return false).
62       * @return <code>true</code> if changes were rolled back, <code>false</code> if the transaction was
63       * canceled but the storage does not support rollback
64       * @throws StorageException if a transaction is not currently active, or an error occurred during rollback
65       */
66      public boolean rollback() throws StorageException;
67  
68      /**
69       * Gives an unique number for a new node, to be inserted in the storage.
70       * This method should work with multiple mmbases
71       * @return unique number
72       */
73      public int createKey() throws StorageException;
74  
75      /**
76       * Retrieve a large text for a specified object field.
77       * Implement this method to allow for optimization of storing and retrieving large texts.
78       * @param node the node to retrieve the text from
79       * @param field the Type of the field to retrieve
80       * @return the retrieved text
81       * @throws StorageException if an error occurred while retrieving the text value
82       */
83      public String   getStringValue(MMObjectNode node, CoreField field) throws StorageException;
84  
85      /**
86       * Retrieve a large binary object (byte array) for a specified object field.
87       * Implement this method to allow for optimization of storing and retrieving binary objects.
88       * @param node the node to retrieve the byte array from
89       * @param field the CoreField of the field to retrieve
90       * @return the retrieved byte array
91       * @throws StorageException if an error occurred while retrieving the binary value
92       */
93      public byte[] getBinaryValue(MMObjectNode node, CoreField field) throws StorageException;
94  
95  
96      /**
97       * @since MMBase-1.8
98       */
99      public InputStream   getInputStreamValue(MMObjectNode node, CoreField field) throws StorageException;
100 
101     /**
102      * This method creates a new object in the storage, and registers the change.
103      * Only fields with states of DBSTATE_PERSISTENT or DBSTATE_SYSTEM are stored.
104      * @param node The node to insert
105      * @return The (new) number for this node, or -1 if an error occurs.
106      * @throws StorageException if an error occurred during insert
107      */
108     public int create(MMObjectNode node) throws StorageException;
109 
110     /**
111      * Commit this node to the specified builder.
112      * @param node The node to commit
113      * @throws StorageException if an error occurred during commit
114      */
115     public void change(MMObjectNode node) throws StorageException;
116 
117     /**
118      * Delete a node
119      * @param node The node to delete
120      * @throws StorageException if an error occurred during delete
121      */
122     public void delete(MMObjectNode node) throws StorageException;
123 
124     /**
125      * Select a node from a specified builder
126      * @param builder The builder to select from
127      * @param number the number of the node
128      * @return the MMObjectNode that was found, or null f it doesn't exist
129      * @throws StorageException if an error occurred during the get
130      */
131     public MMObjectNode getNode(MMObjectBuilder builder, int number) throws StorageException;
132 
133     /**
134      * Returns the nodetype for a specified nodereference
135      * @param number the number of the node
136      * @return int the object type or -1 if not found
137      * @throws StorageException if an error occurred during selection
138      */
139     public int getNodeType(int number) throws StorageException;
140 
141     /**
142      * Create a storage element to store the specified builder's objects.
143      * @param builder the builder to create the storage element for
144      * @throws StorageException if an error occurred during the creation of the storage element
145      */
146     public void create(MMObjectBuilder builder) throws StorageException;
147 
148     /**
149      * Create the basic elements for this storage
150      * @throws StorageException if an error occurred during the creation of the object storage
151      */
152     public void create() throws StorageException;
153 
154     /**
155      * Changes the storage of a builder to match its new configuration.
156      * @param builder the builder whose storage to change
157      */
158     public void change(MMObjectBuilder builder) throws StorageException;
159 
160     /**
161      * Drops the storage of this builder.
162      * @param builder the builder whose storage to drop
163      */
164     public void delete(MMObjectBuilder builder) throws StorageException;
165 
166     /**
167      * Determine if a storage element exists for storing the given builder's objects
168      * @param builder the builder to check
169      * @return <code>true</code> if the storage element exists, false if it doesn't
170      * @throws StorageException if an error occurred while querying the storage
171      */
172     public boolean exists(MMObjectBuilder builder) throws StorageException;
173 
174     /**
175      * Determine if the basic storage elements exist
176      * Basic storage elements include the 'object' storage (where all objects and their types are registered).
177      * @return <code>true</code> if basic storage elements exist
178      * @throws StorageException if an error occurred while querying the storage
179      */
180     public boolean exists() throws StorageException;
181 
182     /**
183      * Return the number of objects of a builder in the storage
184      * @param builder the builder whose objects to count
185      * @return the number of objects the builder has
186      * @throws StorageException if the storage element for the builder does not exists
187      */
188     public int size(MMObjectBuilder builder) throws StorageException;
189 
190     /**
191      * Return the total number of objects in the storage
192      * @return the number of objects
193      * @throws StorageException if the basic storage elements do not exist
194      */
195     public int size() throws StorageException;
196 
197     /**
198      * Creates a field and adds it to the storage of this builder.
199      * @param field the CoreField of the field to add
200      */
201     public void create(CoreField field) throws StorageException;
202 
203     /**
204      * Changes a field to the storage of this builder.
205      * @param field the CoreField of the field to change
206      */
207     public void change(CoreField field) throws StorageException;
208 
209     /**
210      * Deletes a field from the storage of this builder.
211      * @param field the CoreField of the field to delete
212      */
213     public void delete(CoreField field) throws StorageException;
214 
215 }
216 
217
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags