org.tentackle.db
Class SimpleDbCursor<T extends DbObject>

java.lang.Object
  org.tentackle.db.SimpleDbCursor<T>

Type Parameters:

T - the database object class

All Implemented Interfaces:

DbCursor<T>

Direct Known Subclasses:

AppDbCursor, CachedDbCursor

public class SimpleDbCursor<T extends DbObject>
extends Object
implements DbCursor<T>

A simple implementation of a DbCursor.
The cursor operates on a ResultSetWrapper for local connections and on a RemoteDbCursor for remote connections to an application server.

Author:

harald

Field Summary

protected Db	db
protected Class<T>	dbClass
protected T	object
protected RemoteDbCursor	rc
protected String	rcName
protected int	row
protected int	rows
protected ResultSetWrapper	rs
protected boolean	withLinkedObjects

Constructor Summary

SimpleDbCursor(Db db, Class<T> dbClass, ResultSetWrapper rs)
Creates a cursor on a result set for local connections.

SimpleDbCursor(Db db, Class<T> dbClass, ResultSetWrapper rs, boolean withLinkedObjects)
Creates a cursor.

SimpleDbCursor(Db db, RemoteDbCursor rc)
Creates a remote Cursor on the client-side for remote connections.

Method Summary

void	afterLast() Positions the cursor after the last row.
void	beforeFirst() Positions the cursor before the first row.
void	close() Closes the cursor. The cursor is opened in its constructor.
boolean	deleteObject() Removes the object of the current row from the cursor and the server.
boolean	deleteObjectAt(int row) Removes the object a given row from the cursor and the server.
List<T>	fetch() Fetches the next objects up to the fetchsize.
protected void	finalize() Overridden to close forgotten cursors.
boolean	first() Rewinds the cursor to the first row.
Class	getDbClass() Gets the class of the objects in the cursor.
int	getFetchDirection() Gets the fetch direction.
int	getFetchSize() Gets the fetchsize.
T	getObject() Gets the data object of the current row.
T	getObjectAt(int row) Gets an the object at a given row.
int	getRow() Gets the current row.
int	getRowCount() Gets the number of rows. Caution: depending on the implementation this method will have to read all data from the server in order to count the rows.
boolean	isAfterLast() Checks whether the cursor is after the last row.
boolean	isBeforeFirst() Checks whether the cursor is before the first row.
boolean	isOpen() Checks whether cursor is open.
boolean	isRemote() Gets the local/remote type of the cursor.
boolean	last() Positions the cursor on the last row.
T	newObject() Creates a new object.
boolean	next() Moves the cursor to the next row.
boolean	previous() Moves the cursor to the previous row.
void	setDbContext(T object) Sets the db-context for objects retrieved from the remote cursor.
void	setFetchDirection(int direction) Sets the fetch direction.
void	setFetchSize(int rows) Sets the fetchsize.
boolean	setRow(int row) Sets the cursor to a given row.
List<T>	toList() Returns the objects of this cursor as a list.
List<T>	toListAndClose() Returns the objects of this cursor as a list and closes this cursor.
String	toString() Returns a string representation of the object.
void	updateDbContext(T object) Updates the db context in the object after the object has been loaded.
boolean	updateObject(T object) Updates the data object of the current row and persist the change to the server.
boolean	updateObjectAt(T object, int row) Updates the data object at a given row and persist the change to the server.
boolean	updateObjectOnly(T object) Updates the data object of the current row.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

db

protected Db db

dbClass

protected Class<T extends DbObject> dbClass

rs

protected ResultSetWrapper rs

rc

protected RemoteDbCursor rc

rcName

protected String rcName

withLinkedObjects

protected boolean withLinkedObjects

row

protected int row

rows

protected int rows

object

protected T extends DbObject object

Constructor Detail

SimpleDbCursor

public SimpleDbCursor(Db db,
                      Class<T> dbClass,
                      ResultSetWrapper rs,
                      boolean withLinkedObjects)

Creates a cursor.

Parameters:

db - the db connection

dbClass - the DbObject class

rs - the resultset

withLinkedObjects - true if load linked objects, false otherwise

SimpleDbCursor

public SimpleDbCursor(Db db,
                      Class<T> dbClass,
                      ResultSetWrapper rs)

Creates a cursor on a result set for local connections.

Parameters:

db - the db connection

dbClass - the DbObject class

rs - the resultset

SimpleDbCursor

public SimpleDbCursor(Db db,
                      RemoteDbCursor rc)

Creates a remote Cursor on the client-side for remote connections.

Parameters:

db - the remote db connection

rc - the remote cursor

Method Detail

isRemote

public boolean isRemote()

Gets the local/remote type of the cursor.

Returns:

true if cursor is remote, else local

close

public void close()

Closes the cursor.
The cursor is opened in its constructor. Closing an already closed cursor is allowed. This frees also the result set (local or remote).

Specified by:

close in interface DbCursor<T extends DbObject>

isOpen

public boolean isOpen()

Checks whether cursor is open.

Returns:

true if cursor is open

finalize

protected void finalize()
                 throws Throwable

Overridden to close forgotten cursors.

Overrides:

finalize in class Object

Throws:

Throwable - the Exception raised by this method

toString

public String toString()

Description copied from class: java.lang.Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Object

Returns:

a string representation of the object.

getRowCount

public int getRowCount()

Gets the number of rows.
Caution: depending on the implementation this method will have to read all data from the server in order to count the rows. Hence, applications should avoid getRowCount() if possible.

The implementation will move to the end of the cursor to determine the number of rows, if not known yet. Subsequent invocations will use the cached value.

Specified by:

getRowCount in interface DbCursor<T extends DbObject>

Returns:

the number of rows accessible by the cursor

getRow

public int getRow()

Gets the current row. Row numbers start at 1.

Specified by:

getRow in interface DbCursor<T extends DbObject>

Returns:

the current row, 0 if before first row

setRow

public boolean setRow(int row)

Sets the cursor to a given row. Row numbers start at 1.

Specified by:

setRow in interface DbCursor<T extends DbObject>

Parameters:

row - the row number (must be > 0)

Returns:

true if done, false if no such row

first

public boolean first()

Rewinds the cursor to the first row.

Specified by:

first in interface DbCursor<T extends DbObject>

Returns:

true if rewound, false if cursor is empty

last

public boolean last()

Positions the cursor on the last row.

Specified by:

last in interface DbCursor<T extends DbObject>

Returns:

true if positioned, false if cursor is empty

next

public boolean next()

Moves the cursor to the next row. If there are no more rows the current row remains unchanged.

Specified by:

next in interface DbCursor<T extends DbObject>

Returns:

true if moved, false if no more rows

previous

public boolean previous()

Moves the cursor to the previous row. If we are already at the beginning, the cursor remains unchanged.

Specified by:

previous in interface DbCursor<T extends DbObject>

Returns:

true if advanced, false if already at the beginning

beforeFirst

public void beforeFirst()

Positions the cursor before the first row. Works even for empty cursors.

Specified by:

beforeFirst in interface DbCursor<T extends DbObject>

afterLast

public void afterLast()

Positions the cursor after the last row. Works even for empty cursors.

Specified by:

afterLast in interface DbCursor<T extends DbObject>

isBeforeFirst

public boolean isBeforeFirst()

Checks whether the cursor is before the first row.

Specified by:

isBeforeFirst in interface DbCursor<T extends DbObject>

Returns:

true if before first

isAfterLast

public boolean isAfterLast()

Checks whether the cursor is after the last row.

Specified by:

isAfterLast in interface DbCursor<T extends DbObject>

Returns:

true if after last

newObject

public T newObject()

Creates a new object. The object will just be instantiated. The db is no set.

Returns:

the new object

setDbContext

public void setDbContext(T object)

Sets the db-context for objects retrieved from the remote cursor.

Parameters:

object - the DbObject to set the db for, never null

updateDbContext

public void updateDbContext(T object)

Updates the db context in the object after the object has been loaded. Apps may override the method to do further setup. The default implementation does nothing.

Parameters:

object - the DbObject to update the context for, never null

getObject

public T getObject()

Gets the data object of the current row.

The remote server may refuse the delivery of the object due to security constraints. In this case, null is returned.

Specified by:

getObject in interface DbCursor<T extends DbObject>

Returns:

the object, null if invalid row or no such object

updateObjectOnly

public boolean updateObjectOnly(T object)

Updates the data object of the current row. The data will not be written to the server! The object may refuse to be updated.

Specified by:

updateObjectOnly in interface DbCursor<T extends DbObject>

Parameters:

object - the data object

Returns:

true if updated, false if failed

updateObject

public boolean updateObject(T object)

Updates the data object of the current row and persist the change to the server. The object may refuse to be updated and the server update may fail.

Specified by:

updateObject in interface DbCursor<T extends DbObject>

Parameters:

object - the data object

Returns:

true if updated, false if failed

deleteObject

public boolean deleteObject()

Removes the object of the current row from the cursor and the server. The next object becomes the current object. If there is no next object the cursor is positioned to the previous row. The operation may fail if the server cannot delete the object for whatever reason.

Specified by:

deleteObject in interface DbCursor<T extends DbObject>

Returns:

true if deleted, false if failed

getObjectAt

public T getObjectAt(int row)

Gets an the object at a given row. The current row will not be changed.

Specified by:

getObjectAt in interface DbCursor<T extends DbObject>

Parameters:

row - the row starting at 1

Returns:

the object, null if row out of range

updateObjectAt

public boolean updateObjectAt(T object,
                              int row)

Updates the data object at a given row and persist the change to the server. The current row will not be changed. The object may refuse to be updated and the server update may fail.

Specified by:

updateObjectAt in interface DbCursor<T extends DbObject>

Parameters:

object - the data object

row - the row starting at 1

Returns:

true if updated, false if failed

deleteObjectAt

public boolean deleteObjectAt(int row)

Removes the object a given row from the cursor and the server. The current row will not be changed, except when it's the last row (or after last) and the last row is removed. The operation may fail if the server cannot delete the object for whatever reason.

Specified by:

deleteObjectAt in interface DbCursor<T extends DbObject>

Parameters:

row - the row starting at 1

Returns:

true if deleted, false if failed

toList

public List<T> toList()

Returns the objects of this cursor as a list.

Specified by:

toList in interface DbCursor<T extends DbObject>

Returns:

the list (never null)

toListAndClose

public List<T> toListAndClose()

Returns the objects of this cursor as a list and closes this cursor.

Specified by:

toListAndClose in interface DbCursor<T extends DbObject>

Returns:

the list (never null)

getDbClass

public Class getDbClass()

Gets the class of the objects in the cursor.

Specified by:

getDbClass in interface DbCursor<T extends DbObject>

Returns:

the object class

setFetchSize

public void setFetchSize(int rows)

Sets the fetchsize. This is the number of rows the cursor will fetch from the server in one batch. A fetchsize of 0 means server default.

Specified by:

setFetchSize in interface DbCursor<T extends DbObject>

Parameters:

rows - the fetchsize

getFetchSize

public int getFetchSize()

Gets the fetchsize.

Specified by:

getFetchSize in interface DbCursor<T extends DbObject>

Returns:

the fetchsize

setFetchDirection

public void setFetchDirection(int direction)

Sets the fetch direction.

Specified by:

setFetchDirection in interface DbCursor<T extends DbObject>

Parameters:

direction - the direction, see ResultSet.setFetchDirection(int).

getFetchDirection

public int getFetchDirection()

Gets the fetch direction.

Specified by:

getFetchDirection in interface DbCursor<T extends DbObject>

Returns:

the direction

fetch

public List<T> fetch()

Fetches the next objects up to the fetchsize. This method is provided to minimize the number of roundtrips especially for remote cursors. The cursor is closed at the end of the cursor.

If the fetchsize is 0 (auto), the method will fall back to toList. After having read the last row the cursor is closed! This saves two roundtrips for remote dbs.

Specified by:

fetch in interface DbCursor<T extends DbObject>

Returns:

the list of objects, null if no more objects found