Top Description Fields Constructors Methods
com.ziclix.python.sql

public abstract Class Fetch

Additional top-level classes in compilation unit: StaticFetch, DynamicFetch.

extends Object
implements Traverseproc
Class Inheritance
All Implemented Interfaces
org.python.core.Traverseproc
Known Direct Subclasses
com.ziclix.python.sql.StaticFetch, com.ziclix.python.sql.DynamicFetch
Imports
org.python.core.Py, .PyException, .PyInteger, .PyList, .PyObject, .PyTuple, .Traverseproc, .Visitproc, java.sql.CallableStatement, .DatabaseMetaData, .ResultSet, .ResultSetMetaData, .SQLException, .SQLWarning, .Types, java.util.ArrayList, .LinkedList, .List, .Set

The responsibility of a Fetch instance is to manage the iteration of a ResultSet. Two different alogorithms are available: static or dynamic.

Static The static variety iterates the entire set immediately, creating the necessary Jython objects and storing them. It is able to immediately close the ResultSet so a call to close() is essentially a no-op from a database resource perspective (it does clear the results list however). This approach also allows for the correct rowcount to be determined since the entire result set has been iterated.

Dynamic The dynamic variety iterates the result set only as requested. This holds a bit truer to the intent of the API as the fetch*() methods actually fetch when instructed. This is especially useful for managing exeedingly large results, but is unable to determine the rowcount without having worked through the entire result set. The other disadvantage is the ResultSet remains open throughout the entire iteration. So the tradeoff is in open database resources versus JVM resources since the application can keep constant space if it doesn't require the entire result set be presented as one.

Author
brian zimmer

Field Summary

Modifier and TypeField and Description
private DataHandler
datahandler

Field cursor

protected PyObject
description

Field description

private List<WarningListener>
listeners

A list of warning listeners.

protected int
rowcount

The total number of rows in the result set.

protected int
rownumber

The current row of the cursor (-1 if off either end).

Constructor Summary

AccessConstructor and Description
protected
Fetch(DataHandler datahandler)

Constructor Fetch

Method Summary

Modifier and TypeMethod and Description
public abstract void
add(ResultSet resultSet)

Create the results after a successful execution and manages the result set.

public abstract void
add(ResultSet resultSet, Set<Integer>
JDBC-indexed set of columns to be skipped
skipCols)

Create the results after a successful execution and manages the result set.

public abstract void
add(CallableStatement callableStatement, Procedure procedure, PyObject params)

Method add

public void
addWarningListener(WarningListener listener)

public void
close()

Cleanup any resources.

protected PyObject
createDescription(ResultSetMetaData meta)

Builds a tuple containing the meta-information about each column.

protected PyObject
createDescription(Procedure procedure)

Builds a tuple containing the meta-information about each column.

protected PyTuple

Returns:

a tuple of the results
createResult(ResultSet
result set
set, Set<Integer>
set of JDBC-indexed columns to automatically set to None
skipCols, PyObject metaData)

Creates the individual result row from the current ResultSet row.

protected PyObject

Returns:

PyObject
createResults(CallableStatement callableStatement, Procedure procedure, PyObject params)

Method createResults

protected PyList

Returns:

a list of tuples of the results
createResults(ResultSet
result set
set, Set<Integer>
set of JDBC-indexed columns to automatically set to None
skipCols, PyObject metaData)

Creates the results of a query.

public abstract PyObject

Returns:

a sequence of sequences from the result set, or None when no more data is available
fetchall()

Fetch all (remaining) rows of a query result, returning them as a sequence of sequences (e.g. a list of tuples).

public abstract PyObject

Returns:

a sequence of sequences from the result set, or None when no more data is available
fetchmany(int size)

Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples).

public PyObject

Returns:

a single sequence from the result set, or None when no more data is available
fetchone()

Fetch the next row of a query result set, returning a single sequence, or None when no more data is available.

protected void
fireWarning(SQLWarning warning)

public PyObject
getDescription()

The description of each column, in order, for the data in the result set.

public int
getRowCount()

The number of rows in the current result set.

public static Fetch

Returns:

Fetch
newFetch(DataHandler datahandler, boolean dynamic)

Method newFetch

public abstract PyObject

Returns:

true if more sets exist, else None
nextset()

Move the result pointer to the next set if available.

public boolean
refersDirectlyTo(PyObject ob)

Implements org.python.core.Traverseproc.refersDirectlyTo.

Optional operation.

public boolean
removeWarningListener(WarningListener listener)

public abstract void
scroll(int value, String mode)

Scroll the cursor in the result set to a new position according to mode.

public int
traverse(Visitproc visit, Object arg)

Implements org.python.core.Traverseproc.traverse.

Traverses all directly contained PyObjects.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

datahandlerback to summary
private DataHandler datahandler

Field cursor

descriptionback to summary
protected PyObject description

Field description

listenersback to summary
private List<WarningListener> listeners

A list of warning listeners.

rowcountback to summary
protected int rowcount

The total number of rows in the result set.

Note

since JDBC provides no means to get this information without iterating the entire result set, only those fetches which build the result statically will have an accurate row count.

rownumberback to summary
protected int rownumber

The current row of the cursor (-1 if off either end).

Constructor Detail

Fetchback to summary
protected Fetch(DataHandler datahandler)

Constructor Fetch

Method Detail

addback to summary
public abstract void add(ResultSet resultSet)

Create the results after a successful execution and manages the result set.

addback to summary
public abstract void add(ResultSet resultSet, Set<Integer> skipCols)

Create the results after a successful execution and manages the result set. Optionally takes a set of JDBC-indexed columns to automatically set to None primarily to support getTypeInfo() which sets a column type of a number but doesn't use the value so a driver is free to put anything it wants there.

Parameters
skipCols:Set<Integer>

JDBC-indexed set of columns to be skipped

addback to summary
public abstract void add(CallableStatement callableStatement, Procedure procedure, PyObject params)

Method add

addWarningListenerback to summary
public void addWarningListener(WarningListener listener)
closeback to summary
public void close() throws SQLException

Cleanup any resources.

createDescriptionback to summary
protected PyObject createDescription(ResultSetMetaData meta) throws SQLException

Builds a tuple containing the meta-information about each column.

(name, type_code, display_size, internal_size, precision, scale, null_ok)

precision and scale are only available for numeric types

createDescriptionback to summary
protected PyObject createDescription(Procedure procedure) throws SQLException

Builds a tuple containing the meta-information about each column.

(name, type_code, display_size, internal_size, precision, scale, null_ok)

precision and scale are only available for numeric types

createResultback to summary
protected PyTuple createResult(ResultSet set, Set<Integer> skipCols, PyObject metaData) throws SQLException

Creates the individual result row from the current ResultSet row.

Parameters
set:ResultSet

result set

skipCols:Set<Integer>

set of JDBC-indexed columns to automatically set to None

Returns:PyTuple

a tuple of the results

createResultsback to summary
protected PyObject createResults(CallableStatement callableStatement, Procedure procedure, PyObject params) throws SQLException

Method createResults

Returns:PyObject

PyObject

createResultsback to summary
protected PyList createResults(ResultSet set, Set<Integer> skipCols, PyObject metaData) throws SQLException

Creates the results of a query. Iterates through the list and builds the tuple.

Parameters
set:ResultSet

result set

skipCols:Set<Integer>

set of JDBC-indexed columns to automatically set to None

Returns:PyList

a list of tuples of the results

fetchallback to summary
public abstract PyObject fetchall()

Fetch all (remaining) rows of a query result, returning them as a sequence of sequences (e.g. a list of tuples). Note that the cursor's arraysize attribute can affect the performance of this operation.

An Error (or subclass) exception is raised if the previous call to executeXXX() did not produce any result set or no call was issued yet.

Returns:PyObject

a sequence of sequences from the result set, or None when no more data is available

fetchmanyback to summary
public abstract PyObject fetchmany(int size)

Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples). An empty sequence is returned when no more rows are available.

The number of rows to fetch per call is specified by the parameter. If it is not given, the cursor's arraysize determines the number of rows to be fetched. The method should try to fetch as many rows as indicated by the size parameter. If this is not possible due to the specified number of rows not being available, fewer rows may be returned.

An Error (or subclass) exception is raised if the previous call to executeXXX() did not produce any result set or no call was issued yet.

Note there are performance considerations involved with the size parameter. For optimal performance, it is usually best to use the arraysize attribute. If the size parameter is used, then it is best for it to retain the same value from one fetchmany() call to the next.

Returns:PyObject

a sequence of sequences from the result set, or None when no more data is available

fetchoneback to summary
public PyObject fetchone()

Fetch the next row of a query result set, returning a single sequence, or None when no more data is available.

An Error (or subclass) exception is raised if the previous call to executeXXX() did not produce any result set or no call was issued yet.

Returns:PyObject

a single sequence from the result set, or None when no more data is available

fireWarningback to summary
protected void fireWarning(SQLWarning warning)
getDescriptionback to summary
public PyObject getDescription()

The description of each column, in order, for the data in the result set.

getRowCountback to summary
public int getRowCount()

The number of rows in the current result set.

newFetchback to summary
public static Fetch newFetch(DataHandler datahandler, boolean dynamic)

Method newFetch

Returns:Fetch

Fetch

nextsetback to summary
public abstract PyObject nextset()

Move the result pointer to the next set if available.

Returns:PyObject

true if more sets exist, else None

refersDirectlyToback to summary
public boolean refersDirectlyTo(PyObject ob) throws UnsupportedOperationException

Implements org.python.core.Traverseproc.refersDirectlyTo.

Doc from org.python.core.Traverseproc.refersDirectlyTo.

Optional operation. Should only be implemented if it is more efficient than calling traverse(Visitproc, Object) with a visitproc that just watches out for ob. Must return false if ob is null.

removeWarningListenerback to summary
public boolean removeWarningListener(WarningListener listener)
scrollback to summary
public abstract void scroll(int value, String mode)

Scroll the cursor in the result set to a new position according to mode.

If mode is 'relative' (default), value is taken as offset to the current position in the result set, if set to 'absolute', value states an absolute target position.

An IndexError should be raised in case a scroll operation would leave the result set. In this case, the cursor position is left undefined (ideal would be to not move the cursor at all).

Note

This method should use native scrollable cursors, if available, or revert to an emulation for forward-only scrollable cursors. The method may raise NotSupportedErrors to signal that a specific operation is not supported by the database (e.g. backward scrolling).

traverseback to summary
public int traverse(Visitproc visit, Object arg)

Implements org.python.core.Traverseproc.traverse.

Doc from org.python.core.Traverseproc.traverse.

Traverses all directly contained PyObjects. Like in CPython, arg must be passed unmodified to visit as its second parameter. If Visitproc#visit(PyObject, Object) returns nonzero, this return value must be returned immediately by traverse. Visitproc#visit(PyObject, Object) must not be called with a null PyObject-argument.