001: // You can redistribute this software and/or modify it under the terms of
002: // the Ozone Library License version 1 published by ozone-db.org.
003: //
004: // The original code and portions created by SMB are
005: // Copyright (C) 1997-@year@ by SMB GmbH. All rights reserved.
006: //
007: // $Id: OzoneInterface.java,v 1.3 2002/06/08 00:49:38 mediumnet Exp $
008:
009: package org.ozoneDB;
010:
011: import org.w3c.dom.Document;
012: import org.w3c.dom.Node;
013: import org.xml.sax.ContentHandler;
014:
015: /**
016: * Together with {@link ExternalTransaction} and {@link OzoneCompatible} this
017: * interface represents the basic API of the ozone database system.
018: *
019: *
020: * @author <a href="http://www.softwarebuero.de/">SMB</a>
021: * @author <a href="http://www.medium.net/">Medium.net</a>
022: * @version $Revision: 1.3 $Date: 2002/06/08 00:49:38 $
023: */
024: public interface OzoneInterface {
025:
026: /** Object access right. */
027: public final static int Private = 0;
028:
029: /** Object access right. */
030: public final static int AllRead = 1;
031:
032: /** Object access right. */
033: public final static int AllLock = 2;
034:
035: /** Object access right. */
036: public final static int GroupRead = 4;
037:
038: /** Object access right. */
039: public final static int GroupLock = 8;
040:
041: /** Object access right. Combines {@link AllRead} and {@link AllLock}. */
042: public final static int Public = AllRead | AllLock;
043:
044: /**
045: * Creates a database object of the specified class without a name and with
046: * default permissions.
047: *
048: *
049: * @param className The fully qualified name of the class.
050: * @return A proxy object for the newly created object.
051: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
052: * ozone related problem.
053: * @throws {@link RuntimeException} To signal an implementation specific problem,
054: * such as {@link IOException}
055: */
056: public OzoneProxy createObject(String className)
057: throws RuntimeException;
058:
059: /**
060: * Creates a database object of the specified class without a name and with
061: * the specified access rights.
062: *
063: *
064: * @param className The fully qualified name of the class.
065: * @param access The access rights (ORed).
066: * @return proxy A proxy object for the newly created database object.
067: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
068: * ozone related problem.
069: * @throws {@link RuntimeException} To signal an implementation specific problem,
070: * such as {@link IOException}
071: */
072: public OzoneProxy createObject(String className, int access)
073: throws RuntimeException;
074:
075: /**
076: * Creates a database object of the specified class with the specified name
077: * and the specified access rights.
078: *
079: *
080: * @param className The fully qualified name of the class.
081: * @param access The access right. (ORed)
082: * @param objName The name of the object. (optional)
083: * @return A proxy object for the newly created object.
084: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
085: * ozone related problem.
086: * @throws {@link RuntimeException} To signal an implementation specific problem,
087: * such as {@link IOException}
088: */
089: public OzoneProxy createObject(String className, int access,
090: String objName) throws RuntimeException;
091:
092: /**
093: * Creates an object by calling the constructor with the specified
094: * signature with the specified parameters. Generated proxy objects use
095: * this method.<p>
096: *
097: *
098: * @param className fully qualified name of the class
099: * @param access access right (ORed)
100: * @param objName name of the object (optional
101: * @param sig The signature string of the constructor.
102: * @param args The parameter that are passed to the constructor.
103: * @return proxy A OzoneProxy object for the newly created object.
104: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
105: * ozone related problem.
106: * @throws {@link RuntimeException} To signal an implementation specific problem,
107: * such as {@link IOException}
108: */
109: public OzoneProxy createObject(String className, int access,
110: String objName, String sig, Object[] args)
111: throws RuntimeException;
112:
113: /**
114: * Creates an object by calling the constructor with the specified
115: * signature with the specified parameters and default permissions.
116: *
117: *
118: * @param className fully qualified name of the class
119: * @param sig The signature string of the constructor.
120: * @param args The parameter that are passed to the constructor.
121: * @return proxy A OzoneProxy object for the newly created object.
122: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
123: * ozone related problem.
124: * @throws {@link RuntimeException} To signal an implementation specific problem,
125: * such as {@link IOException}
126: */
127: public OzoneProxy createObject(String className, String sig,
128: Object[] args) throws RuntimeException;
129:
130: /**
131: * Creates a database object of the specified class without a name and with
132: * default permissions.
133: *
134: *
135: * @param type the type of the object to be created
136: * @return A proxy object for the newly created object.
137: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
138: * ozone related problem.
139: * @throws {@link RuntimeException} To signal an implementation specific problem,
140: * such as {@link IOException}
141: */
142: public OzoneProxy createObject(Class type) throws RuntimeException;
143:
144: /**
145: * Creates a database object of the specified class without a name and with
146: * the specified access rights.
147: *
148: *
149: * @param type the type of the object to be created
150: * @param access The access rights (ORed).
151: * @return proxy A proxy object for the newly created database object.
152: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
153: * ozone related problem.
154: * @throws {@link RuntimeException} To signal an implementation specific problem,
155: * such as {@link IOException}
156: */
157: public OzoneProxy createObject(Class type, int access)
158: throws RuntimeException;
159:
160: /**
161: * Creates a database object of the specified class with the specified name
162: * and the specified access rights.
163: *
164: *
165: * @param type the type of the object to be created
166: * @param access The access right. (ORed)
167: * @param objName The name of the object. (optional)
168: * @return A proxy object for the newly created object.
169: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
170: * ozone related problem.
171: * @throws {@link RuntimeException} To signal an implementation specific problem,
172: * such as {@link IOException}
173: */
174: public OzoneProxy createObject(Class type, int access,
175: String objName) throws RuntimeException;
176:
177: /**
178: * Creates an object by calling the constructor with the specified
179: * signature with the specified parameters. Generated proxy objects use
180: * this method.<p>
181: *
182: *
183: * @param type the type of the object to be created
184: * @param access access right (ORed)
185: * @param objName name of the object (optional
186: * @param sig The signature string of the constructor.
187: * @param args The parameter that are passed to the constructor.
188: * @return proxy A OzoneProxy object for the newly created object.
189: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
190: * ozone related problem.
191: * @throws {@link RuntimeException} To signal an implementation specific problem,
192: * such as {@link IOException}
193: */
194: public OzoneProxy createObject(Class type, int access,
195: String objName, String sig, Object[] args)
196: throws RuntimeException;
197:
198: /**
199: * Creates an object by calling the constructor with the specified
200: * signature with the specified parameters and default permissions.
201: *
202: *
203: * @param type the type of the object to be created
204: * @param sig The signature string of the constructor.
205: * @param args The parameter that are passed to the constructor.
206: * @return proxy A OzoneProxy object for the newly created object.
207: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
208: * ozone related problem.
209: * @throws {@link RuntimeException} To signal an implementation specific problem,
210: * such as {@link IOException}
211: */
212: public OzoneProxy createObject(Class type, String sig, Object[] args)
213: throws RuntimeException;
214:
215: /**
216: * Copy an object. The new objects gets its own object ID. The specified
217: * object is an instance of OzoneProxy which you may have created by
218: * createObject().
219: *
220: *
221: * @param rObj
222: * @return proxy for the newly created object
223: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
224: * ozone related problem.
225: * @throws {@link Exception} To signal an implementation specific problem,
226: * such as {@link IOException}
227: */
228: public OzoneProxy copyObject(OzoneRemote rObj) throws Exception;
229:
230: /**
231: * Deletes the specified database object. The specified object is an
232: * instance of OzoneProxy which you may have created by createObject().
233: *
234: *
235: * @param rObj
236: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
237: * ozone related problem.
238: * @throws {@link RuntimeException} To signal an implementation specific problem,
239: * such as {@link IOException}
240: */
241: public void deleteObject(OzoneRemote rObj) throws RuntimeException;
242:
243: /**
244: * Assigns the specified object with the specified name. This can
245: * also be done at object creation time. The specified object is an
246: * instance of OzoneProxy which you may have created by createObject().
247: *
248: *
249: * @param rObj
250: * @param name
251: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
252: * ozone related problem.
253: * @throws {@link Exception} To signal an implementation specific problem,
254: * such as {@link IOException}
255: */
256: public void nameObject(OzoneRemote rObj, String name)
257: throws Exception;
258:
259: /**
260: * Returns the object for the specifies name or null if there is no such
261: * object.
262: *
263: *
264: * @param The name name of the object.
265: * @return A proxy object for the found object or null.
266: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
267: * ozone related problem.
268: * @throws {@link Exception} To signal an implementation specific problem,
269: * such as {@link IOException}
270: */
271: public OzoneProxy objectForName(String name) throws Exception;
272:
273: /**
274: * Returns the object for the specified handle or null if there is no such
275: * object.
276: *
277: *
278: * @param The handle of the object.
279: * @return A proxy object for the found object or null.
280: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
281: * ozone related problem.
282: * @throws {@link Exception} To signal an implementation specific problem,
283: * such as {@link IOException}
284: */
285: public OzoneProxy objectForHandle(String handle) throws Exception;
286:
287: /**
288: * Gives all objects of the specified class as array.
289: *
290: *
291: * @param name
292: * @return
293: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
294: * ozone related problem.
295: * @throws {@link Exception} To signal an implementation specific problem,
296: * such as {@link IOException}
297: */
298: public OzoneProxy[] objectsOfClass(String name) throws Exception;
299:
300: /**
301: * Invokes a method on the specified object. This method is called by
302: * proxy objects to route the call to the corresponding database object.
303: * A client will never call this method explicitly.
304: *
305: *
306: * @param rObj OzoneProxy on which to call the method
307: * @param methodName
308: * @param sig signature of the method as String
309: * @param args array of arguments
310: * @param update specifies wether this method changes the state of the object
311: * @return regular object or proxy
312: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
313: * ozone related problem.
314: * @throws {@link Exception} To signal an implementation specific problem,
315: * such as {@link IOException}
316: */
317: public Object invoke(OzoneProxy rObj, String methodName,
318: String sig, Object[] args, int lockLevel) throws Exception;
319:
320: public Object invoke(OzoneProxy rObj, int methodIndex,
321: Object[] args, int lockLevel) throws Exception;
322:
323: /**
324: * Returns the actual target of the given proxy if the actual implementation
325: * is able to do so. A client will never call this method explicitly.
326: */
327: public OzoneCompatible fetch(OzoneProxy rObj, int lockLevel)
328: throws Exception;
329:
330: /**
331: * Force the database server to reload all classes which extend
332: * OzoneObject. This is particularly useful while testing new classes.
333: *
334: * @throws {@link OzoneRemoteExc} (or one of its sub-classes) to signal a
335: * ozone related problem.
336: * @throws {@link Exception} To signal an implementation specific problem,
337: * such as {@link IOException}
338: */
339: public void reloadClasses() throws Exception;
340:
341: /**
342: * Convert the specified object into XML. This method returns the
343: * generated XML data as DOM tree. For performance reasons you should
344: * try to use {@link #xmlForObject(OzoneRemote, ContentHandler)}, which
345: * returns SAX events, instead of DOM.
346: * See the doc directory of ozone for a detailed description (XML Schema)
347: * of the XML output of this method.
348: *
349: * @param rObj The database object to be converted.
350: * @param factory The factory for creating DOM nodes.
351: *
352: * @result The DOM node representing the converted object.
353: */
354: public Node xmlForObject(OzoneRemote rObj, Document domFactory)
355: throws Exception;
356:
357: /**
358: * Converts the specified object into XML. This method returns the generated
359: * XML data as SAX events. See the doc directory of ozone for a detailed
360: * description (XML Schema) of the XML output of this method.
361: *
362: * @param rObj The database object to be converted.
363: * @param ch The SAX ContentHandler to which the result is sent.
364: */
365: public void xmlForObject(OzoneRemote rObj, ContentHandler ch)
366: throws Exception;
367:
368: // /** Service handle to be used with the {@link #service()} method.*/
369: // public final static int SERVICE_HANDLE_XML = 1;
370: //
371: //
372: // public OzoneService service (int serviceHandle)
373: // throws Exception;
374:
375: /**
376: Creates a unique ID. This ID is unique to all other IDs returned by this method (and by the way also unique
377: to all IDs used within the database). Though, the uniqueness is limited to the amount of states a long
378: can represent. If 1000 unique IDs were created each second, the time of non-uniqueness would begin after
379: 584'942'417 years. So it would happen after the Y10k problem, where we can revise the software using these
380: unique IDs... ;-)
381: */
382: /*
383: Currently, we do not implement this.
384: This method is (for an ExternalDatabase) surely slower and much more expensive than just waiting a millisecond
385: and using the new UNIX epoch millisecond as ID exclusively. However, this would depend on a current time which
386: never falls.
387: */
388: /*
389: public long createUniqueID();
390: */
391:
392: /**
393: Internal method. This method is called by {@link OzoneProxy}s when they are dying (during finalize()). This
394: is required, as the database may track the references the database client has to objects within the database
395: in order to properly support garbage collection. If this method is called from anyone else than from the
396: {@link OzoneProxy}.finalize()-Method, data loss may occur!
397:
398: @param proxy the OzoneProxy object which is dying. It may call this method exaclty once.
399: */
400: public void notifyProxyDeath(OzoneProxy proxy);
401:
402: }
|