org.brains2b.data.cursor

Class Cursor

java.lang.Object

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

Fields

Modifier and Type	Field and Description
protected CursorData	m_prototype

Constructor Summary

Constructors

Constructor and Description
Cursor(java.lang.String name) default constructor

Method Summary

Modifier and Type	Method and Description
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:

java.sql.SQLException - thrown if the resultset has no current position, or if the database delivers an 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

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

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

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

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

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