VersantPersistenceManagerFactory


1   
2   /*
3    * Copyright (c) 1998 - 2005 Versant Corporation
4    * All rights reserved. This program and the accompanying materials
5    * are made available under the terms of the Eclipse Public License v1.0
6    * which accompanies this distribution, and is available at
7    * http://www.eclipse.org/legal/epl-v10.html
8    *
9    * Contributors:
10   * Versant Corporation - initial API and implementation
11   */
12  package com.versant.core.jdo;
13  
14  import com.versant.core.logging.LogEvent;
15  import com.versant.core.metric.Metric;
16  import com.versant.core.metric.MetricSnapshotPacket;
17  import com.versant.core.server.DataStoreInfo;
18  
19  import javax.jdo.PersistenceManagerFactory;
20  import java.sql.Connection  ;
21  import java.sql.SQLException  ;
22  import java.util.Collection  ;
23  import java.util.List  ;
24  
25  /**
26   * JDO Genie extension to the PersistenceManagerFactory interface. This adds
27   * methods for monitoring a JDO Genie server, controlling event logging,
28   * changing the cache size etc. To use this just cast the PMF to this and
29   * call the methods.
30   */
31  public interface VersantPersistenceManagerFactory
32          extends PersistenceManagerFactory {
33  
34      public static final String   PROP_DRIVER_NAME = "javax.jdo.option.ConnectionDriverName";
35      public static final String   PROP_USER_NAME = "javax.jdo.option.ConnectionUserName";
36      public static final String   PROP_PASSWORD = "javax.jdo.option.ConnectionPassword";
37      public static final String   PROP_URL = "javax.jdo.option.ConnectionURL";
38      public static final String   PROP_FACTORY_NAME = "javax.jdo.option.ConnectionFactoryName";
39      public static final String   PROP_FACTORY2_NAME = "javax.jdo.option.ConnectionFactory2Name";
40  
41      public static final int EVENT_ERRORS = 1;
42      public static final int EVENT_NORMAL = 2;
43      public static final int EVENT_VERBOSE = 3;
44      public static final int EVENT_ALL = 4;
45  
46      /**
47       * Obtain a JDBC connection from the pool for the datastore. If the
48       * datastore name is null then the default datastore is used. You must
49       * close the connection at some point to return it to the pool. The
50       * connection has no transaction association and autoCommit will be set
51       * to false. If JDBC event logging is on then operations on the connection
52       * will be logged. This method is not available to remote clients and a
53       * JDOUserException is thrown if it is called by a remote client or if
54       * the datastore does not exist.
55       */
56      public Connection   getJdbcConnection(String   datastore)
57              throws SQLException  ;
58  
59      /**
60       * Close all connections in the pool for the datastore. Connections
61       * currently in use are not closed. If datastore is null then the
62       * connections for the default datastore are closed. Any errors
63       * encountered closing the connections are silently discarded. If you
64       * know backups happen at 3am and the database is restarted then you
65       * can schedule a call to this method to get rid of the stale
66       * connections in the pool.
67       */
68      public void clearConnectionPool(String   datastore);
69  
70      /**
71       * Associate a user object with this PMF. Note that if the PMF is local
72       * then there is one object for the whole server. If the PMF is remote
73       * then there is one object per remote connection (i.e. client). For
74       * remote PMFs the object must be Serializable. This is typically used
75       * to identify remote clients in some way (e.g. the logged on user or a
76       * remote stub to communicate with the client).
77       *
78       * @see #getUserObject()
79       */
80      public void setUserObject(Object   o);
81  
82      /**
83       * Get the user object.
84       *
85       * @see #setUserObject
86       */
87      public Object   getUserObject();
88  
89      /**
90       * Is access to loaded default fetch group fields always intercepted?
91       * See the "Cache Management" chapter of the manual for more information
92       * on this flag.
93       */
94      public boolean isInterceptDfgFieldAccess();
95  
96      /**
97       * Control interception of loaded default fetch group fields.
98       * See the "Cache Management" chapter of the manual for more information
99       * on this flag.
100      */
101     public void setInterceptDfgFieldAccess(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, boolean includeSubclasses);
392 
393     /**
394      * Configure the encoder with PersistenceDelegate's for JDO Genie SCO
395      * instances. The java.beans package was only added in JDK 1.4.
396      *
397      * @see java.beans.Encoder
398      */
399     public void registerSCOPersistenceDelegates(Object   encoder);
400 
401     /**
402      * Get the type of reference used to reference instances in the local
403      * PM cache by PMs returned by this factory. 
404      *
405      * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_WEAK
406      * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_SOFT
407      * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_STRONG
408      */
409     public int getPmCacheRefType();
410 
411     /**
412      * Set the type of reference used to reference instances in the local
413      * PM cache by PMs returned by this factory. This can also be changed
414      * for each PM using
415      * {@link com.versant.core.jdo.VersantPersistenceManager#setPmCacheRefType(int)}.
416      *
417      * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_WEAK
418      * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_SOFT
419      * @see com.versant.core.jdo.VersantPersistenceManager#PM_CACHE_REF_TYPE_STRONG
420      */
421     public void setPmCacheRefType(int pmCacheRefType);
422 
423     /**
424      * This method is for internal testing. Get information about the
425      * datastore. If the datastore parameter is null the information about the
426      * default datastore is returned.
427      */
428     public DataStoreInfo getDataStoreInfo(String   datastore);
429 
430     /**
431      * This PersistenceManagerFactory method adds the listener to the list of
432      * lifecycle event listeners set as the initial listeners for each
433      * PersistenceManager created by this PersistenceManagerFactory. The
434      * classes parameter identifies all of the classes of interest. If the
435      * classes parameter is specified as null, events for all persistent
436      * classes and interfaces are generated. If the classes specified have
437      * persistence-capable subclasses, all such subclasses are registered
438      * implicitly. The listener will be called for each event for which it
439      * implements the corresponding listener interface.
440      */
441     public void addLifecycleListener(LifecycleListener listener,
442             Class  [] classes);
443 
444     /**
445      * This PersistenceManagerFactory method removes the listener from the
446      * list of event listeners set as the initial listeners for each
447      * PersistenceManager created by this PersistenceManagerFactory.
448      */
449     public void removeLifecycleListener(LifecycleListener listener);
450 
451 
452     /**
453      * Create a ejb3 EntityManagerFactory.
454      */
455     public Object   getEntityManagerFactory();
456 
457 }
458
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags