org.brains2b.data.cursor
Class Cursor

java.lang.Object
  extended by org.brains2b.data.cursor.Cursor
Direct Known Subclasses:
SqlCursor

public abstract class Cursor
extends java.lang.Object

Cursor is the Control class for a valid SQL select statement to be be used as a data class for which we can manipulate the data.

This includes inserting, deleting or selecting data, a bit like an Oracle Cursor.

Usage: Create a new Cursor object with a valid SQL connection and a String containing a valid SQL statement. Cursor c=new Cursor({Valid Connection},"A distinquising name", "SELECT NAME, DEPARTMENT FROM EMP,DEP WHERE NAME.DEP_ID=DEPARTMENT.ID"); After this a Select statement will return a CursorData object. See the javadoc for this object for more information. To get a new CursorData object use c.getNewCursorData()

Limitation: Updating and inserting will only proceed if the underlying database allows this particular operation for the particular query. Usually this only happens when all reference are explicit, all primary keys are set and all non-null values are filled. Cursor will pass the Exception thrown by the database through when there is a problem with mutating data.

Version:
0.23 [16-01-2008]
Author:
dennis@brains2b.nl
See Also:
CursorData

Field Summary
protected  CursorData m_prototype
           
 
Constructor Summary
Cursor(java.lang.String name)
          default constructor
 
Method Summary
abstract  int delete(CursorData cd)
          delete an object of type o from the datastore
 java.lang.String getName()
          get the name for this cursor
 CursorData getNewCursorData()
          Get an new CursorData object for this cursor, which has all the fields for this Cursor defined.
protected  CursorData getObject(CursorData prototype, java.sql.ResultSet rs)
          get a CursorData object filled from the current position in the ResultSet.
abstract  CursorData getProtoType()
          get a prototype for this cursor, which is basically a defintion of the columns and types, but without the values
abstract  int insert(CursorData cd)
          insert an object of type o to the datastore
abstract  CursorData retrieve(Condition condition)
          select an Object of the type of the Object o which match the supplied condition.
abstract  java.util.List retrieveList()
          retrieve a list of Objects of the type of the Object
abstract  java.util.List retrieveList(Condition condition)
          retrieve a list of Objects of the type of the Object o which match the supplied condition.
abstract  int update(CursorData cd)
          update an object of type o to the datastore
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

m_prototype

protected CursorData m_prototype
Constructor Detail

Cursor

public Cursor(java.lang.String name)
default constructor

Parameters:
name - String, a name for this cursor
Method Detail

getNewCursorData

public CursorData getNewCursorData()
Get an new CursorData object for this cursor, which has all the fields for this Cursor defined.

Returns:
CursorData, a new CursorData object which is basically a prototype retrieved from the database. Will return null if the underlying prototype cannot be returned, or if the database throws an Exception.

getProtoType

public abstract CursorData getProtoType()
                                 throws DataException
get a prototype for this cursor, which is basically a defintion of the columns and types, but without the values

Returns:
CursorData
Throws:
DataException

getObject

protected CursorData getObject(CursorData prototype,
                               java.sql.ResultSet rs)
                        throws java.sql.SQLException
get a CursorData object filled from the current position in the ResultSet.

Parameters:
prototype - CursorData, object which functions as a prototype, will be cloned to function as return type.
rs - ResultSet, a resultset with a valid position
Returns:
CursorData, an object with all fields and values set.
Throws:
SQLException, - thrown if the resultset has no current position, or if the database delivers an SQLException
java.sql.SQLException

getName

public java.lang.String getName()
get the name for this cursor

Returns:
String, the name of this cursor

update

public abstract int update(CursorData cd)
                    throws DataException
update an object of type o to the datastore

Parameters:
cd - CursorData, the object to update
Returns:
int, the number or records updated, should always return one
Throws:
DataException, - exception thrown from the specific data store controls, such as a JDBC driver are wrapped within this Exception
DataException
See Also:
DataController.update(Object)

insert

public abstract int insert(CursorData cd)
                    throws DataException
insert an object of type o to the datastore

Parameters:
cd - CursorData, the object to insert
Returns:
int, the number or records inserted, should always return one
Throws:
DataException, - exception thrown from the specific data store controls, such as a JDBC driver are wrapped within this Exception
DataException
See Also:
DataController.insert(Object)

delete

public abstract int delete(CursorData cd)
                    throws DataException
delete an object of type o from the datastore

Parameters:
cd - CursorData, the object to delete
Returns:
int, the number or records deleted, should always return one
Throws:
DataException, - exception thrown from the specific data store controls, such as a JDBC driver are wrapped within this Exception
DataException
See Also:
DataController.delete(Object)

retrieve

public abstract CursorData retrieve(Condition condition)
                             throws DataException
select an Object of the type of the Object o which match the supplied condition.

Parameters:
condition - Condition the condition which should be met by the retrieved objects
Returns:
An object which meets the condition. If more then one object meets the criteria implementations should only return the first one. Should return null if no object meets the condition.
Throws:
DataException, - exception thrown from the specific data store controls, such as a JDBC driver are wrapped within this Exception
DataException
See Also:
DataController.retrieve(Object, Condition), Condition

retrieveList

public abstract java.util.List retrieveList(Condition condition)
                                     throws DataException
retrieve a list of Objects of the type of the Object o which match the supplied condition.

Parameters:
condition - Condition the condition which should be met by the retrieved objects
Returns:
A Vector of Objects which meet the condition. Should return null if no object meets the condition.
Throws:
DataException, - exception thrown from the specific data store controls, such as a JDBC driver are wrapped within this Exception
DataException
See Also:
DataController.retrieveList(Object, Condition), Condition

retrieveList

public abstract java.util.List retrieveList()
                                     throws DataException
retrieve a list of Objects of the type of the Object

Returns:
A list of CursorData which meet the defined cursor condition.
Throws:
DataException, - exception thrown from the specific data store controls, such as a JDBC driver are wrapped within this Exception
DataException