Berkeley DB version 4.2.52

## com.sleepycat.bdb
Class DataView

    java.lang.Object
      |
      +--com.sleepycat.bdb.DataView

All Implemented Interfaces:
  Cloneable

public final class DataView
extends Object
implements Cloneable

(internal) Represents a Berkeley DB database and adds support for indices, bindings and key ranges.

NOTE: This classes is internal and may be changed incompatibly or deleted in the future. It is public only so it may be used by subpackages.

This class defines a view and takes care of reading and updating indices, calling bindings, constraining access to a key range, etc.

Constructor Summary
`DataView(DataStore store, DataIndex index, DataBinding keyBinding, DataBinding valueBinding, EntityBinding entityBinding, boolean writeAllowed)` Creates a view for a given store/index and bindings.

Method Summary
`int` `addValue(DataThang primaryKeyThang, Object value, int flags)` Adds a duplicate value for a specified key.
`int` `append(Object value, Object[] retPrimaryKey, Object[] retValue)` Appends a value and returns the new key.
`boolean` `areDuplicatesAllowed()` Returns whether duplicates are allowed for the index or store.
`boolean` `areDuplicatesOrdered()` Returns whether duplicates are ordered for the index or store.
`boolean` `areKeysRenumbered()` Returns whether keys (record numbers) are renumbered for the index or store.
`DataView` `autoCommitView(boolean enable)` Returns a new view with a specified autoCommit setting.
`boolean` `canDeriveKeyFromValue()` Returns whether data keys can be derived from the value/entity binding of this view, which determines whether a value/entity object alone is sufficient for operations that require keys.
`void` `clear(Collection oldValues)` Deletes all records in the current range, optionally returning the values for the deleted records.
`int` `consume(int flags, Object[] retPrimaryKey, Object[] retValue)` Performs a database 'get and consume' operation.
`DataView` `dirtyReadView(boolean enable)` Returns a new view with a specified dirtyRead setting.
`int` `get(Object key, Object value, int flags, boolean lockForWrite, Object[] retValue)` Performs a general database 'get' operation.
`CurrentTransaction` `getCurrentTxn()` Returns the current transaction for the view or null if the environment is non-transactional.
`DataDb` `getDb()` Returns the database for the index, if one is used, or store, if no index is used.
`DbEnv` `getEnv()` Returns the environment for the store and index.
`DataIndex` `getIndex()` Returns the index, as specified to the constructor.
`DataBinding` `getKeyBinding()` Returns the key binding that is used.
`DataThang` `getSingleKeyThang()` Returns the key thang for a single key range, or null if a single key range is not used.
`DataStore` `getStore()` Returns the store, as specified to the constructor.
`DataBinding` `getValueBinding()` Returns the value binding that is used.
`EntityBinding` `getValueEntityBinding()` Returns the entity binding that is used.
`boolean` `isAutoCommit()` Returns whether auto-commit is set for this view or for the transactional environment of the store and index.
`boolean` `isDirtyReadAllowed()` Returns whether DIRTY_READ was specified for both the Store and Index.
`boolean` `isDirtyReadEnabled()` Returns whether DIRTY_READ will be used for all read operations.
`boolean` `isEmpty()` Returns whether no records are present in the view.
`boolean` `isOrdered()` Returns whether keys are ordered for the index or store.
`boolean` `isTransactional()` Returns whether the store and index are transactional.
`boolean` `isWriteAllowed()` Returns whether write operations are allowed.
`DataCursor` `join(DataCursor[] indexCursors, boolean presorted)` Returns a cursor for this view that reads only records having the index key values at the specified cursors.
`DataCursor` `join(DataView[] indexViews, Object[] indexKeys, boolean presorted)` Returns a cursor for this view that reads only records having the specified index key values.
`DataView` `keySetView()` Return a new key-set view derived from this view by setting the entity and value binding to null.
`int` `put(Object primaryKey, Object value, int flags, Object[] oldValue)` Performs a database 'put' operation, optionally returning the old value.
`DataView` `subView(Object beginKey, boolean beginInclusive, Object endKey, boolean endInclusive, DataBinding keyBinding)` Return a new value-set view for key range, optionally changing the key binding.
`DataView` `valueSetView()` Return a new value-set view derived from this view by setting the key binding to null.
`DataView` `valueSetView(Object singleKey)` Return a new value-set view for single key range.

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

Constructor Detail

### DataView

    public DataView(DataStore store,
                    DataIndex index,
                    DataBinding keyBinding,
                    DataBinding valueBinding,
                    EntityBinding entityBinding,
                    boolean writeAllowed)
             throws IllegalArgumentException

  Creates a view for a given store/index and bindings. The key range of the view will be open.

Parameters:
  `store` - is the store or is ignored if the index parameter is given.
  `index` - is the index or null if no index is used.
  `keyBinding` - is the key binding or null if keys will not be used.
  `valueBinding` - is the value binding or null if an entityBinding is given or if values will not be used.
  `entityBinding` - is the entity binding or null if an valueBinding is given or if values will not be used.
  `writeAllowed` - is whether writing through this view is allowed.
Throws:
  `IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.

Method Detail

### keySetView

    public DataView keySetView()

  Return a new key-set view derived from this view by setting the entity and value binding to null.

  Returns:
    the derived view.

### valueSetView

    public DataView valueSetView()

  Return a new value-set view derived from this view by setting the key binding to null.

  Returns:
    the derived view.

### valueSetView

    public DataView valueSetView(Object singleKey)
                          throws DbException,
                                 IOException,
                                 KeyRangeException

  Return a new value-set view for single key range.

  Parameters:
    `singleKey` - the single key value.
  Returns:
    the derived view.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.
    `KeyRangeException` - if the specified range is not within the current range.

### subView

    public DataView subView(Object beginKey,
                            boolean beginInclusive,
                            Object endKey,
                            boolean endInclusive,
                            DataBinding keyBinding)
                     throws DbException,
                            IOException,
                            KeyRangeException

  Return a new value-set view for key range, optionally changing the key binding.

  Parameters:
    `beginKey` - the lower bound.
    `beginInclusive` - whether the lower bound is inclusive.
    `endKey` - the upper bound.
    `endInclusive` - whether the upper bound is inclusive.
    `keyBinding` - a key binding to use, or null to retain the base view's key binding.
  Returns:
    the derived view.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.
    `KeyRangeException` - if the specified range is not within the current range.

### dirtyReadView

    public DataView dirtyReadView(boolean enable)

  Returns a new view with a specified dirtyRead setting.

  Parameters:
    `enable` - whether to enable or disable dirty-read.
  Returns:
    the derived view.

### autoCommitView

    public DataView autoCommitView(boolean enable)

  Returns a new view with a specified autoCommit setting. Note that auto-commit is not implemented by the view, the view only holds the auto-commit property.

  Parameters:
    `enable` - whether to enable or disable auto-commit.
  Returns:
    the derived view.

### getCurrentTxn

    public CurrentTransaction getCurrentTxn()

  Returns the current transaction for the view or null if the environment is non-transactional.

  Returns:
    the current transaction.

### getSingleKeyThang

    public DataThang getSingleKeyThang()

  Returns the key thang for a single key range, or null if a single key range is not used.

  Returns:
    the key thang or null.

### getDb

    public DataDb getDb()

  Returns the database for the index, if one is used, or store, if no index is used.

  Returns:
    the database of the index or, if none, the store.

### getEnv

    public final DbEnv getEnv()

  Returns the environment for the store and index.

  Returns:
    the environment.

### isAutoCommit

    public final boolean isAutoCommit()

  Returns whether auto-commit is set for this view or for the transactional environment of the store and index. Note that auto-commit is not implemented by the view, the view only holds the auto-commit property.

  Returns:
    the auto-commit setting.

### getStore

    public final DataStore getStore()

  Returns the store, as specified to the constructor.

  Returns:
    the store.

### getIndex

    public final DataIndex getIndex()

  Returns the index, as specified to the constructor.

  Returns:
    the index or null.

### getKeyBinding

    public final DataBinding getKeyBinding()

  Returns the key binding that is used.

  Returns:
    the key binding or null.

### getValueBinding

    public final DataBinding getValueBinding()

  Returns the value binding that is used.

  Returns:
    the value binding or null.

### getValueEntityBinding

    public final EntityBinding getValueEntityBinding()

  Returns the entity binding that is used.

  Returns:
    the entity binding or null.

### areDuplicatesAllowed

    public final boolean areDuplicatesAllowed()

  Returns whether duplicates are allowed for the index or store.

  Returns:
    whether duplicates are allowed.

### areDuplicatesOrdered

    public final boolean areDuplicatesOrdered()

  Returns whether duplicates are ordered for the index or store.

  Returns:
    whether duplicates are ordered.

### areKeysRenumbered

    public final boolean areKeysRenumbered()

  Returns whether keys (record numbers) are renumbered for the index or store.

  Returns:
    whether keys are renumbered.

### isOrdered

    public final boolean isOrdered()

  Returns whether keys are ordered for the index or store.

  Returns:
    whether keys are ordered.

### isWriteAllowed

    public final boolean isWriteAllowed()

  Returns whether write operations are allowed.

  Returns:
    whether write operations are allowed.

### isDirtyReadAllowed

    public final boolean isDirtyReadAllowed()

  Returns whether DIRTY_READ was specified for both the Store and Index.

  Returns:
    whether dirty-read is allowed.

### isDirtyReadEnabled

    public final boolean isDirtyReadEnabled()

  Returns whether DIRTY_READ will be used for all read operations.

  Returns:
    whether dirty-read is enabled.

### isTransactional

    public final boolean isTransactional()

  Returns whether the store and index are transactional.

  Returns:
    whether the store and index are transactional.

### isEmpty

    public boolean isEmpty()
                    throws DbException,
                           IOException

  Returns whether no records are present in the view.

  Returns:
    whether the view is empty.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### get

    public int get(Object key,
                   Object value,
                   int flags,
                   boolean lockForWrite,
                   Object[] retValue)
            throws DbException,
                   IOException

  Performs a general database 'get' operation.

  Parameters:
    `key` - used to find the value
    `value` - used to find the value
    `flags` - all flags except DB_SET and DB_GET_BOTH are legal, `Db.get(DbTxn,Dbt,Dbt,int)`.
    `lockForWrite` - if true locks the cursor during the get.
    `retValue` - used to store the result of the query
  Returns:
    0 if mathing values are found, Db.DB_NOTFOUND if not.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### consume

    public int consume(int flags,
                       Object[] retPrimaryKey,
                       Object[] retValue)
                throws DbException,
                       IOException

  Performs a database 'get and consume' operation.

  Parameters:
    `flags` - must be CONSUME or CONSUME_WAIT.
    `retPrimaryKey` - used to store the resulting key.
    `retValue` - used to store the resulting value.
  Returns:
    an error or zero for success.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### put

    public int put(Object primaryKey,
                   Object value,
                   int flags,
                   Object[] oldValue)
            throws DbException,
                   IOException

  Performs a database 'put' operation, optionally returning the old value.

  Parameters:
    `primaryKey` - key of new record.
    `value` - value of new record.
    `flags` - must be 0, NODUPDATA or NOOVERWRITE.
    `oldValue` - used to store the old value, or null if none should be returned.
  Returns:
    an error or zero for success.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### addValue

    public int addValue(DataThang primaryKeyThang,
                        Object value,
                        int flags)
                 throws DbException,
                        IOException

  Adds a duplicate value for a specified key.

  Parameters:
    `primaryKeyThang` - key of new record.
    `value` - value of new record.
    `flags` - must be 0 or NODUPDATA or KEYFIRST or KEYLAST.
  Returns:
    an error or zero for success.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### append

    public int append(Object value,
                      Object[] retPrimaryKey,
                      Object[] retValue)
               throws DbException,
                      IOException

  Appends a value and returns the new key. If a key assigner is used it assigns the key, otherwise a QUEUE or RECNO database is required.

  Parameters:
    `value` - is the value to append.
    `retPrimaryKey` - used to store the assigned key.
    `retValue` - used to store the resulting entity, or null if none should be returned.
  Returns:
    an error or zero for success.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### clear

    public void clear(Collection oldValues)
               throws DbException,
                      IOException

  Deletes all records in the current range, optionally returning the values for the deleted records.

  Parameters:
    `oldValues` - is used to store the values that are cleared, or null if the old values should not be returned.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### join

    public DataCursor join(DataView[] indexViews,
                           Object[] indexKeys,
                           boolean presorted)
                    throws DbException,
                           IOException

  Returns a cursor for this view that reads only records having the specified index key values.

  Parameters:
    `indexViews` - are the views to be joined.
    `indexKeys` - are the keys to join on for each view.
    `presorted` - is whether the given views are presorted or should be sorted by number of values per key.
  Returns:
    the join cursor.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### join

    public DataCursor join(DataCursor[] indexCursors,
                           boolean presorted)
                    throws DbException,
                           IOException

  Returns a cursor for this view that reads only records having the index key values at the specified cursors.

  Parameters:
    `presorted` - is whether the given cursors are presorted or should be sorted by number of values per key.
  Returns:
    the join cursor.
  Throws:
    `DbException` - if a database problem occurs.
    `IOException` - if an IO problem occurs.

### canDeriveKeyFromValue

    public boolean canDeriveKeyFromValue()

  Returns whether data keys can be derived from the value/entity binding of this view, which determines whether a value/entity object alone is sufficient for operations that require keys.

  Returns:
    whether data keys can be derived.

Berkeley DB version 4.2.52

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.