Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.store.access.sort.SortBufferRowSource

Modifier and Type	Field and Description
private int	maxFreeListSize
pack-priv SortBuffer	sortBuffer The Sort buffer where rows come from
private SortObserver	sortObserver
protected TransactionManager	tran The TransactionManager that opened this scan.
private boolean	writingToDisk

Access	Constructor and Description
pack-priv	SortBufferRowSource(SortBuffer sortBuffer, TransactionManager tran, SortObserver sortObserver, boolean writingToDisk, int maxFreeListSize)

Method Summary

Modifier and Type	Method and Description
public void	close() Implements org.apache.derby.iapi.store.access.GenericScanController.close. Close the scan
public boolean	closeForEndTransaction(boolean If true, means to close scan even if it has been opened to be kept opened across commit. This is used to close these scans on abort. closeHeldScan) Implements org.apache.derby.iapi.store.access.conglomerate.ScanManager.closeForEndTransaction. Close the scan
public void	closeRowSource() Implements org.apache.derby.iapi.store.access.RowSource.closeRowSource. Close the rowSource
public void	fetch(DataValueDescriptor[] The row into which the value of the current position in the scan is to be stored. result) Implements org.apache.derby.iapi.store.access.ScanController.fetch. Fetch the row at the current position of the Scan.
public final boolean	fetchNext(DataValueDescriptor[] The destRow row into which the value of the next position in the scan is to be stored. row) Implements org.apache.derby.iapi.store.access.ScanController.fetchNext. Fetch the (partial) row at the next position of the Scan.
public void	fetchWithoutQualify(DataValueDescriptor[] The row into which the value of the current position in the scan is to be stored. result) Implements org.apache.derby.iapi.store.access.ScanController.fetchWithoutQualify. Fetch the row at the current position of the Scan and does not apply the qualifiers.
public DataValueDescriptor[]	getNextRowFromRowSource() Implements org.apache.derby.iapi.store.access.RowSource.getNextRowFromRowSource. Get the next row as an array of column objects.
public FormatableBitSet	getValidColumns() Implements org.apache.derby.iapi.store.access.RowSource.getValidColumns. All columns are always set from a sorter
public boolean	needsRowLocation() Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.needsRowLocation. needsRowLocation returns true iff this the row source expects the drainer of the row source to call rowLocation after getting a row from getNextRowFromRowSource.
public boolean	needsRowLocationForDeferredCheckConstraints() Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.needsRowLocationForDeferredCheckConstraints.
public boolean	needsToClone() Implements org.apache.derby.iapi.store.access.RowSource.needsToClone. Does the caller of getNextRowFromRowSource() need to clone the row in order to keep a reference to the row past the getNextRowFromRowSource() call which returned the row.
public boolean	next() Implements org.apache.derby.iapi.store.access.ScanController.next, org.apache.derby.iapi.store.access.GroupFetchScanController.next. Move to the next position in the scan.
public void	offendingRowLocation(RowLocation rl, long containdId) Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.offendingRowLocation.
public void	rowLocation(RowLocation rl) Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.rowLocation. rowLocation is a callback for the drainer of the row source to return the rowLocation of the current row, i.e, the row that is being returned by getNextRowFromRowSource.

maxFreeListSize	back to summary
private int maxFreeListSize

sortBuffer	back to summary
pack-priv SortBuffer sortBuffer The Sort buffer where rows come from

sortObserver	back to summary
private SortObserver sortObserver

tran	back to summary
protected TransactionManager tran The TransactionManager that opened this scan.

writingToDisk	back to summary
private boolean writingToDisk

SortBufferRowSource	back to summary
pack-priv SortBufferRowSource(SortBuffer sortBuffer, TransactionManager tran, SortObserver sortObserver, boolean writingToDisk, int maxFreeListSize)

Method Detail

close	back to summary
public void close() Implements org.apache.derby.iapi.store.access.GenericScanController.close. Close the scan

back to summary

public void close()

Implements org.apache.derby.iapi.store.access.GenericScanController.close.

Close the scan

closeForEndTransaction	back to summary
public boolean closeForEndTransaction(boolean closeHeldScan) Implements org.apache.derby.iapi.store.access.conglomerate.ScanManager.closeForEndTransaction. Close the scan Parameters closeHeldScan:boolean Doc from org.apache.derby.iapi.store.access.conglomerate.ScanManager.closeForEndTransaction. If true, means to close scan even if it has been opened to be kept opened across commit. This is used to close these scans on abort. Returns:boolean Doc from org.apache.derby.iapi.store.access.conglomerate.ScanManager.closeForEndTransaction. boolean indicating that the close has resulted in a real close of the scan. A held scan will return false if called by closeForEndTransaction(false), otherwise it will return true. A non-held scan will always return true.

closeForEndTransaction

back to summary

public boolean closeForEndTransaction(boolean closeHeldScan)

Implements org.apache.derby.iapi.store.access.conglomerate.ScanManager.closeForEndTransaction.

Close the scan

Parameters

closeHeldScan:boolean

Doc from org.apache.derby.iapi.store.access.conglomerate.ScanManager.closeForEndTransaction.

If true, means to close scan even if it has been opened to be kept opened across commit. This is used to close these scans on abort.

Returns:boolean

Doc from org.apache.derby.iapi.store.access.conglomerate.ScanManager.closeForEndTransaction.

boolean indicating that the close has resulted in a real close of the scan. A held scan will return false if called by closeForEndTransaction(false), otherwise it will return true. A non-held scan will always return true.

closeRowSource	back to summary
public void closeRowSource() Implements org.apache.derby.iapi.store.access.RowSource.closeRowSource. Close the rowSource

closeRowSource

back to summary

public void closeRowSource()

Implements org.apache.derby.iapi.store.access.RowSource.closeRowSource.

Close the rowSource

fetch back to summary

fetch	back to summary
public void fetch(DataValueDescriptor[] result) throws StandardException Implements org.apache.derby.iapi.store.access.ScanController.fetch. Fetch the row at the current position of the Scan. Parameters result:DataValueDescriptor[] Doc from org.apache.derby.iapi.store.access.ScanController.fetch. The row into which the value of the current position in the scan is to be stored. Exceptions StandardException: Doc from org.apache.derby.iapi.store.access.ScanController.fetch. Standard exception policy. See Also `org.apache.derby.iapi.store.access.ScanController#fetch`

public void fetch(DataValueDescriptor[] result) throws StandardException

Implements org.apache.derby.iapi.store.access.ScanController.fetch.

Fetch the row at the current position of the Scan.

Parameters

result:DataValueDescriptor[]

Doc from org.apache.derby.iapi.store.access.ScanController.fetch.

The row into which the value of the current position in the scan is to be stored.

Exceptions

StandardException:

Doc from org.apache.derby.iapi.store.access.ScanController.fetch.

Standard exception policy.

fetchNext	back to summary
public final boolean fetchNext(DataValueDescriptor[] row) throws StandardException Implements org.apache.derby.iapi.store.access.ScanController.fetchNext. Doc from org.apache.derby.iapi.store.access.ScanController.fetchNext. Fetch the (partial) row at the next position of the Scan. If there is a valid next position in the scan then the value in the destRow storable row is replaced with the value of the row at the current scan position. The columns of the destRow row must be of the same type as the actual columns in the underlying conglomerate. The resulting contents of destRow after a fetchNext() which returns false is undefined. The result of calling fetchNext(row) is exactly logically equivalent to making a next() call followed by a fetch(row) call. This interface allows implementations to optimize the 2 calls if possible. Parameters row:DataValueDescriptor[] The destRow row into which the value of the next position in the scan is to be stored. Returns:boolean True if there is a next position in the scan, false if there isn't. Exceptions StandardException: Standard exception policy.

fetchNext

back to summary

public final boolean fetchNext(DataValueDescriptor[] row) throws StandardException

Implements org.apache.derby.iapi.store.access.ScanController.fetchNext.

Doc from org.apache.derby.iapi.store.access.ScanController.fetchNext.

Fetch the (partial) row at the next position of the Scan. If there is a valid next position in the scan then the value in the destRow storable row is replaced with the value of the row at the current scan position. The columns of the destRow row must be of the same type as the actual columns in the underlying conglomerate. The resulting contents of destRow after a fetchNext() which returns false is undefined. The result of calling fetchNext(row) is exactly logically equivalent to making a next() call followed by a fetch(row) call. This interface allows implementations to optimize the 2 calls if possible.

Parameters

row:DataValueDescriptor[]: The destRow row into which the value of the next position in the scan is to be stored.

Returns:boolean

True if there is a next position in the scan, false if there isn't.

Exceptions

StandardException:: Standard exception policy.

fetchWithoutQualify back to summary

fetchWithoutQualify	back to summary
public void fetchWithoutQualify(DataValueDescriptor[] result) throws StandardException Implements org.apache.derby.iapi.store.access.ScanController.fetchWithoutQualify. Fetch the row at the current position of the Scan and does not apply the qualifiers. This method will always throw an exception. (SQLState.SORT_IMPROPER_SCAN_METHOD) Parameters result:DataValueDescriptor[] Doc from org.apache.derby.iapi.store.access.ScanController.fetchWithoutQualify. The row into which the value of the current position in the scan is to be stored. Exceptions StandardException: Doc from org.apache.derby.iapi.store.access.ScanController.fetchWithoutQualify. Standard exception policy. See Also `org.apache.derby.iapi.store.access.ScanController#fetchWithoutQualify`

public void fetchWithoutQualify(DataValueDescriptor[] result) throws StandardException

Implements org.apache.derby.iapi.store.access.ScanController.fetchWithoutQualify.

Fetch the row at the current position of the Scan and does not apply the qualifiers. This method will always throw an exception. (SQLState.SORT_IMPROPER_SCAN_METHOD)

Parameters

result:DataValueDescriptor[]

Doc from org.apache.derby.iapi.store.access.ScanController.fetchWithoutQualify.

The row into which the value of the current position in the scan is to be stored.

Exceptions

StandardException:

Doc from org.apache.derby.iapi.store.access.ScanController.fetchWithoutQualify.

Standard exception policy.

getNextRowFromRowSource	back to summary
public DataValueDescriptor[] getNextRowFromRowSource() Implements org.apache.derby.iapi.store.access.RowSource.getNextRowFromRowSource. Doc from org.apache.derby.iapi.store.access.RowSource.getNextRowFromRowSource. Get the next row as an array of column objects. The column objects can be a JBMS Storable or any Serializable/Externalizable/Formattable/Streaming type. A return of null indicates that the complete set of rows has been read. A null column can be specified by leaving the object null, or indicated by returning a non-null getValidColumns. On streaming columns, it can be indicated by returning a non-null get FieldStates. If RowSource.needToClone() is true then the returned row (the DataValueDescriptor[]) is guaranteed not to be modified by drainer of the RowSource (except that the input stream will be read, of course) and drainer will keep no reference to it before making the subsequent nextRow call. So it is safe to return the same DataValueDescriptor[] in subsequent nextRow calls if that is desirable for performance reasons. If RowSource.needToClone() is false then the returned row (the DataValueDescriptor[]) may be be modified by drainer of the RowSource, and the drainer may keep a reference to it after making the subsequent nextRow call. In this case the client should severe all references to the row after returning it from getNextRowFromRowSource().

getNextRowFromRowSource

back to summary

public DataValueDescriptor[] getNextRowFromRowSource()

Implements org.apache.derby.iapi.store.access.RowSource.getNextRowFromRowSource.

Doc from org.apache.derby.iapi.store.access.RowSource.getNextRowFromRowSource.

Get the next row as an array of column objects. The column objects can be a JBMS Storable or any Serializable/Externalizable/Formattable/Streaming type.
A return of null indicates that the complete set of rows has been read.

A null column can be specified by leaving the object null, or indicated by returning a non-null getValidColumns. On streaming columns, it can be indicated by returning a non-null get FieldStates.

If RowSource.needToClone() is true then the returned row (the DataValueDescriptor[]) is guaranteed not to be modified by drainer of the RowSource (except that the input stream will be read, of course) and drainer will keep no reference to it before making the subsequent nextRow call. So it is safe to return the same DataValueDescriptor[] in subsequent nextRow calls if that is desirable for performance reasons.

If RowSource.needToClone() is false then the returned row (the DataValueDescriptor[]) may be be modified by drainer of the RowSource, and the drainer may keep a reference to it after making the subsequent nextRow call. In this case the client should severe all references to the row after returning it from getNextRowFromRowSource().

getValidColumns	back to summary
public FormatableBitSet getValidColumns() Implements org.apache.derby.iapi.store.access.RowSource.getValidColumns. All columns are always set from a sorter

getValidColumns

back to summary

public FormatableBitSet getValidColumns()

Implements org.apache.derby.iapi.store.access.RowSource.getValidColumns.

All columns are always set from a sorter

needsRowLocation	back to summary
public boolean needsRowLocation() Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.needsRowLocation. Doc from org.apache.derby.iapi.store.access.RowLocationRetRowSource.needsRowLocation. needsRowLocation returns true iff this the row source expects the drainer of the row source to call rowLocation after getting a row from getNextRowFromRowSource. Returns:boolean true iff this row source expects some row location to be returned

needsRowLocation

back to summary

public boolean needsRowLocation()

Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.needsRowLocation.

Doc from org.apache.derby.iapi.store.access.RowLocationRetRowSource.needsRowLocation.

needsRowLocation returns true iff this the row source expects the drainer of the row source to call rowLocation after getting a row from getNextRowFromRowSource.

Returns:boolean: true iff this row source expects some row location to be returned

needsRowLocationForDeferredCheckConstraints	back to summary
public boolean needsRowLocationForDeferredCheckConstraints() Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.needsRowLocationForDeferredCheckConstraints.

needsToClone back to summary

needsToClone	back to summary
public boolean needsToClone() Implements org.apache.derby.iapi.store.access.RowSource.needsToClone. Doc from org.apache.derby.iapi.store.access.RowSource.needsToClone. Does the caller of getNextRowFromRowSource() need to clone the row in order to keep a reference to the row past the getNextRowFromRowSource() call which returned the row. This call must always return the same for all rows in a RowSource (ie. the caller will call this once per scan from a RowSource and assume the behavior is true for all rows in the RowSource). See Also `org.apache.derby.iapi.store.access.RowSource#needsToClone`

public boolean needsToClone()

Implements org.apache.derby.iapi.store.access.RowSource.needsToClone.

Doc from org.apache.derby.iapi.store.access.RowSource.needsToClone.

Does the caller of getNextRowFromRowSource() need to clone the row in order to keep a reference to the row past the getNextRowFromRowSource() call which returned the row. This call must always return the same for all rows in a RowSource (ie. the caller will call this once per scan from a RowSource and assume the behavior is true for all rows in the RowSource).

See Also: org.apache.derby.iapi.store.access.RowSource#needsToClone

next	back to summary
public boolean next() throws StandardException Implements org.apache.derby.iapi.store.access.ScanController.next, org.apache.derby.iapi.store.access.GroupFetchScanController.next. Doc from org.apache.derby.iapi.store.access.ScanController.next. Move to the next position in the scan. If this is the first call to next(), the position is set to the first row. Returns false if there is not a next row to move to. It is possible, but not guaranteed, that this method could return true again, after returning false, if some other operation in the same transaction appended a row to the underlying conglomerate. Returns:boolean True if there is a next position in the scan, false if there isn't. Exceptions StandardException: Standard exception policy.

back to summary

public boolean next() throws StandardException

Implements org.apache.derby.iapi.store.access.ScanController.next, org.apache.derby.iapi.store.access.GroupFetchScanController.next.

Doc from org.apache.derby.iapi.store.access.ScanController.next.

Move to the next position in the scan. If this is the first call to next(), the position is set to the first row. Returns false if there is not a next row to move to. It is possible, but not guaranteed, that this method could return true again, after returning false, if some other operation in the same transaction appended a row to the underlying conglomerate.

Returns:boolean

True if there is a next position in the scan, false if there isn't.

Exceptions

StandardException:: Standard exception policy.

offendingRowLocation	back to summary
public void offendingRowLocation(RowLocation rl, long containdId) throws StandardException Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.offendingRowLocation.

rowLocation	back to summary
public void rowLocation(RowLocation rl) Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.rowLocation. Doc from org.apache.derby.iapi.store.access.RowLocationRetRowSource.rowLocation. rowLocation is a callback for the drainer of the row source to return the rowLocation of the current row, i.e, the row that is being returned by getNextRowFromRowSource. This interface is for the purpose of loading a base table with index. In that case, the indices can be built at the same time the base table is laid down once the row location of the base row is known. This is an example pseudo code on how this call is expected to be used: boolean needsRL = rowSource.needsRowLocation(); DataValueDescriptor[] row; while((row = rowSource.getNextRowFromRowSource()) != null) { RowLocation rl = heapConglomerate.insertRow(row); if (needsRL) rowSource.rowLocation(rl); } NeedsRowLocation and rowLocation will ONLY be called by a drainer of the row source which CAN return a row location. Drainer of row source which cannot return rowLocation will guarantee to not call either callbacks. Conversely, if NeedsRowLocation is called and it returns true, then for every row return by getNextRowFromRowSource, a rowLocation callback must also be issued with the row location of the row. Implementor of both the source and the drain of the row source must be aware of this protocol. The RowLocation object is own by the caller of rowLocation, in other words, the drainer of the RowSource. This is so that we don't need to new a row location for every row. If the Row Source wants to keep the row location, it needs to clone it (RowLocation is a ClonableObject).

rowLocation

back to summary

public void rowLocation(RowLocation rl)

Implements org.apache.derby.iapi.store.access.RowLocationRetRowSource.rowLocation.

Doc from org.apache.derby.iapi.store.access.RowLocationRetRowSource.rowLocation.

rowLocation is a callback for the drainer of the row source to return the rowLocation of the current row, i.e, the row that is being returned by getNextRowFromRowSource. This interface is for the purpose of loading a base table with index. In that case, the indices can be built at the same time the base table is laid down once the row location of the base row is known. This is an example pseudo code on how this call is expected to be used:

		boolean needsRL = rowSource.needsRowLocation();
		DataValueDescriptor[] row;
		while((row = rowSource.getNextRowFromRowSource()) != null)
		{
			RowLocation rl = heapConglomerate.insertRow(row);
			if (needsRL)
				rowSource.rowLocation(rl);
		}

NeedsRowLocation and rowLocation will ONLY be called by a drainer of the row source which CAN return a row location. Drainer of row source which cannot return rowLocation will guarantee to not call either callbacks. Conversely, if NeedsRowLocation is called and it returns true, then for every row return by getNextRowFromRowSource, a rowLocation callback must also be issued with the row location of the row. Implementor of both the source and the drain of the row source must be aware of this protocol.
The RowLocation object is own by the caller of rowLocation, in other words, the drainer of the RowSource. This is so that we don't need to new a row location for every row. If the Row Source wants to keep the row location, it needs to clone it (RowLocation is a ClonableObject).

public Class SortBufferRowSource

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail