001 package org.apache.ojb.odmg;
002
003 /* Copyright 2002-2005 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 import org.odmg.Implementation;
019
020 /**
021 * Offers useful none odmg-standard methods of the odmg {@link org.odmg.Implementation} interface.
022 * <p>
023 * Note: All listed methods are <strong>not</strong> part of the standard ODMG-api -
024 * they are special (proprietary) OJB extensions.
025 * </p>
026 *
027 * @version $Id: ImplementationExt.java,v 1.1 2007-08-24 22:17:37 ewestfal Exp $
028 */
029 public interface ImplementationExt extends Implementation
030 {
031 /**
032 * The used collection type class returned by OQL queries.
033 *
034 * @see org.apache.ojb.odmg.oql.EnhancedOQLQuery#execute()
035 * @see org.odmg.OQLQuery#execute()
036 * @return The collection class type
037 */
038 public Class getOqlCollectionClass();
039
040 /**
041 * Set the used collection type class returned by OQL queries.
042 * <p/>
043 * NOTE: Each specified class must implement interface {@link org.apache.ojb.broker.ManageableCollection}
044 * to work proper with OJB.
045 *
046 * @param oqlCollectionClass The collection class used in OQL queries.
047 */
048 public void setOqlCollectionClass(Class oqlCollectionClass);
049
050 /**
051 * If the OJB implicit locking feature (see {@link TransactionExt#setImplicitLocking(boolean)}) is
052 * enabled, this define the lock type of all implicit locked objects.
053 * <p/>
054 * If set to <em>true</em>, acquiring a write-lock on a given object x implies write locks on all
055 * implicit locked objects.
056 * <br/>
057 * If set to <em>false</em>, in any case implicit read-locks are acquired.
058 * Acquiring a read- or write lock on x thus allways results in implicit read-locks
059 * on all associated objects.
060 *
061 * @param impliciteWriteLocks If <em>true</em> implicit write locks will enabled.
062 */
063 public void setImpliciteWriteLocks(boolean impliciteWriteLocks);
064
065 /**
066 * Is <em>true</em> when implicite write locks are enabled.
067 *
068 * @return <em>true</em> when implicit write locks are enabled.
069 * @see #setImpliciteWriteLocks(boolean)
070 */
071 public boolean isImpliciteWriteLocks();
072
073 /**
074 * Set the global property <em>implicit locking</em>. This method can be used
075 * to activate or deactivate the global implicit
076 * locking mechanism.
077 * <br/>
078 * If set <em>true</em> OJB implicitly locks objects to ODMG transactions
079 * after performing OQL queries. Also if implicit locking is used
080 * locking objects is recursive, that is associated objects are also
081 * locked. If ImplicitLocking is set to 'false', no locks are obtained
082 * in OQL queries, lookup objects and there is also no recursive locking.
083 * <p/>
084 * However it's possible to set this value only for the current used {@link org.odmg.Transaction}
085 * using {@link TransactionExt#setImplicitLocking(boolean)} and to detect the implicit locking
086 * state of the used transaction instance call {@link TransactionExt#isImplicitLocking()}.
087 * <br/>
088 * Turning off implicit locking may improve performance but requires
089 * additional care to make sure that all changed objects are properly
090 * registered to the transaction.
091 *
092 * @param impliciteLocking If set <em>true</em> implicit locking is enabled,
093 * if <em>false</em>, implicit locking is disabled.
094 */
095 public void setImplicitLocking(boolean impliciteLocking);
096
097 /**
098 * Returns <em>true</em> if the global implicit locking is enabled
099 * for this {@link org.odmg.Implementation} instance, else <em>false</em>.
100 * <br/>
101 * <strong>Important:</strong> The returned value is the global used setting for all
102 * {@link org.odmg.Transaction#lock(Object, int)} calls.
103 * <br/>
104 * However it's possible to set this value only for the current used {@link org.odmg.Transaction}
105 * using {@link TransactionExt#setImplicitLocking(boolean)} and to detect the implicit locking
106 * state of the used transaction instance call {@link TransactionExt#isImplicitLocking()}.
107 *
108 * @return <em>true</em> if the global property <em>implicit locking</em><em>true</em> is enabled.
109 * @see #setImplicitLocking(boolean)
110 */
111 public boolean isImplicitLocking();
112
113 /**
114 * Returns <em>true</em> if OJB's ordering algorithm is enabled.
115 *
116 * @see #setOrdering(boolean)
117 */
118 public boolean isOrdering();
119
120 /**
121 * Disable/enable OJB's ordering algorithm when insert, update, delete a
122 * bunch of objects within a transaction. The ordering algorithm try to
123 * calculate the correct order of the modified/new persistent objects to
124 * prevent problems on commit of the transaction.
125 * <br/>
126 * If the used databases support 'deferred checks' it's recommended to
127 * use this feature and to disable OJB's object ordering.
128 * <p/>
129 * However it's possible to set this value only for the current
130 * used {@link org.odmg.Transaction} using {@link TransactionExt#setOrdering(boolean)}
131 *
132 * @param ordering If <em>true</em> OJB's ordering algorithm is used.
133 */
134 public void setOrdering(boolean ordering);
135
136 // /**
137 // * Returns whether or not the persistent method calls determine
138 // * the persistent object order on commit.
139 // *
140 // * @see #setNoteUserOrder(boolean)
141 // */
142 // public boolean isNoteUserOrder();
143 //
144 // /**
145 // * If <em>true</em> the order of persisting method calls like
146 // * <br/> - {@link org.odmg.Transaction#lock(Object, int)}).
147 // * <br/> - {@link org.odmg.Database#deletePersistent(Object)}).
148 // * <br/> - {@link org.odmg.Database#makePersistent(Object)})
149 // * determine the order of objects before commit.
150 // * <br/>
151 // * If <em>false</em> the ordering was determined by OJB's internal
152 // * method calls and user calls.
153 // * <br/>
154 // * However it's possible to set this value only for the current
155 // * used {@link org.odmg.Transaction} using {@link TransactionExt#setNoteUserOrder(boolean)}
156 // * <p/>
157 // * <strong>NOTE:</strong> If OJB's ordering algorithm (see
158 // * {@link #setOrdering(boolean)}) is enabled, the
159 // * order of objects may change on commit.
160 // *
161 // * @param noteUserOrder If <em>true</em> the order of persisting
162 // * method calls determine the order of objects.
163 // */
164 // public void setNoteUserOrder(boolean noteUserOrder);
165
166
167 // /**
168 // * Get object by OJB's {@link org.apache.ojb.broker.Identity}.
169 // *
170 // * @param id The identity of the object to look for.
171 // * @return The matching object or <em>null</em>.
172 // */
173 // public Object getObjectByIdentity(Identity id);
174
175 // /**
176 // * If set <em>true</em> the odmg implementation do it's best to find out the user intension, if set
177 // * <em>false</em> OJB use an optimized mode and the user has to adhere strictly the odmg-api:
178 // * <ul>
179 // * <li>
180 // * New objects can only be made persistent by using {@link org.odmg.Database#makePersistent(Object)}
181 // * </li>
182 // * <li>
183 // * Only persistent objects can be locked with {@link org.odmg.Transaction#lock(Object, int)}.
184 // * </li>
185 // * <li>
186 // * When deleting an object with {@link org.odmg.Database#deletePersistent(Object)} to reuse it
187 // * within a transaction a call to {@link org.odmg.Database#makePersistent(Object)} is needed and
188 // * field changes on objects marked as "deleted" are not allowed.
189 // * </li>
190 // * </ul>
191 // * When running odmg in <em>safe-mode</em> these restrictions are "softened" and it's e.g. possible
192 // * to persist new objects with {@link org.odmg.Transaction#lock(Object, int)}.
193 // * <p/>
194 // * The <em>optimized-mode</em> show a significant better performance, but needs strictness in using the API.
195 // *
196 // * @param safeMode Set <em>true</em> to enable the <em>safe-mode</em>, use <em>false</em> to enable
197 // * the <em>optimized-mode</em>.
198 // */
199 // void setSafeMode(boolean safeMode);
200 //
201 // /**
202 // * Returns <em>true</em> if this class use the safe-mode for
203 // * user interaction, else the optimized-mode is used.
204 // */
205 // boolean isSafeMode();
206 }