001: /*
002: * Copyright (c) 1998 - 2005 Versant Corporation
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * Versant Corporation - initial API and implementation
010: */
011: package com.versant.core.jdo;
012:
013: import com.versant.core.logging.LogEvent;
014: import com.versant.core.metric.Metric;
015: import com.versant.core.metric.MetricSnapshotPacket;
016: import com.versant.core.server.DataStoreInfo;
017:
018: import javax.jdo.PersistenceManagerFactory;
019: import java.sql.Connection;
020: import java.sql.SQLException;
021: import java.util.Collection;
022: import java.util.List;
023:
024: /**
025: * JDO Genie extension to the PersistenceManagerFactory interface. This adds
026: * methods for monitoring a JDO Genie server, controlling event logging,
027: * changing the cache size etc. To use this just cast the PMF to this and
028: * call the methods.
029: */
030: public interface VersantPersistenceManagerFactory extends
031: PersistenceManagerFactory {
032:
033: public static final String PROP_DRIVER_NAME = "javax.jdo.option.ConnectionDriverName";
034: public static final String PROP_USER_NAME = "javax.jdo.option.ConnectionUserName";
035: public static final String PROP_PASSWORD = "javax.jdo.option.ConnectionPassword";
036: public static final String PROP_URL = "javax.jdo.option.ConnectionURL";
037: public static final String PROP_FACTORY_NAME = "javax.jdo.option.ConnectionFactoryName";
038: public static final String PROP_FACTORY2_NAME = "javax.jdo.option.ConnectionFactory2Name";
039:
040: public static final int EVENT_ERRORS = 1;
041: public static final int EVENT_NORMAL = 2;
042: public static final int EVENT_VERBOSE = 3;
043: public static final int EVENT_ALL = 4;
044:
045: /**
046: * Obtain a JDBC connection from the pool for the datastore. If the
047: * datastore name is null then the default datastore is used. You must
048: * close the connection at some point to return it to the pool. The
049: * connection has no transaction association and autoCommit will be set
050: * to false. If JDBC event logging is on then operations on the connection
051: * will be logged. This method is not available to remote clients and a
052: * JDOUserException is thrown if it is called by a remote client or if
053: * the datastore does not exist.
054: */
055: public Connection getJdbcConnection(String datastore)
056: throws SQLException;
057:
058: /**
059: * Close all connections in the pool for the datastore. Connections
060: * currently in use are not closed. If datastore is null then the
061: * connections for the default datastore are closed. Any errors
062: * encountered closing the connections are silently discarded. If you
063: * know backups happen at 3am and the database is restarted then you
064: * can schedule a call to this method to get rid of the stale
065: * connections in the pool.
066: */
067: public void clearConnectionPool(String datastore);
068:
069: /**
070: * Associate a user object with this PMF. Note that if the PMF is local
071: * then there is one object for the whole server. If the PMF is remote
072: * then there is one object per remote connection (i.e. client). For
073: * remote PMFs the object must be Serializable. This is typically used
074: * to identify remote clients in some way (e.g. the logged on user or a
075: * remote stub to communicate with the client).
076: *
077: * @see #getUserObject()
078: */
079: public void setUserObject(Object o);
080:
081: /**
082: * Get the user object.
083: *
084: * @see #setUserObject
085: */
086: public Object getUserObject();
087:
088: /**
089: * Is access to loaded default fetch group fields always intercepted?
090: * See the "Cache Management" chapter of the manual for more information
091: * on this flag.
092: */
093: public boolean isInterceptDfgFieldAccess();
094:
095: /**
096: * Control interception of loaded default fetch group fields.
097: * See the "Cache Management" chapter of the manual for more information
098: * on this flag.
099: */
100: public void setInterceptDfgFieldAccess(
101: boolean interceptDfgFieldAccess);
102:
103: /**
104: * Is closing a PersistenceManager with a active tx is allowed? The
105: * default is false.
106: *
107: * @see #setAllowPmCloseWithTxOpen(boolean)
108: */
109: public boolean isAllowPmCloseWithTxOpen();
110:
111: /**
112: * Allow the closing of a PersistenceManager with active tx. The default
113: * is to not allow it.
114: */
115: public void setAllowPmCloseWithTxOpen(boolean allowed);
116:
117: /**
118: * Are bidirectional relationships (one-to-many, many-to-many) checked for
119: * consistency on commit for new PersistenceManagers? The default is false.
120: *
121: * @see #setCheckModelConsistencyOnCommit(boolean)
122: * @see com.versant.core.jdo.VersantPersistenceManager#isCheckModelConsistencyOnCommit()
123: */
124: public boolean isCheckModelConsistencyOnCommit();
125:
126: /**
127: * Enable or disable commit time consistency checking for bidirectional
128: * relationships (one-to-many, many-to-many) in newly created
129: * PersistenceManagers. When this flag is enabled commiting with an
130: * incorrectly completed bidirectional relationship will trigger a
131: * JDOUserException. This check is expensive and should only be enabled
132: * during development.
133: * @see com.versant.core.jdo.VersantPersistenceManager#setCheckModelConsistencyOnCommit(boolean)
134: */
135: public void setCheckModelConsistencyOnCommit(boolean on);
136:
137: /**
138: * Associate a user object with the JDO Genie server. Note that if the PMF
139: * is local then this method just calls setUserObject. This method makes
140: * it possible for a remote client to change the user object associated
141: * with the local PMF on the server.
142: *
143: * @see #getServerUserObject()
144: * @see #setUserObject(Object)
145: */
146: public void setServerUserObject(Object o);
147:
148: /**
149: * Get the user object associated with the JDO Genie server. Note that if
150: * the PMF is local then this is the same object as returned by
151: * getUserObject. If the PMF is remote then this is the user object
152: * associated with the local PMF on the server. For the remote case
153: * the user object must be serializable. Typically it will be a remote
154: * object providing services to remote clients. Making it available
155: * through this method avoids having to register it with the RMI registry
156: * or some other naming service.
157: *
158: * @see #setServerUserObject(Object)
159: */
160: public Object getServerUserObject();
161:
162: /**
163: * Shutdown the JDO Genie server.
164: */
165: public void shutdown();
166:
167: /**
168: * Get all performance events newer than lastId or all events if lastId is
169: * 0. If no new events are available null is returned.
170: */
171: public LogEvent[] getNewPerfEvents(int lastId);
172:
173: /**
174: * Get server status information bean. For much more detailed information
175: * on the state of the server use {@link #getNewMetricSnapshots(int) }.
176: */
177: public PmfStatus getPmfStatus();
178:
179: /**
180: * Get all the performance metrics configured on the server.
181: *
182: * @see #getNewMetricSnapshots(int)
183: */
184: public Metric[] getMetrics();
185:
186: /**
187: * Get all performance metric snapshots newer that lastId or all
188: * available data if lastId is 0. If no new data is available then null
189: * is be returned.
190: *
191: * @see #getMetrics()
192: * @see #getMostRecentMetricSnapshot(int)
193: */
194: public MetricSnapshotPacket getNewMetricSnapshots(int lastId);
195:
196: /**
197: * Get the most recent performance metric snapshot since the one with ID
198: * of lastId. If no new data is available then null is be returned. If
199: * lastId is 0 then the most recent snapshot is returned.
200: *
201: * @see #getMetrics()
202: * @see #getNewMetricSnapshots(int)
203: */
204: public MetricSnapshotPacket getMostRecentMetricSnapshot(int lastId);
205:
206: /**
207: * Set the value of the named user-defined metric.
208: *
209: * @see #incUserMetric
210: */
211: public void setUserMetric(String name, int value);
212:
213: /**
214: * Add delta to the value of the named user-defined metric.
215: *
216: * @see #setUserMetric
217: */
218: public void incUserMetric(String name, int delta);
219:
220: /**
221: * Get the value of the named user-defined metric. Note that the values for
222: * all user-defined metrics are returned with each set of samples in
223: * {@link #getNewMetricSnapshots(int) }.
224: */
225: public int getUserMetric(String name);
226:
227: /**
228: * Log a user defined event. If the event logging level does not match
229: * the level parameter then the event is ignored. For remote PMs this
230: * check is done on the server so a network call is required even if the
231: * event is not logged.
232: *
233: * @see #EVENT_ERRORS
234: * @see #EVENT_NORMAL
235: * @see #EVENT_VERBOSE
236: * @see #EVENT_ALL
237: */
238: public void logEvent(int level, String description, int ms);
239:
240: /**
241: * Call System.gc() in the VM that the JDO Genie server associated with
242: * this PMF is running in.
243: */
244: public void doSystemGC();
245:
246: /**
247: * Get a tree of all the configurable properties of the server and their
248: * current values.
249: */
250: public PropertyInfo getServerConfiguration();
251:
252: /**
253: * Change a property on a component of the server (e.g. the cache). If
254: * the return value is null then the change was sucessful otherwise it
255: * is an error message.
256: *
257: * @param beanPath The path to the bean property to change (build this
258: * using the name of each bean in the path and the name of the
259: * property)
260: * @param value The new value for the property
261: */
262: public String setServerProperty(String[] beanPath, String value);
263:
264: /**
265: * Get status information on all active remote clients.
266: */
267: public RemoteClientStatus[] getRemoteClients();
268:
269: /**
270: * Get status information on all active PersistenceManager's.
271: */
272: public List getPersistenceManagers();
273:
274: /**
275: * Evict all information for an OID from the PMF wide cache. This is a NOP
276: * if there is no information in the cache for the OID.
277: *
278: * @param oid OID of the JDO instance to be evicted
279: */
280: public void evict(Object oid);
281:
282: /**
283: * Evict all information for an array of OIDs from the PMF wide cache.
284: *
285: * @param oids OIDs of the JDO instances to be evicted
286: */
287: public void evictAll(Object[] oids);
288:
289: /**
290: * Evict all information for a collection of OIDs from the PMF wide cache.
291: *
292: * @param oids Collection of OIDs of the JDO instances to be evicted
293: */
294: public void evictAll(Collection oids);
295:
296: /**
297: * Evict all information for all JDO instances of a Class from the PMF wide
298: * cache.
299: *
300: * @param cls Class of JDO instances to be evicted
301: * @param includeSubclasses If true then instances of subclasses are also
302: * evicted
303: */
304: public void evictAll(Class cls, boolean includeSubclasses);
305:
306: /**
307: * Evict all JDO instances from the PMF wide cache.
308: */
309: public void evictAll();
310:
311: /**
312: * Is the OID in the PMF wide cache? Note that it may already be gone
313: * even if this call returns true. This is for our unit tests.
314: */
315: public boolean isInCache(Object oid);
316:
317: /**
318: * Get the classid for the class. This is a positive int generated from
319: * a hash of the class name. It is used as part of the OID string for
320: * datastore identity classes and in jdo_class columns in inheritance
321: * heirachies. A JDOUserException is thrown if cls is not persistent.
322: *
323: * @see #getClassForID
324: * @see #getJdbcClassID
325: * @see #getClassIndex
326: */
327: public int getClassID(Class cls);
328:
329: /**
330: * Get the Class for the classid. A JDOUserException is thrown if the
331: * classid is invalid.
332: *
333: * @see #getClassID
334: * @see #getClassForJdbcID
335: * @see #getClassForIndex
336: */
337: public Class getClassForID(int classid);
338:
339: /**
340: * Get the JDBC classid for the class. If the class is part of an
341: * inheritance heirachy then this is the value of the jdbc-class column
342: * that identifies instances of the class. The default value is the
343: * classid for the class but this can be changed using the jdbc-class-id
344: * extension in the meta data.
345: *
346: * @see #getClassForJdbcID
347: * @see #getClassID
348: * @see #getClassIndex
349: */
350: public Object getJdbcClassID(Class cls);
351:
352: /**
353: * Get the Class for the jdbc-class-id for a class in the heirachy
354: * starting at baseClass. A JDOUserException is thrown if the jdbc-class-id
355: * is invalid.
356: *
357: * @see #getJdbcClassID
358: * @see #getClassForID
359: * @see #getClassForIndex
360: */
361: public Class getClassForJdbcID(Class baseClass, Object jdbcClassid);
362:
363: /**
364: * Get the class index for the class. This is an int between 0 and the
365: * number of perstent classes less 1. It is appropriate for short term
366: * representation of a class. It will change as new persistent classes
367: * are added to the model. A JDOUserException is thrown if cls is not
368: * persistent.
369: *
370: * @see #getClassForIndex
371: * @see #getClassID
372: * @see #getJdbcClassID
373: */
374: public int getClassIndex(Class cls);
375:
376: /**
377: * Get the Class for a class index. An JDOUserException exception
378: * is thrown if the index is invalid.
379: *
380: * @see #getClassIndex
381: * @see #getClassForID
382: * @see #getClassForJdbcID
383: */
384: public Class getClassForIndex(int index);
385:
386: /**
387: * Convert an array of Class'es into their class indexes. If
388: * includeSubclasses is true then this will recursively get the indexes
389: * for all the subclasses in each heirachy.
390: */
391: public int[] getClassIndexes(Class[] classes,
392: boolean includeSubclasses);
393:
394: /**
395: * Configure the encoder with PersistenceDelegate's for JDO Genie SCO
396: * instances. The java.beans package was only added in JDK 1.4.
397: *
398: * @see java.beans.Encoder
399: */
400: public void registerSCOPersistenceDelegates(Object encoder);
401:
402: /**
403: * Get the type of reference used to reference instances in the local
404: * PM cache by PMs returned by this factory.
405: *
406: * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_WEAK
407: * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_SOFT
408: * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_STRONG
409: */
410: public int getPmCacheRefType();
411:
412: /**
413: * Set the type of reference used to reference instances in the local
414: * PM cache by PMs returned by this factory. This can also be changed
415: * for each PM using
416: * {@link com.versant.core.jdo.VersantPersistenceManager#setPmCacheRefType(int)}.
417: *
418: * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_WEAK
419: * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_SOFT
420: * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_STRONG
421: */
422: public void setPmCacheRefType(int pmCacheRefType);
423:
424: /**
425: * This method is for internal testing. Get information about the
426: * datastore. If the datastore parameter is null the information about the
427: * default datastore is returned.
428: */
429: public DataStoreInfo getDataStoreInfo(String datastore);
430:
431: /**
432: * This PersistenceManagerFactory method adds the listener to the list of
433: * lifecycle event listeners set as the initial listeners for each
434: * PersistenceManager created by this PersistenceManagerFactory. The
435: * classes parameter identifies all of the classes of interest. If the
436: * classes parameter is specified as null, events for all persistent
437: * classes and interfaces are generated. If the classes specified have
438: * persistence-capable subclasses, all such subclasses are registered
439: * implicitly. The listener will be called for each event for which it
440: * implements the corresponding listener interface.
441: */
442: public void addLifecycleListener(LifecycleListener listener,
443: Class[] classes);
444:
445: /**
446: * This PersistenceManagerFactory method removes the listener from the
447: * list of event listeners set as the initial listeners for each
448: * PersistenceManager created by this PersistenceManagerFactory.
449: */
450: public void removeLifecycleListener(LifecycleListener listener);
451:
452: /**
453: * Create a ejb3 EntityManagerFactory.
454: */
455: public Object getEntityManagerFactory();
456:
457: }
|