KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > genimen > djeneric > repository > DjCursor


1 /*
2  * Copyright (c) 2001-2005 by Genimen BV (www.genimen.com) All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without modification, is permitted
5  * provided that the following conditions are met:
6  * - Redistributions of source code must retain the above copyright notice, this list of conditions
7  * and the following disclaimer.
8  * - Redistributions in binary form must reproduce the above copyright notice, this list of
9  * conditions and the following disclaimer in the documentation and/or other materials
10  * provided with the distribution.
11  * - All advertising materials mentioning features or use of this software must display the
12  * following acknowledgment: "This product includes Djeneric."
13  * - Products derived from this software may not be called "Djeneric" nor may
14  * "Djeneric" appear in their names without prior written permission of Genimen BV.
15  * - Redistributions of any form whatsoever must retain the following acknowledgment: "This
16  * product includes Djeneric."
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS"
19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL GENIMEN BV, DJENERIC.ORG,
22  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 package com.genimen.djeneric.repository;
31
32 import com.genimen.djeneric.repository.exceptions.DjenericException;
33
34 /**
35  * A cursor can be used to retrieve a large set of objects; without the need
36  * to load them all in memory at once. Long running batches that process a large
37  * number of objects will want to use cursors to avoid the memory overhead at the
38  * cost of a slight cpu overhead.
39  * Another benefit of using cursors is that you can stop processing half way the
40  * set; effectively limiting the number of objects to process to a maximum number.
41  * Be aware that you should close cursors when done; this will free resources allocated
42  * by/for the persistent store.
43  *
44  *@author Wido Riezebos
45  *@created 24 mei 2002
46  */
47 public abstract class DjCursor
48 {
49   private DjSession _session;
50   private DjList _newObjects;
51   private String JavaDoc _idColumnName;
52   private boolean _forceReloadFromDB;
53   private DjExtent _extent;
54
55   /**
56    * Returns the next object
57    *
58    *@return The next object
59    *@exception DjenericException Description of the Exception
60    */
61   public abstract DjObject getNext() throws DjenericException;
62
63   /**
64    * Closes the cursor, freeing any resources
65    *
66    *@exception DjenericException Description of the Exception
67    */
68   public abstract void close() throws DjenericException;
69
70   /**
71    * Constructor for the DjCursor object
72    *
73    *@param session The session for use by the cursor
74    *@param extent The extent this cursor is traversing
75    *@param sessionObjects A list a new objects that are not in the persistent store yet
76    *@param forceReloadFromDB Force a reload from the persistent store
77    *@exception DjenericException Description of the Exception
78    */
79   protected DjCursor(DjSession session, DjExtent extent, DjList sessionObjects, boolean forceReloadFromDB)
80       throws DjenericException
81   {
82     _session = session;
83     _forceReloadFromDB = forceReloadFromDB;
84     _extent = extent;
85     _newObjects = new DjList();
86     _newObjects.setStoredTypeName(extent);
87     _newObjects.addAll(sessionObjects);
88     _idColumnName = extent.getIdProperty().getName();
89   }
90
91   /**
92    * Returns the extent this cursor is traversing
93    *
94    *@return The extent value
95    */
96   public DjExtent getExtent()
97   {
98     return _extent;
99   }
100
101   /**
102    * Returns the session this cursor uses
103    *
104    *@return The session value
105    */
106   protected DjSession getSession()
107   {
108     return _session;
109   }
110
111   /**
112    * Returns the list of new objects that will be returned by the cursor in
113    * addition to the objects retrieved from the persistent store
114    *
115    *@return The new objects present in the session but not yet persisted
116    */
117   protected DjList getSessionObjects()
118   {
119     return _newObjects;
120   }
121
122   /**
123    * Returns the name of the id column of the extent.
124    *
125    *@return The idColumnName value
126    */
127   protected String JavaDoc getIdColumnName()
128   {
129     return _idColumnName;
130   }
131
132   /**
133    * Returns true if objects returned should be reloaded (refreshed)
134    * from the persistent store
135    *
136    *@return True if objects returned should be reloaded
137    */
138   protected boolean isForceReloadFromDB()
139   {
140     return _forceReloadFromDB;
141   }
142
143 }
Popular Tags