Storage


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  package org.netbeans.mdr.persistence;
20  
21  import java.util.Collections  ;
22  import java.util.Arrays  ;
23  
24  /** Set of indexes (Singlevalued and Multivalued) that are all updated
25   * in a single transaction. Every index holds keys and every key in the index
26   * is connected with a value or an ordered/unordered values.
27   * The type of objects that can be stored in the index is resticted
28   * by the {@link Storage.Entrytype}.
29   * @author Pavel Buzek
30   * @version 1.0
31   */
32  public interface Storage {
33      /** Type of values and keys stored in index.
34       */
35      public static final class EntryType {
36          /** Values are fixed length alphanumeric strings */
37      public static final EntryType MOFID = new EntryType ((byte) 1, "MOFID");
38  
39          /** Values are objects that implement the Streamable interface. 
40           * This type of values may not be used by user to create a new index,
41           * it is used only in the primary index created by the Storage.
42           */
43          public static final EntryType STREAMABLE =new EntryType ((byte) 2, "STREAMABLE");
44  
45          /** Values are variable length Strings. */
46          public static final EntryType STRING =new EntryType ((byte) 3, "STRING");
47  
48          /** Values are integers. */
49          public static final EntryType INT =new EntryType ((byte) 4, "INT");
50  
51      private static final EntryType[] all = new EntryType[] {MOFID, STREAMABLE, STRING, INT};
52  
53          private final byte id;
54      private final String   textId;
55          
56      private EntryType(byte id, String   textId) {
57          this.id = id;
58          this.textId = textId;
59      }
60      
61          /** Returns list of all EntryTypes.
62           * @return Collection view of all available EntryTypes. 
63           */
64          public static java.util.Collection   getEntryTypes () {
65          return Collections.unmodifiableCollection(Arrays.asList(all));
66          }
67  
68          public static Storage.EntryType decodeEntryType (String   name) {
69              for (int i = 0; i < all.length; i++){
70                  if (all[i].textId.equals(name)) {
71                      return all[i];
72                  }
73              }
74              return null;
75          }
76  
77          public static Storage.EntryType decodeEntryType (byte code) {
78          if (code > 0 && code <= 4) return all[code-1];
79              return null;
80          }
81  
82      public String   toString() {
83              return textId;
84          }
85          
86      public byte encode() {
87              return id;
88          }
89      }
90  
91      public String   getName();
92      
93      public String   getStorageId ();
94      
95      public long getSerialNumber ();
96      
97      /** Reads a MOFID from Storage, must be called in the
98       *  streamable read context.
99       *  @return MOFID red object
100      *  @exception StorageException 
101      */
102     public MOFID readMOFID (java.io.InputStream   inputStream) throws StorageException;
103 
104     /** Writes a MOFID into Storage, must be called in the
105      *  streamable write context.
106      *  @param  MOFID mofid, object to be written
107      *  @exception StorageException 
108      */
109     public void writeMOFID (java.io.OutputStream   outputStream, MOFID mofid) throws StorageException;
110 
111     /** Returns the primary index in this Storage. There is exactly one primary
112      * index in every storage, primary index has valueType STREAMABLE.
113      */
114     public SinglevaluedIndex getPrimaryIndex() throws StorageException;
115     
116     /* Returns true if the Storage of the given name exists */
117     public boolean exists() throws StorageException;
118     
119     /** Delete any persistent resources associated with the Storage.
120      * @return true if and only if the Storage is succesfully deleted, false otherwise
121      */
122     public boolean delete() throws StorageException;
123     
124     /* Create a new Storage instance.  For btree, this creates a new btree repository.  
125      * For an RDBMS implementation, this might create a new database, or new tables and
126      * indexes within an existing database.  For an implementation which uses a JMI
127      * service, it might create a top-level package containing all MDR pacakges.
128      * After the repository is created, it is opened.
129      * If the repository already exists, and "replace" is false, an exception is
130      * thrown. If replace is true, the existing repository is deleted and a new one created.
131      * // PENDING: should return primary index or nothing ?
132      */
133     public void create (boolean replace, ObjectResolver resolver) throws StorageException;
134     
135     /* Open an existing repository.  If createOnNoExist is true, and the Storage
136      * doesn't exist, create it and then open it.
137      * // PENDING: should return primary index or nothing ?
138      */
139     public void open(boolean createOnNoExist, ObjectResolver resolver) throws StorageException;
140     
141     /* Close the Storage */
142     public void close() throws StorageException;
143 
144     /** Create index that holds exactly one value for each key.
145      * @return created index
146      * @param name name of the index
147      * @param keyType type of keys in the index
148      * @param valueType type of values in the index (any type except STREAMABLE)
149      */
150     public SinglevaluedIndex createSinglevaluedIndex(String   name, EntryType keyType, EntryType valueType) throws StorageException;
151     /** Create index that holds sorted set of values for each key.
152      * @return created index
153      * @param name name of the index
154      * @param keyType type of keys in the index
155      * @param valueType type of values in the index (any type except STREAMABLE)
156      * @param unique true if values associated with one key do not contain duplicates
157      */
158     public MultivaluedOrderedIndex createMultivaluedOrderedIndex(String   name, EntryType keyType, EntryType valueType, boolean unique) throws StorageException;
159     /** Create index that hold a set of values for each key. Elements in one Multivalued are
160      * not sorted. Set does not contain duplicate values.
161      * @return created index
162      * @param name name of the index
163      * @param keyType type of keys in the index
164      * @param valueType type of values in the index (any type except STREAMABLE)
165      * @param unique true if values associated with one key do not contain duplicates
166      */
167     public MultivaluedIndex createMultivaluedIndex(String   name, EntryType keyType, EntryType valueType, boolean unique) throws StorageException;
168 
169     /** Retrieve index by name.
170      * @param name name of the index
171      * @return index of the specified name
172      */
173     public Index getIndex(String   name) throws StorageException;
174     /** Retrieve index by name.
175      * @param name name of the index
176      * @return index of the specified name and type
177      */
178     public SinglevaluedIndex getSinglevaluedIndex(String   name) throws StorageException;
179     /** Retrieve index by name.
180      * @param name name of the index
181      * @return index of the specified name and type
182      */
183     public MultivaluedIndex getMultivaluedIndex(String   name) throws StorageException;
184     /** Retrieve index by name.
185      * @param name name of the index
186      * @return index of the specified name and type
187      */
188     public MultivaluedOrderedIndex getMultivaluedOrderedIndex(String   name) throws StorageException;
189     /** Delete index.
190      * @param name name of the index
191      */
192     public void dropIndex(String   name) throws StorageException;
193 
194     /** Notify the Storage that state of the object associated with this key
195      * will be changed.  This must be called before the change.
196      * Storage can use this notification to handle information needed to
197      * perform rollback. Note that the notification does not imply object
198      * change will perform necessary (the planned change can be canceled), 
199      * however every performed change (notified by {@link Storage#objectStateChanged})
200      * is supposed to be precedesed by this notification.
201      * @param key key of the object that will be changed
202      */
203     public void objectStateWillChange (Object   key) throws StorageException;
204     
205     /** Notify the Storage that state of the object associated with this key
206      * was changed.  This must be called after the change is made to ensure 
207      * that the changed state is comitted correctly.
208      * @param key key of the object that was changed and must be saved
209      */
210     public void objectStateChanged (Object   key) throws StorageException;            
211     
212     /** Save all objects changed since this method was last call.
213      * This operation implements transactions on the storage.
214      * It must either whole complete or whole fail.
215      */
216     public void commitChanges() throws StorageException;
217 
218     /** Discard all changes since commitChanges() method was last call.
219      * This operation implements transactions on the storage.
220      * It must either whole complete or whole fail.
221      * Note that, after this method completes, the persistent MDR and
222      * any modified objects in memory are inconsistent, so it should
223      * be followed shortly by program exit.
224      */
225     public void rollBackChanges () throws StorageException;
226     
227     /**
228      * Performs operations needed on exit.
229      */
230     public void shutDown() throws StorageException;
231     
232 //
233 // Method removed, storage has always only one primary index, that is returned by 
234 // getPrimaryIndex method
235 // 
236 //    /** Returns true if the storage supports more than one index with type
237 //     * {@link Entrytype.STREAMABLE}
238 //     * @return true if the storage supports more than one index with type
239 //     * {@link Entrytype.STREAMABLE}
240 //     */
241 //    public boolean supportsMultipleStorableIndexes() throws StorageException;
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags