SortBufferRowSource (Apache Derby V10.14 Internals)

java.lang.Object
- org.apache.derby.impl.store.access.sort.Scan
- - org.apache.derby.impl.store.access.sort.SortBufferRowSource

All Implemented Interfaces:

ScanControllerRowSource, ScanManager, GenericScanController, GroupFetchScanController, RowCountable, RowLocationRetRowSource, RowSource, ScanController, ScanInfo
```
public class SortBufferRowSource
extends Scan
implements ScanControllerRowSource
```
Wrapping the output of a SortBuffer in a RowSource for the benefit of the createAndLoadConglomerate and loadConglomerate interface. Scan implements ScanController, this class just implements the RowSource interface.

Field Summary

Fields
Modifier and Type	Field	Description
`private int`	`maxFreeListSize`
`(package private) SortBuffer`	`sortBuffer`	The Sort buffer where rows come from
`private SortObserver`	`sortObserver`
`protected TransactionManager`	`tran`	The TransactionManager that opened this scan.
`private boolean`	`writingToDisk`

Fields inherited from interface org.apache.derby.iapi.store.access.ScanController
GE, GT, NA

Constructor Summary

Constructors
Constructor	Description
`SortBufferRowSource(SortBuffer sortBuffer, TransactionManager tran, SortObserver sortObserver, boolean writingToDisk, int maxFreeListSize)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`close()`	Close the scan
`boolean`	`closeForEndTransaction(boolean closeHeldScan)`	Close the scan
`void`	`closeRowSource()`	Close the rowSource
`void`	`fetch(DataValueDescriptor[] result)`	Fetch the row at the current position of the Scan.
`boolean`	`fetchNext(DataValueDescriptor[] row)`	Fetch the (partial) row at the next position of the Scan.
`void`	`fetchWithoutQualify(DataValueDescriptor[] result)`	Fetch the row at the current position of the Scan and does not apply the qualifiers.
`DataValueDescriptor[]`	`getNextRowFromRowSource()`	Get the next row as an array of column objects.
`FormatableBitSet`	`getValidColumns()`	All columns are always set from a sorter
`boolean`	`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.
`boolean`	`needsRowLocationForDeferredCheckConstraints()`
`boolean`	`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.
`boolean`	`next()`	Move to the next position in the scan.
`void`	`offendingRowLocation(RowLocation rl, long containdId)`
`void`	`rowLocation(RowLocation rl)`	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.

Methods inherited from interface org.apache.derby.iapi.store.access.GenericScanController
getScanInfo, isKeyed, isTableLocked, newRowLocationTemplate, reopenScan, reopenScanByRowLocation

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.derby.iapi.store.access.RowCountable
getEstimatedRowCount, setEstimatedRowCount

Methods inherited from class org.apache.derby.impl.store.access.sort.Scan
delete, didNotQualify, doesCurrentPositionQualify, fetchLocation, fetchNextGroup, fetchNextGroup, fetchSet, getAllScanInfo, getEstimatedRowCount, getScanInfo, isCurrentPositionDeleted, isHeldAfterCommit, isKeyed, isTableLocked, newRowLocationTemplate, positionAtRowLocation, reopenScan, reopenScanByRowLocation, replace, setEstimatedRowCount

Methods inherited from interface org.apache.derby.iapi.store.access.ScanController
delete, didNotQualify, doesCurrentPositionQualify, fetchLocation, isCurrentPositionDeleted, isHeldAfterCommit, positionAtRowLocation, replace

- Field Detail
  - sortBuffer
```
SortBuffer sortBuffer
```
    The Sort buffer where rows come from
  - tran
```
protected TransactionManager tran
```
    The TransactionManager that opened this scan.
  - maxFreeListSize
```
private int maxFreeListSize
```
  - writingToDisk
```
private boolean writingToDisk
```
  - sortObserver
```
private SortObserver sortObserver
```
- Constructor Detail
  - SortBufferRowSource
```
SortBufferRowSource(SortBuffer sortBuffer,
                    TransactionManager tran,
                    SortObserver sortObserver,
                    boolean writingToDisk,
                    int maxFreeListSize)
```
- Method Detail
  - getNextRowFromRowSource
```
public DataValueDescriptor[] getNextRowFromRowSource()
```
    Description copied from interface: RowSource
    
    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().
    
    Specified by:
    
    getNextRowFromRowSource in interface RowSource
  - needsRowLocation
```
public boolean needsRowLocation()
```
    Description copied from interface: RowLocationRetRowSource
    
    needsRowLocation returns true iff this the row source expects the drainer of the row source to call rowLocation after getting a row from getNextRowFromRowSource.
    
    Specified by:
    
    needsRowLocation in interface RowLocationRetRowSource
    
    Returns:
    
    true iff this row source expects some row location to be returned
    
    See Also:
    
    RowLocationRetRowSource.rowLocation(org.apache.derby.iapi.types.RowLocation)
  - needsRowLocationForDeferredCheckConstraints
```
public boolean needsRowLocationForDeferredCheckConstraints()
```
    Specified by:
    
    needsRowLocationForDeferredCheckConstraints in interface RowLocationRetRowSource
  - needsToClone
```
public boolean needsToClone()
```
    Description copied from interface: RowSource
    
    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).
    
    Specified by:
    
    needsToClone in interface RowSource
    
    See Also:
    
    RowSource.needsToClone()
  - rowLocation
```
public void rowLocation(RowLocation rl)
```
    Description copied from interface: RowLocationRetRowSource
    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).
    Specified by:
    
    rowLocation in interface RowLocationRetRowSource
  - offendingRowLocation
```
public void offendingRowLocation(RowLocation rl,
                                 long containdId)
                          throws StandardException
```
    Specified by:
    
    offendingRowLocation in interface RowLocationRetRowSource
    
    Throws:
    
    StandardException
  - getValidColumns
```
public FormatableBitSet getValidColumns()
```
    All columns are always set from a sorter
    
    Specified by:
    
    getValidColumns in interface RowSource
  - close
```
public void close()
```
    Close the scan
    
    Specified by:
    
    close in interface GenericScanController
  - closeForEndTransaction
```
public boolean closeForEndTransaction(boolean closeHeldScan)
```
    Close the scan
    
    Specified by:
    
    closeForEndTransaction in interface ScanManager
    
    Parameters:
    
    closeHeldScan - 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 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
```
public void closeRowSource()
```
    Close the rowSource
    
    Specified by:
    
    closeRowSource in interface RowSource
  - next
```
public boolean next()
             throws StandardException
```
    Description copied from interface: ScanController
    
    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.
    
    Specified by:
    
    next in interface GroupFetchScanController
    
    Specified by:
    
    next in interface ScanController
    
    Returns:
    
    True if there is a next position in the scan, false if there isn't.
    
    Throws:
    
    StandardException - Standard exception policy.
  - fetchWithoutQualify
```
public void fetchWithoutQualify(DataValueDescriptor[] result)
                         throws StandardException
```
    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)
    
    Specified by:
    
    fetchWithoutQualify in interface ScanController
    
    Parameters:
    
    result - The row into which the value of the current position in the scan is to be stored.
    
    Throws:
    
    StandardException - Standard exception policy.
    
    See Also:
    
    ScanController.fetchWithoutQualify(org.apache.derby.iapi.types.DataValueDescriptor[])
  - fetch
```
public void fetch(DataValueDescriptor[] result)
           throws StandardException
```
    Fetch the row at the current position of the Scan.
    
    Specified by:
    
    fetch in interface ScanController
    
    Parameters:
    
    result - The row into which the value of the current position in the scan is to be stored.
    
    Throws:
    
    StandardException - Standard exception policy.
    
    See Also:
    
    ScanController.fetch(org.apache.derby.iapi.types.DataValueDescriptor[])
  - fetchNext
```
public final boolean fetchNext(DataValueDescriptor[] row)
                        throws StandardException
```
    Description copied from interface: ScanController
    
    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.
    
    Specified by:
    
    fetchNext in interface ScanController
    
    Parameters:
    
    row - The destRow row into which the value of the next position in the scan is to be stored.
    
    Returns:
    
    True if there is a next position in the scan, false if there isn't.
    
    Throws:
    
    StandardException - Standard exception policy.
    
    See Also:
    
    ScanController.fetch(org.apache.derby.iapi.types.DataValueDescriptor[]), RowUtil

Class SortBufferRowSource

Field Summary

Fields inherited from interface org.apache.derby.iapi.store.access.ScanController

Constructor Summary

Method Summary

Methods inherited from interface org.apache.derby.iapi.store.access.GenericScanController

Methods inherited from class java.lang.Object

Methods inherited from interface org.apache.derby.iapi.store.access.RowCountable

Methods inherited from class org.apache.derby.impl.store.access.sort.Scan

Methods inherited from interface org.apache.derby.iapi.store.access.ScanController

Field Detail

sortBuffer

tran

maxFreeListSize

writingToDisk

sortObserver

Constructor Detail

SortBufferRowSource

Method Detail

getNextRowFromRowSource

needsRowLocation

needsRowLocationForDeferredCheckConstraints

needsToClone

rowLocation

offendingRowLocation

getValidColumns

close

closeForEndTransaction

closeRowSource

next

fetchWithoutQualify

fetch

fetchNext