001: /*
002: Copyright (C) 2007 Mobixess Inc. http://www.java-objects-database.com
003:
004: This file is part of the JODB (Java Objects Database) open source project.
005:
006: JODB is free software; you can redistribute it and/or modify it under
007: the terms of version 2 of the GNU General Public License as published
008: by the Free Software Foundation.
009:
010: JODB is distributed in the hope that it will be useful, but WITHOUT ANY
011: WARRANTY; without even the implied warranty of MERCHANTABILITY or
012: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013: for more details.
014:
015: You should have received a copy of the GNU General Public License along
016: with this program; if not, write to the Free Software Foundation, Inc.,
017: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
018: */
019: package com.mobixess.jodb.soda.api;
020:
021: import java.io.IOException;
022:
023: import com.mobixess.jodb.core.IllegalClassTypeException;
024:
025: /**
026: * database engine interface.
027: * <br><br>The <code>ObjectContainer</code> interface provides all methods
028: * to store, retrieve and delete objects and to change object state.
029: */
030: public interface ObjectContainer {
031:
032: /**
033: * Activates all members on a stored object to the specified depth.
034: * <br><br>
035: * @throws IOException
036: */
037: public void activate(Object obj, int depth) throws IOException;
038:
039: /**
040: * closes the <code>ObjectContainer</code>.
041: * <br><br>A call to <code>close()</code> automatically performs a
042: * {@link #commit commit()}.
043: * <br><br>Every session opened with JODB.openFile() requires one
044: * close()call, even if the same filename was used multiple times.<br><br>
045: * Use <code>while(!close()){}</code> to close all sessions using this container.<br><br>
046: * @return success - true denotes that the last used instance of this container
047: * and the database file were closed.
048: * @throws IOException
049: */
050: public boolean close() throws IOException;
051:
052: /**
053: * Commits the running transaction.
054: *
055: * @throws IOException
056: */
057: public void commit() throws IOException;
058:
059: /**
060: * deactivates a stored object by setting all members to <code>NULL</code>.
061: * <br>Primitive types will be set to their default values.
062: * The method has no effect, if the passed object is not stored in the
063: * <code>ObjectContainer</code>
064: * <br><br>
065: * @param obj the object to be deactivated.
066: * @param depth the member
067: * to which deactivate is to cascade.
068: */
069: public void deactivate(Object obj, int depth);
070:
071: /**
072: * deletes a stored object permanently.
073: * <br><br>Note that this method has to be called <b>for every single object
074: * individually</b>. Delete does not recurse to object members. Simple
075: * and array member types are destroyed.
076: *
077: * The method has no effect, if
078: * the passed object is not stored in the <code>ObjectContainer</code>.
079: * which can be also used for cascaded deletes.<br><br>
080: * @param obj the object to be deleted from the
081: * <code>ObjectContainer</code>.<br>
082: * @throws IOException
083: */
084: public void delete(Object obj) throws IOException;
085:
086: /**
087: * Query-By-Example interface to retrieve objects.
088: * <br><br><code>get()</code> creates an
089: * {@link ObjectSet ObjectSet} containing
090: * all objects in the <code>ObjectContainer</code> that match the passed
091: * template object.<br><br>
092: * Calling <code>get(NULL)</code> returns all objects stored in the
093: * <code>ObjectContainer</code>.<br><br><br>
094: * <b>Query Evaluation</b>
095: * <br>All non-null members of the template object are compared against
096: * all stored objects of the same class.
097: * Primitive type members are ignored if they are 0 or false respectively.
098: * <br><br>
099: * <b>Returned Objects</b><br>
100: * The objects returned in the
101: * {@link ObjectSet ObjectSet} are instantiated
102: * and activated to the preconfigured depth. The
103: * {@link com.mobixess.jodb.core.JODBConfig#getDefaultActivationDepth activation depth}
104: * may be configured globally via {@link com.mobixess.jodb.core.JODBConfig#setDefaultActivationDepth() }.
105: * <br><br>
106: * The database keeps track of all instantiatied objects. Queries will return
107: * references to these objects instead of instantiating them a second time.
108: * <br><br>
109: * @param template object to be used as an example to find all matching objects.<br><br>
110: * @return {@link ObjectSet ObjectSet} containing all found objects.<br><br>
111: * @throws IOException
112: * @throws IllegalClassTypeException
113: */
114: public <T> ObjectSet<T> get(Object template) throws IOException,
115: IllegalClassTypeException;
116:
117: /**
118: * creates a new S.O.D.A. {@link Query Query}.
119: * <br><br>
120: * Use {@link #get get(Object template)} for simple Query-By-Example.<br><br>
121: * <br><br>
122: * @return a new Query object
123: */
124: public Query query();
125:
126: /**
127: * queries for all instances of a class.
128: * @param clazz the class to query for.
129: * @return the {@link ObjectSet} returned by the query.
130: * @throws IOException
131: * @throws IllegalClassTypeException
132: */
133: public <Type> ObjectSet<Type> query(Class<Type> clazz)
134: throws IOException, IllegalClassTypeException;
135:
136: /**
137: * rolls back the running transaction.
138: * <br><br>Modified application objects im memory are not restored.
139: * Use combined calls to {@link #deactivate deactivate()}
140: * and {@link #activate activate()} to reload an objects member values.
141: */
142: public void rollback();
143:
144: /**
145: * Newly stores objects or updates stored objects.
146: * <br><br>An object not yet stored in the <code>ObjectContainer</code> will be
147: * stored when it is passed to <code>set()</code>. An object already stored
148: * in the <code>ObjectContainer</code> will be updated.
149: * @param obj the object to be stored or updated.
150: * @throws IOException
151: * @throws {@link IllegalClassTypeException}
152: */
153: public void set(Object obj) throws IllegalClassTypeException,
154: IOException;
155:
156: /**
157: * Newly stores objects or updates stored objects.
158: * <br><br>An object not yet stored in the <code>ObjectContainer</code> will be
159: * stored when it is passed to <code>set()</code>. An object already stored
160: * in the <code>ObjectContainer</code> will be updated.
161: *
162: * @param obj the object to be stored or updated.
163: * @param depth the depth to which the object is to be updated
164: * @throws IllegalClassTypeException
165: * @throws IOException
166: */
167: public void set(Object obj, int depth)
168: throws IllegalClassTypeException, IOException;
169:
170: }
|