BIndexedTableNode Class Reference
[Data Model]

#include <storage/IndexedTableNode.h>

Inheritance diagram for BIndexedTableNode:

List of all members.

---

Detailed Description

An implementation of INode that holds a 2d array of data, identified by index.

The class derives from BMetaDataNode, providing a more concrete implementation for nodes that hold an array of items, which themselves have a common array of items (a table structure). It implements BMetaDataNode::LookupEntry() for you, returning an INode of the data at that row in the table and also taking care of the COLLAPSE_NODE flag to return the data as an SValue mapping. It does not push any node events, since this node does not itself contain actual data.

The class derives from BIndexedIterable, providing index-based iterators over the table rows. It implements BIndexedIterable::EntryAtLocked() for you, like BMetaDataNode::LookupEntry(). It calls BGenericIterable::PushIteratorChangedLocked() if any of the table data changes... though it is not clear if this is really the correct behavior (an iterator here will only change if it is using COLLAPSE_NODE to retrieve items).

The class also implements ITable, but at this point only so it can push the CellModified event. You will need to implement the other ITable methods if you want their functionality.

You must implement the following methods for a concrete class. Providing information about rows: BIndexedIterable::CountEntriesLocked(), EntryIndexOfLocked(), EntryNameAtLocked(). Providing information about columns: CountColumnsLocked(), ColumnIndexOfLocked(), ColumnNameAtLocked(). Providing table data: ValueAtLocked(), StoreValueAtLocked().

Row/Column Management
Manage the mapping of indices to nodes/datums.
sptr< BIndexedDataNode >	ActiveNodeAtLocked (size_t index)
	Retrieve node for a given row only if it already exists.
sptr< BIndexedDataNode >	NodeAtLocked (size_t index)
	Retrieve a node of a given row.
void	UpdateColumnIndicesLocked (size_t index, ssize_t delta)
	Adjust all active column datums due to items being added/removed.
void	UpdateEntryIndicesLocked (size_t index, ssize_t delta)
	Adjust all active row nodes due to items being added/removed.
ITable Implementation
virtual status_t	AddColumn (const SString &name, uint32_t type, size_t maxSize, uint32_t flags, const SValue &extras)
	Returns B_UNSUPPORTED.
virtual SValue	ColumnNames () const
	Returns all column names.
virtual status_t	CreateRow (SString *inoutName, const SValue &columns, uint32_t flags=0, sptr< INode > *createdRow=NULL)
	Returns B_UNSUPPORTED.
virtual status_t	RemoveColumn (const SString &name)
	Returns B_UNSUPPORTED.
virtual status_t	RemoveRow (const sptr< INode > &row)
	Returns B_UNSUPPORTED.
virtual SValue	Schema () const
	Returns column schema info.
Bookkeeping
Creation, destruction, locking, etc.
	BIndexedTableNode (const SContext &context, uint32_t mode=IDatum::READ_WRITE)
	BIndexedTableNode (uint32_t mode=IDatum::READ_WRITE)
SContext	Context ()
	Disambiguate.
virtual SValue	Inspect (const sptr< IBinder > &caller, const SValue &which, uint32_t flags)
	Make both INode and IIterable accessible.
virtual lock_status_t	Lock () const
	Disambiguate.
virtual void	Unlock () const
	Disambiguate.
virtual	~BIndexedTableNode ()
Structural Virtuals
New virtuals that must be implemented by derived classes, to associated entry names with indices and otherwise manage the table structure.
virtual ssize_t	ColumnIndexOfLocked (const SString &entry) const =0
	Return the index for a column entry name in the node.
virtual SString	ColumnNameAtLocked (size_t index) const =0
	Return the name of a column at a given index.
virtual size_t	CountColumnsLocked () const =0
	Return the total number of columns in the table.
virtual size_t	CountEntriesLocked () const =0
	From BIndexedIterable::CountEntriesLocked().
virtual ssize_t	EntryIndexOfLocked (const SString &entry) const =0
	Return the index for an row entry name in the node.
virtual SString	EntryNameAtLocked (size_t index) const =0
	Return the name of a row at a given index.
Meta-data
Customization and control of meta-data.
virtual void	CreateSelectionLocked (SValue *inoutSelection, SValue *outCookie) const
	Perform selection on available columns.
SString	EntryMimeTypeLocked () const
	Retrieve the MIME type of entries (row nodes).
virtual void	SetMimeType (const SString &value)
	By default, clients are not allowed to modify the MIME type.
status_t	StoreEntryMimeTypeLocked (const SString &mimeType)
	Set the MIME type that all entries (row nodes) will report.
Implement Pure Virtuals
Provide default implementation based on new capabilities.
virtual status_t	EntryAtLocked (const sptr< IndexedIterator > &it, size_t index, uint32_t flags, SValue *key, SValue *entry)
	Implement using EntryNameAtLocked() and FetchEntryAtLocked().
status_t	FetchEntryAtLocked (const sptr< IndexedIterator > &it, size_t rowIndex, uint32_t flags, SValue *entry)
	Retrieve row entry, taking care of COLLAPSE_NODE flag if needed.
status_t	FetchValueAtLocked (size_t row, const sptr< BIndexedDataNode > &rowNode, size_t column, uint32_t flags, SValue *entry)
	Use ValueAtLocked() to retrieve the entry and DatumAtLocked() if it needs to be wrapped in an IDatum.
virtual status_t	LookupEntry (const SString &entry, uint32_t flags, SValue *node)
	Implement using EntryIndexOfLocked() and FetchEntryAtLocked().
Stream Virtuals
These are like the corresponding virtuals on BStreamDatum.
virtual void	FinishReadingAtLocked (size_t row, size_t col, const void *data) const
	The default implementation does nothing.
virtual void	FinishWritingAtLocked (size_t row, size_t col, void *data)
	The default implementation uses StoreValueAtLocked() to write the data.
virtual const void *	StartReadingAtLocked (size_t row, size_t col, off_t position, ssize_t *inoutSize, uint32_t flags) const
	The default implementation return uses ValueAtLocked() to retrieve the data.
virtual void *	StartWritingAtLocked (size_t row, size_t col, off_t position, ssize_t *inoutSize, uint32_t flags)
	The default implementation uses ValueAtLocked() to create a temporary buffer.
Node Generation
virtual sptr< RowNode >	NewRowNodeLocked (size_t index, uint32_t mode)
	Called when a new row object needs to be created.
Value-based Structure Access
These are like the corresponding virtuals on BStreamDatum.
virtual void	ReportChangeAtLocked (size_t row, size_t col, const sptr< IBinder > &editor, uint32_t changes, off_t start=-1, off_t length=-1)
	Similar to BStreamDatum::ReportChangeLocked(), using same change flags.
void	SetValueAtLocked (size_t row, size_t col, const SValue &value)
	Convenience function for changing a value.
virtual off_t	SizeAtLocked (size_t row, size_t col) const
	The default implementation returns ValueAtLocked().Length().
virtual status_t	StoreSizeAtLocked (size_t row, size_t col, off_t size)
	The default implementation uses ValueAtLocked() and StoreValueAtLocked() to change the size.
virtual status_t	StoreValueAtLocked (size_t row, size_t col, const SValue &value)=0
	Must be implemented by subclasses change the current value at an index.
virtual status_t	StoreValueTypeAtLocked (size_t row, size_t col, uint32_t type)
	The default implementation uses ValueAtLocked() and StoreValueAtLocked() to change the type.
virtual SValue	ValueAtLocked (size_t row, size_t col) const =0
	Must be implemented by subclasses to return the current value at an index.
virtual uint32_t	ValueTypeAtLocked (size_t row, size_t col) const
	The default implementation returns ValueAtLocked().Type().
Friends
class	RowNode
Classes
class	RowNode
	Node object generated for a row in BIndexedTableNode. More...

---

Constructor & Destructor Documentation

BIndexedTableNode (  uint32_t  mode = IDatum::READ_WRITE  )

BIndexedTableNode (  const SContext &  context, uint32_t  mode = IDatum::READ_WRITE )

~BIndexedTableNode (   )  [protected, virtual]

---

Member Function Documentation

sptr< BIndexedDataNode > ActiveNodeAtLocked (  size_t  index  )

Retrieve node for a given row only if it already exists. This is like NodeAtLocked(), but doesn't create the node object if it doesn't already exist.

status_t AddColumn (  const SString &  name, uint32_t  type, size_t  maxSize, uint32_t  flags, const SValue &  extras )  [virtual]

Returns B_UNSUPPORTED. Implements ITable.

virtual ssize_t ColumnIndexOfLocked (  const SString &  entry  )  const [pure virtual]

Return the index for a column entry name in the node. Return an error code if the lookup failed, usually B_ENTRY_NOT_FOUND.

virtual SString ColumnNameAtLocked (  size_t  index  )  const [pure virtual]

Return the name of a column at a given index. This class guarantees it will not call this function with an invalid index.

SValue ColumnNames (   )  const [virtual]

Returns all column names. Implements ITable.

SContext Context (   )  [inline]

Disambiguate.

virtual size_t CountColumnsLocked (   )  const [pure virtual]

Return the total number of columns in the table.

virtual size_t CountEntriesLocked (   )  const [pure virtual]

From BIndexedIterable::CountEntriesLocked(). Implements BIndexedIterable.

status_t CreateRow (  SString *  inoutName, const SValue &  columns, uint32_t  flags = 0, sptr< INode > *  createdRow = NULL )  [virtual]

Returns B_UNSUPPORTED. Implements ITable.

void CreateSelectionLocked (  SValue *  inoutSelection, SValue *  outCookie )  const [virtual]

Perform selection on available columns. Reimplemented from BIndexedIterable.

status_t EntryAtLocked (  const sptr< IndexedIterator > &  it, size_t  index, uint32_t  flags, SValue *  key, SValue *  entry )  [virtual]

Implement using EntryNameAtLocked() and FetchEntryAtLocked(). Implements BIndexedIterable.

virtual ssize_t EntryIndexOfLocked (  const SString &  entry  )  const [pure virtual]

Return the index for an row entry name in the node. Return an error code if the lookup failed, usually B_ENTRY_NOT_FOUND.

SString EntryMimeTypeLocked (   )  const

Retrieve the MIME type of entries (row nodes).

virtual SString EntryNameAtLocked (  size_t  index  )  const [pure virtual]

Return the name of a row at a given index. This class guarantees it will not call this function with an invalid index.

status_t FetchEntryAtLocked (  const sptr< IndexedIterator > &  it, size_t  rowIndex, uint32_t  flags, SValue *  entry )

Retrieve row entry, taking care of COLLAPSE_NODE flag if needed. Note: The iterator it will be NULL when not called from an iterator.

status_t FetchValueAtLocked (  size_t  row, const sptr< BIndexedDataNode > &  rowNode, size_t  column, uint32_t  flags, SValue *  entry )

Use ValueAtLocked() to retrieve the entry and DatumAtLocked() if it needs to be wrapped in an IDatum. The rowNode is only needed if the REQUEST_DATA flag is NOT set. It is passed in here instead of looking it up inside for better performance when this method is called many times in a row, such as to implement COLLAPSE_NODE.

void FinishReadingAtLocked (  size_t  row, size_t  col, const void *  data )  const [virtual]

The default implementation does nothing.

void FinishWritingAtLocked (  size_t  row, size_t  col, void *  data )  [virtual]

The default implementation uses StoreValueAtLocked() to write the data.

SValue Inspect (  const sptr< IBinder > &  caller, const SValue &  which, uint32_t  flags )  [virtual]

Make both INode and IIterable accessible. Reimplemented from BnTable.

lock_status_t Lock (   )  const [virtual]

Disambiguate. Reimplemented from BGenericIterable.

status_t LookupEntry (  const SString &  entry, uint32_t  flags, SValue *  node )  [virtual]

Implement using EntryIndexOfLocked() and FetchEntryAtLocked(). Implements BGenericNode.

sptr< BIndexedTableNode::RowNode > NewRowNodeLocked (  size_t  index, uint32_t  mode )  [virtual]

Called when a new row object needs to be created. The default implementation instantiates and returns a new IndexedDatum object.

sptr< BIndexedDataNode > NodeAtLocked (  size_t  index  )

Retrieve a node of a given row. Returns an existing node if one is currently active for the index. Otherwise, calls NewRowNodeLocked() to create a new node and associates it with this index.

status_t RemoveColumn (  const SString &  name  )  [virtual]

Returns B_UNSUPPORTED. Implements ITable.

status_t RemoveRow (  const sptr< INode > &  row  )  [virtual]

Returns B_UNSUPPORTED. Implements ITable.

void ReportChangeAtLocked (  size_t  row, size_t  col, const sptr< IBinder > &  editor, uint32_t  changes, off_t  start = -1, off_t  length = -1 )  [virtual]

Similar to BStreamDatum::ReportChangeLocked(), using same change flags. Also pushes the ITable change events.

SValue Schema (   )  const [virtual]

Returns column schema info. Implements ITable.

void SetMimeType (  const SString &  value  )  [virtual]

By default, clients are not allowed to modify the MIME type. To use the normal BMetaDataNode implementation, override this to call directly to BGenericNode::SetMimeType(). To change the MIME type yourself, you can call SetMimeTypeLocked(). Reimplemented from BGenericNode.

void SetValueAtLocked (  size_t  row, size_t  col, const SValue &  value )

Convenience function for changing a value. The implementation takes care of calling ReportChangeAtLocked() for you if the value has changed. This is semantically the same as BStreamDatum::SetValue().

off_t SizeAtLocked (  size_t  row, size_t  col )  const [virtual]

The default implementation returns ValueAtLocked().Length().

const void * StartReadingAtLocked (  size_t  row, size_t  col, off_t  position, ssize_t *  inoutSize, uint32_t  flags )  const [virtual]

The default implementation return uses ValueAtLocked() to retrieve the data.

void * StartWritingAtLocked (  size_t  row, size_t  col, off_t  position, ssize_t *  inoutSize, uint32_t  flags )  [virtual]

The default implementation uses ValueAtLocked() to create a temporary buffer.

status_t StoreEntryMimeTypeLocked (  const SString &  mimeType  )

Set the MIME type that all entries (row nodes) will report.

status_t StoreSizeAtLocked (  size_t  row, size_t  col, off_t  size )  [virtual]

The default implementation uses ValueAtLocked() and StoreValueAtLocked() to change the size.

virtual status_t StoreValueAtLocked (  size_t  row, size_t  col, const SValue &  value )  [pure virtual]

Must be implemented by subclasses change the current value at an index.

status_t StoreValueTypeAtLocked (  size_t  row, size_t  col, uint32_t  type )  [virtual]

The default implementation uses ValueAtLocked() and StoreValueAtLocked() to change the type.

void Unlock (   )  const [virtual]

Disambiguate. Reimplemented from BGenericIterable.

void UpdateColumnIndicesLocked (  size_t  index, ssize_t  delta )

Adjust all active column datums due to items being added/removed. Your subclass must call this when it changes its set of column items.

void UpdateEntryIndicesLocked (  size_t  index, ssize_t  delta )

Adjust all active row nodes due to items being added/removed. Your subclass must call this when it changes its set of row items.

virtual SValue ValueAtLocked (  size_t  row, size_t  col )  const [pure virtual]

Must be implemented by subclasses to return the current value at an index.

uint32_t ValueTypeAtLocked (  size_t  row, size_t  col )  const [virtual]

The default implementation returns ValueAtLocked().Type().

---

Friends And Related Function Documentation

friend class RowNode [friend]

---

The documentation for this class was generated from the following files:

• IndexedTableNode.h
• IndexedTableNode.cpp

---

Generated on Wed Dec 28 22:33:30 2005 by Doxygen 1.4.4 for OpenBinder Documentation Version 1.0

PalmSource, Inc. © 2005