OzoneInterface


1   // You can redistribute this software and/or modify it under the terms of
2   // the Ozone Library License version 1 published by ozone-db.org.
3   //
4   // The original code and portions created by SMB are
5   // Copyright (C) 1997-@year@ by SMB GmbH. All rights reserved.
6   //
7   // $Id: OzoneInterface.java,v 1.12 2003/04/06 13:57:32 mediumnet Exp $
8   
9   package org.ozoneDB;
10  
11  import org.w3c.dom.Document  ;
12  import org.w3c.dom.Node  ;
13  import org.xml.sax.ContentHandler  ;
14  
15  
16  /**
17   * Together with {@link ExternalTransaction} and {@link OzoneCompatible} this
18   * interface represents the basic API of the ozone database system.
19   *
20   *
21   * @author <a HREF="http://www.softwarebuero.de/">SMB</a>
22   * @author <a HREF="http://www.medium.net/">Medium.net</a>
23   * @version $Revision: 1.12 $Date: 2003/04/06 13:57:32 $
24   */
25  public interface OzoneInterface {
26  
27      /** Object access right. */
28      public final static int Private = 0;
29  
30      /** Object access right. */
31      public final static int AllRead = 1;
32  
33      /** Object access right. */
34      public final static int AllLock = 2;
35  
36      /** Object access right. */
37      public final static int GroupRead = 4;
38  
39      /** Object access right. */
40      public final static int GroupLock = 8;
41  
42      /** Object access right. Combines {@link #AllRead} and {@link #AllLock}. */
43      public final static int Public = AllRead | AllLock;
44  
45  
46      /**
47       * Creates a database object of the specified class without a name and with
48       * default permissions.
49       *
50       *
51       * @param className The fully qualified name of the class.
52       * @return A proxy object for the newly created object.
53       * @throws org.ozoneDB.OzoneRemoteException (or one of its sub-classes) to signal a
54       * ozone related problem.
55       * @throws RuntimeException To signal an implementation specific problem,
56       * such as {@link java.io.IOException}
57       */
58      public OzoneProxy createObject(String   className) throws RuntimeException  , OzoneRemoteException;
59  
60  
61      /**
62       * Creates a database object of the specified class without a name and with
63       * the specified access rights.
64       *
65       *
66       * @param className The fully qualified name of the class.
67       * @param access The access rights (ORed).
68       * @return proxy A proxy object for the newly created database object.
69       * @throws OzoneRemoteException (or one of its sub-classes) to signal a
70       * ozone related problem.
71       * @throws RuntimeException To signal an implementation specific problem,
72       * such as {@link java.io.IOException}
73       */
74      public OzoneProxy createObject(String   className,int access) throws RuntimeException  , OzoneRemoteException;
75  
76  
77      /**
78       * Creates a database object of the specified class with the specified name
79       * and the specified access rights.
80       *
81       *
82       * @param className The fully qualified name of the class.
83       * @param access The access right. (ORed)
84       * @param objName The name of the object. (optional)
85       * @return A proxy object for the newly created object.
86       * @throws OzoneRemoteException (or one of its sub-classes) to signal a
87       * ozone related problem.
88       * @throws RuntimeException To signal an implementation specific problem,
89       * such as {@link java.io.IOException}
90       */
91      public OzoneProxy createObject(String   className,int access,String   objName) throws RuntimeException  , OzoneRemoteException;
92  
93  
94      /**
95       * Creates an object by calling the constructor with the specified
96       * signature with the specified parameters. Generated proxy objects use
97       * this method.<p>
98       *
99       *
100      * @param className fully qualified name of the class
101      * @param access access right (ORed)
102      * @param objName name of the object (optional
103      * @param sig The signature string of the constructor.
104      * @param args The parameter that are passed to the constructor.
105      * @return proxy A OzoneProxy object for the newly created object.
106      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
107      * ozone related problem.
108      * @throws RuntimeException To signal an implementation specific problem,
109      * such as {@link java.io.IOException}
110      */
111     public OzoneProxy createObject(String   className,int access,String   objName,String   sig,Object  [] args) throws RuntimeException  , OzoneRemoteException;
112 
113 
114     /**
115      * Creates an object by calling the constructor with the specified
116      * signature with the specified parameters and default permissions.
117      *
118      *
119      * @param className fully qualified name of the class
120      * @param sig The signature string of the constructor.
121      * @param args The parameter that are passed to the constructor.
122      * @return proxy A OzoneProxy object for the newly created object.
123      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
124      * ozone related problem.
125      * @throws RuntimeException To signal an implementation specific problem,
126      * such as {@link java.io.IOException}
127      */
128     public OzoneProxy createObject( String   className, String   sig, Object  [] args) throws RuntimeException  , OzoneRemoteException;
129 
130 
131     /**
132      * Creates a database object of the specified class without a name and with
133      * default permissions.
134      *
135      *
136      * @param type the type of the object to be created
137      * @return A proxy object for the newly created object.
138      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
139      * ozone related problem.
140      * @throws RuntimeException To signal an implementation specific problem,
141      * such as {@link java.io.IOException}
142      */
143     public OzoneProxy createObject(Class   type) throws RuntimeException  , OzoneRemoteException;
144 
145 
146     /**
147      * Creates a database object of the specified class without a name and with
148      * the specified access rights.
149      *
150      *
151      * @param type the type of the object to be created
152      * @param access The access rights (ORed).
153      * @return proxy A proxy object for the newly created database object.
154      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
155      * ozone related problem.
156      * @throws RuntimeException To signal an implementation specific problem,
157      * such as {@link java.io.IOException}
158      */
159     public OzoneProxy createObject(Class   type, int access ) throws RuntimeException  , OzoneRemoteException;
160 
161 
162     /**
163      * Creates a database object of the specified class with the specified name
164      * and the specified access rights.
165      *
166      *
167      * @param type the type of the object to be created
168      * @param access The access right. (ORed)
169      * @param objName The name of the object. (optional)
170      * @return A proxy object for the newly created object.
171      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
172      * ozone related problem.
173      * @throws RuntimeException To signal an implementation specific problem,
174      * such as {@link java.io.IOException}
175      */
176     public OzoneProxy createObject(Class   type, int access, String   objName ) throws RuntimeException  , OzoneRemoteException;
177 
178 
179     /**
180      * Creates an object by calling the constructor with the specified
181      * signature with the specified parameters. Generated proxy objects use
182      * this method.<p>
183      *
184      *
185      * @param type the type of the object to be created
186      * @param access access right (ORed)
187      * @param objName name of the object (optional
188      * @param sig An array of signature params for the constructor in question.
189      * @param args The parameter that are passed to the constructor.
190      * @return proxy A OzoneProxy object for the newly created object.
191      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
192      * ozone related problem.
193      * @throws RuntimeException To signal an implementation specific problem,
194      * such as {@link java.io.IOException}
195      */
196     public OzoneProxy createObject(Class   type, int access, String   objName, Class  [] sig, Object  [] args) throws RuntimeException  , OzoneRemoteException;
197 
198 
199     /**
200      * Creates an object by calling the constructor with the specified
201      * signature with the specified parameters and default permissions.
202      *
203      *
204      * @param type the type of the object to be created
205      * @param sig An array of signature params for the constructor in question.
206      * @param args The parameter that are passed to the constructor.
207      * @return proxy A OzoneProxy object for the newly created object.
208      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
209      * ozone related problem.
210      * @throws RuntimeException To signal an implementation specific problem,
211      * such as {@link java.io.IOException}
212      */
213     public OzoneProxy createObject(Class   type, Class  [] sig, Object  [] args) throws RuntimeException  , OzoneRemoteException;
214 
215 
216     /**
217      * Copy an object. The new objects gets its own object ID. The specified
218      * object is an instance of OzoneProxy which you may have created by
219      * createObject().
220      *
221      *
222      * @param rObj
223      * @return proxy for the newly created object
224      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
225      * ozone related problem.
226      * @throws Exception To signal an implementation specific problem,
227      * such as {@link java.io.IOException}
228      */
229     public OzoneProxy copyObject(OzoneRemote rObj) throws Exception  ;
230 
231 
232     /**
233      * Deletes the specified database object. The specified object is an
234      * instance of OzoneProxy which you may have created by createObject().
235      *
236      *
237      * @param rObj
238      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
239      * ozone related problem.
240      * @throws RuntimeException To signal an implementation specific problem,
241      * such as {@link java.io.IOException}
242      */
243     public void deleteObject(OzoneRemote rObj) throws RuntimeException  , OzoneRemoteException;
244 
245 
246     /**
247      * Assigns the specified object with the specified name. This can
248      * also be done at object creation time. The specified object is an
249      * instance of OzoneProxy which you may have created by createObject().
250      *
251      *
252      * @param rObj
253      * @param name
254      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
255      * ozone related problem.
256      * @throws Exception To signal an implementation specific problem,
257      * such as {@link java.io.IOException}
258      */
259     public void nameObject(OzoneRemote rObj, String   name) throws Exception  ;
260 
261 
262     /**
263      * Returns the object for the specifies name or null if there is no such
264      * object.
265      *
266      *
267      * @param name The name name of the object.
268      * @return A proxy object for the found object or null.
269      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
270      * ozone related problem.
271      * @throws Exception To signal an implementation specific problem,
272      * such as {@link java.io.IOException}
273      */
274     public OzoneProxy objectForName(String   name) throws Exception  ;
275 
276     /**
277      * fetch an array of all named objects
278      *
279      *
280      * @return a String array of all named objects
281      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
282      * ozone related problem.
283      * @throws Exception To signal an implementation specific problem,
284      * such as {@link java.io.IOException}
285      */
286     public String  [] objectNames() throws Exception  ;
287 
288     /**
289      * Returns the object for the specified handle or null if there is no such
290      * object.
291      *
292      *
293      * @param handle The handle of the object.
294      * @return A proxy object for the found object or null.
295      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
296      * ozone related problem.
297      * @throws Exception To signal an implementation specific problem,
298      * such as {@link java.io.IOException}
299      */
300     public OzoneProxy objectForHandle(String   handle) throws Exception  ;
301 
302     /**
303      * Invokes a method on the specified object. This method is called by
304      * proxy objects to route the call to the corresponding database object.
305      * A client will never call this method explicitly.
306      *
307      *
308      * @param rObj OzoneProxy on which to call the method
309      * @param methodName
310      * @param sig signature of the method as String
311      * @param args array of arguments
312      * @param lockLevel specifies wether this method changes the state of the object
313      * @return regular object or proxy
314      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
315      * ozone related problem.
316      * @throws Exception To signal an implementation specific problem,
317      * such as {@link java.io.IOException}
318      */
319     public Object   invoke(OzoneProxy rObj, String   methodName, String   sig, Object  [] args, int lockLevel) throws Exception  ;
320 
321 
322     public Object   invoke(OzoneProxy rObj, int methodIndex, Object  [] args, int lockLevel) throws Exception  ;
323 
324 
325     /**
326      * Returns the actual target of the given proxy if the actual implementation
327      * is able to do so. A client will never call this method explicitly.
328      */
329     public OzoneCompatible fetch(OzoneProxy rObj, int lockLevel) throws Exception  ,org.ozoneDB.ObjectNotFoundException, java.io.IOException  , java.lang.ClassNotFoundException  , org.ozoneDB.TransactionException, org.ozoneDB.core.TransactionError;
330 
331 
332     /**
333      * Force the database server to reload all classes which extend
334      * OzoneObject. This is particularly useful while testing new classes.
335      *
336      * @throws OzoneRemoteException (or one of its sub-classes) to signal a
337      * ozone related problem.
338      * @throws Exception To signal an implementation specific problem,
339      * such as {@link java.io.IOException}
340      */
341     public void reloadClasses() throws Exception  ;
342 
343 
344     /**
345      * Convert the specified object into XML. This method returns the
346      * generated XML data as DOM tree. For performance reasons you should
347      * try to use {@link #xmlForObject(OzoneRemote, ContentHandler)}, which
348      * returns SAX events, instead of DOM.
349      * See the doc directory of ozone for a detailed description (XML Schema)
350      * of the XML output of this method.
351      *
352      * @param rObj The database object to be converted.
353      * @param domFactory The factory for creating DOM nodes.
354      *
355      * @return The DOM node representing the converted object.
356      */
357     public Node   xmlForObject(OzoneRemote rObj, Document   domFactory)
358             throws Exception  ;
359 
360 
361     /**
362      * Converts the specified object into XML. This method returns the generated
363      * XML data as SAX events. See the doc directory of ozone for a detailed
364      * description (XML Schema) of the XML output of this method.
365      *
366      * @param rObj The database object to be converted.
367      * @param ch The SAX ContentHandler to which the result is sent.
368      */
369     public void xmlForObject(OzoneRemote rObj, ContentHandler   ch)
370             throws Exception  ;
371 
372 
373     //    /** Service handle to be used with the {@link #service()} method.*/
374     //    public final static int   SERVICE_HANDLE_XML = 1;
375     //
376     //
377     //    public OzoneService service (int serviceHandle)
378     //        throws Exception;
379 
380 
381     /**
382         Creates a unique ID. This ID is unique to all other IDs returned by this method (and by the way also unique
383         to all IDs used within the database). Though, the uniqueness is limited to the amount of states a long
384         can represent. If 1000 unique IDs were created each second, the time of non-uniqueness would begin after
385         584'942'417 years. So it would happen after the Y10k problem, where we can revise the software using these
386         unique IDs... ;-)
387     */
388     /*
389         Currently, we do not implement this.
390         This method is (for an ExternalDatabase) surely slower and much more expensive than just waiting a millisecond
391         and using the new UNIX epoch millisecond as ID exclusively. However, this would depend on a current time which
392         never falls.
393     */
394     /*
395     public long createUniqueID();
396     */
397 
398     /**
399         Internal method. This method is called by {@link OzoneProxy}s when they are dying (during finalize()). This
400         is required, as the database may track the references the database client has to objects within the database
401         in order to properly support garbage collection. If this method is called from anyone else than from the
402         {@link OzoneProxy}.finalize()-Method, data loss may occur!
403 
404         @param proxy the OzoneProxy object which is dying. It may call this method exactly once.
405     */
406     public void notifyProxyDeath(OzoneProxy proxy);
407 
408 }
409
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags