BSchemaTableNode Class Reference
[CoreDataManagerProvider]

#include <dmprovider/SchemaTableNode.h>

Inheritance diagram for BSchemaTableNode:

Detailed Description

INode providing access to a single table in the Data Manager.

This class can be instantiated by yourself on a particular schema database, or generated for you by BSchemaDatabaseNode.

Todo:

Implement efficient IDatum stream read/write operations.

Fix data access to use cursor ID instead of always row ID.

Implement adding and removing of columns in underlying table.

Make everything update when columns are added/removed.

Note:: These classes are not a part of the OpenBinder build, but included as an example for other similar implementations.

ITable Implementation

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

Add a new column to the table.

virtual SValue ColumnNames () const

Return set of column names.

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

Create a new row in the table.

virtual status_t RemoveColumn (const SString &name)

Remove an existing column from the table.

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

Remove an existing row from the table.

virtual SValue Schema () const

Return all information about columns.

ICatalog Implementation

virtual status_t AddEntry (const SString &name, const SValue &entry)

Add or modify an entry in the catalog.

virtual sptr< IDatum > CreateDatum (SString *name, uint32_t flags, status_t *err)

Create a new IDatum object inside of this catalog.

virtual sptr< INode > CreateNode (SString *name, status_t *err)

Create a new INode in this catalog.

virtual status_t RemoveEntry (const SString &name)

Remove an existing entry from the catalog.

virtual status_t RenameEntry (const SString &entry, const SString &name)

Change the name of an entry in the catalog.

Bookkeeping

Creation, destruction, locking, etc.

BSchemaTableNode (const SContext &context, const SDatabase &database, const SString &table, const SString &keyColumn=SString(), const SString &refPath=SString())

SContext Context ()

Disambiguate.

virtual void InitAtom ()

Open and initialize the database.

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

Make INode, IIterable, ITable, and IReferable accessible.

virtual lock_status_t Lock () const

Disambiguate.

status_t StatusCheck ()

Returns initialization state of object, such as error code when opening database.

virtual void Unlock () const

Disambiguate.

virtual ~BSchemaTableNode ()

Data Model Implementation

Provide default implementation based on new capabilities.

ssize_t ColumnIndexOfLocked (const SString &entry) const

Return the index for a column entry name in the table.

SString ColumnNameAtLocked (size_t index) const

Return the name of a column at a given index.

type_code ColumnTypeAtLocked (size_t index) const

Return the type of a column at a given index.

size_t CountColumnsLocked () const

Returns the total number of columns in the table.

SString EntryNameForLocked (uint32_t rowID) const

Return the name associated with a particular row ID.

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

Implemented by calling LookupNode().

virtual status_t LookupNode (const SString &entry, sptr< RowNode > *outNode)

Implemented by converting name to a rowID and then calling NodeForLocked().

virtual void MapSQLOrderColumn (SValue *inoutColumnName, SValue *inoutOrder) const

Map custom columns to underlying database columns when sorting by them.

sptr< RowNode > NodeForLocked (uint32_t rowID)

Return INode object for a particular table row ID.

virtual void ReportChangeAtLocked (size_t rowid, 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.

bool RowIDIsValidLocked (uint32_t rowID) const

Return true if the given row ID exists in the table.

Object Generation

virtual sptr< GenericIterator > NewGenericIterator (const SValue &args)

Create and return a new iterator object.

virtual sptr< RowNode > NewRowNodeLocked (uint32_t rowID)

Called when a new row object needs to be created.

IReferable Implementation

virtual SString Reference () const

Official path to this object.

Configuration

Functions for customizing how the table is exposed. See the CustomColumn class for the API for adding new computed columns to the table.

SString RowMimeTypeLocked () 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 StoreRowMimeTypeLocked (const SString &mimeType)

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

SString TableName () const

Return the name of this table.

Friends

class CustomColumn

class DataAccessor

class QueryIterator

class RowNode

Classes

struct column_info

struct custom_column_info

class CustomColumn

Base class for implementing custom column data in BSchemaTableNode. More...

class DataAccessor

Class providing direct access to BSchemaTableNode data. More...

class QueryIterator

Iterator over a BSchemaTableNode. More...

class RowNode

Node object generated for a row in BSchemaTableNode. More...

Constructor & Destructor Documentation

BSchemaTableNode ( const SContext & context,

const SDatabase & database,

const SString & table,

const SString & keyColumn = SString(),

const SString & refPath = SString()

)

~BSchemaTableNode ( ) [protected, virtual]

Member Function Documentation

status_t AddColumn ( const SString & name,

uint32_t typeCode,

size_t maxSize,

uint32_t flags,

const SValue & extras

) [virtual]

Add a new column to the table.

Parameters:

[in] name Name of the new column. Must be unique.

[in] typeCode Data type of the new column, such as B_INT32_TYPE.

[in] maxSize For data types that are variable length (such as B_STRING_TYPE), this is the maximum amount of data it can contain. For fixed-length types, this is ignored, or the table may simply ignore it completely and not impose a size limit.

[in] flags Additional information about the column.

[in] extras For future extension.

Returns:
B_OK if the column was successfully added, B_NAME_IN_USE if there is already a column with this name, etc.
Some tables are dynamic, allow you to add and/or remove columns. If supported, this API lets you create a new column in the table.
Implements ITable.

status_t AddEntry ( const SString & name,

const SValue & entry

) [virtual]

Add or modify an entry in the catalog.

Parameters:

[in] name Desired name of the entry.

[in] entry Data or object for the entry.

Returns:
B_OK on success, else an error code.
AddEntry() is a general way to place new entries into a catalog. There are two main ways it can be useful. The first is as an equivalent to the INode::REQUEST_DATA hint for reading entries –- if you supply an SValue of data to ddEntry(), it can create a new entry with that data, without requiring an intermediate operation through an IDatum object.
The second reason for using this API is to add new types of objects to the catalog – if the SValue contains an IBinder object, the given object will be directly added as the new entry. This latter approach allows you to create places where the namespace crosses processes, mount new types of directories in the namespace, etc. Note, however, that many catalogs (such as one representing a filesystem) will not be able to host references to external objects.
Contrast this with CreateNode() and CreateDatum(), which creates new entry objects that are owned and managed by the catalog.

Todo:
This API should not allow both creation of new entries and modification of existing entries.

Todo:
This API should work more like CreateDatum(), where the name is an in/out parameter, and it should be able to return the created object as an optional output. Perhaps this functionality should be moved to CreateNode() and CreateDatum(), and this method changed to ReplaceEntry() to only modify an existing entry.

Implements ICatalog.

ssize_t ColumnIndexOfLocked ( const SString & entry ) const

Return the index for a column entry name in the table.
Returns B_ENTRY_NOT_FOUND if no column with the given name exists.

SString ColumnNameAtLocked ( size_t index ) const

Return the name of a column at a given index.
The index must be in the range of [0..CountColumnsLocked()]. It does no bounds checking for you.

SValue ColumnNames ( ) const [virtual]

Return set of column names.

Todo:
Should be replaced with an IIterable interface.

Implements ITable.

type_code ColumnTypeAtLocked ( size_t index ) const

Return the type of a column at a given index.
The index must be in the range of [0..CountColumnsLocked()]. It does no bounds checking for you.

SContext Context ( ) [inline]

Disambiguate.

size_t CountColumnsLocked ( ) const

Returns the total number of columns in the table.

sptr< IDatum > CreateDatum ( SString * name,

uint32_t flags,

status_t * err

) [virtual]

Create a new IDatum object inside of this catalog.

Parameters:

[in,out] name Incoming, the desired name for the new entry. Outgoing, the actual name that was used. Some catalogs may completely ignore your desired name and use their own. Alternatively, a catalog may use your name as-is, and return an error if an entry with that name already exists.

[in] flags Additional options. Always set to 0.

[out] err B_OK on success, else an error code.

Returns:
The newly created IDatum, or NULL on failure.
This is like CreateNode() (see that API for further details), but creates an object implementing the IDatum interface and thus allowing you to place actual data under this entry.
Note that the returned object may very well support other interfaces (including INode), however its main purpose is to hold data for you.
Implements ICatalog.

sptr< INode > CreateNode ( SString * name,

status_t * err

) [virtual]

Create a new INode in this catalog.

Parameters:

[in,out] name Incoming, the desired name for the new entry. Outgoing, the actual name that was used. Some catalogs may completely ignore your desired name and use their own. Alternatively, a catalog may use your name as-is, and return an error if an entry with that name already exists.

[out] err B_OK on success, else an error code.

Returns:
The newly created INode, or NULL on failure.
Use this API to create a new subdirectory kind of object inside of this catalog. The returned object will be at least an INode that can itself contain one or more child entries. However, the details of how the node INode works are entirely dependent on this containing catalog: it could start out empty and have its own ICatalog interface through which you can add any arbitrary entries, start out with a fixed set of entries that can not be changed, etc.
This, along with CreateDatum(), is the mechanism you should normally use when entries in a particular catalog, because they allow the catalog to ensure that objects with the correct implementation are created. For example, if the catalog is on a filesystem, it will need to modify the filesystem data to hold the new structure and create and return a proxy object for the new entry it just created.
Even in a generic catalog the use of this function is important, since it ensures objects are created in the same process as the parent directory. Consider, for example, an application that wishes to create a node with some data that will stay around after the application itself exits.
Contrast this with AddEntry(), which if called with an IBinder object will place a reference to that object in the catalog.
Implements ICatalog.

status_t CreateRow ( SString * name,

const SValue & columns,

uint32_t flags = 0,

sptr< INode > * createdRow = NULL

) [virtual]

Create a new row in the table.

Parameters:

[in,out] name Incoming, the desired name for the new row. Outgoing, the actual name that was used. Some table may completely ignore your desired name and use their own. Alternatively, a table may use your name as-is, and return an error if an entry with that name already exists. A table may even not have names at all, in which case the name will be returned with the value "".

[in] columns Any initial values you would like for the columns in this row. This is a set of mappings, where the key is the name of the column and the value is the data to place in the row for that column.

[in] flags Additional control flags. None currently defined.

[out] createdRow Optional output of the INode object representing the new row.

Returns:
B_OK on success, else an appropriate error code.

Todo:
This should probably be removed from this interface, and the ICatalog::CreateNode() API extended to have all of this functionality.

Implements ITable.

SString EntryNameForLocked ( uint32_t rowID ) const

Return the name associated with a particular row ID.

void InitAtom ( ) [virtual]

Open and initialize the database.

Reimplemented from SAtom.

SValue Inspect ( const sptr< IBinder > & caller,

const SValue & which,

uint32_t flags

) [virtual]

Make INode, IIterable, ITable, and IReferable accessible.

Reimplemented from BnReferable.

lock_status_t Lock ( ) const [virtual]

Disambiguate.

Reimplemented from BGenericIterable.

status_t LookupEntry ( const SString & entry,

uint32_t flags,

SValue * node

) [virtual]

Implemented by calling LookupNode().

Implements BGenericNode.

status_t LookupNode ( const SString & entry,

sptr< RowNode > * outNode

) [virtual]

Implemented by converting name to a rowID and then calling NodeForLocked().

void MapSQLOrderColumn ( SValue * inoutColumnName,

SValue * inoutOrder

) const [virtual]

Map custom columns to underlying database columns when sorting by them.

Reimplemented from SSQLBuilder.

sptr< BSchemaTableNode::GenericIterator > NewGenericIterator ( const SValue & args ) [virtual]

Create and return a new iterator object.
Derived classes need to implement this to return their own GenericIterator subclass.
Implements BGenericIterable.

sptr< BSchemaTableNode::RowNode > NewRowNodeLocked ( uint32_t rowID ) [virtual]

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

sptr< BSchemaTableNode::RowNode > NodeForLocked ( uint32_t rowID )

Return INode object for a particular table row ID.

SString Reference ( ) const [virtual]

Official path to this object.
This property holds the canonical path at which you can find the object being queried. The returned path is always of the form "/some/path/to/me"; that is, SContext::Lookup() can be used to resolve the path back to the object.

Note:
Currently SContext::Lookup() always uses IDatum::REQUEST_DATA, so it will not work for retrieving IDatum objects. This should be fixed.

Implements IReferable.

status_t RemoveColumn ( const SString & name ) [virtual]

Remove an existing column from the table.

Parameters:

[in] name Name of the column to be removed.

Returns:
B_OK if the column was successfully added, B_NAME_NOT_FOUND if there is no column with the given name, etc.
Some tables are dynamic, allow you to add and/or remove columns. If supported, this API lets you remove columns from the table.
Implements ITable.

status_t RemoveEntry ( const SString & name ) [virtual]

Remove an existing entry from the catalog.

Parameters:

[in] name Name of the entry to be removed.

Returns:
B_OK if the entry was removed, some other error code on error. In particular, B_ENTRY_NOT_FOUND if there is not an entry with the given name.

Implements ICatalog.

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

Remove an existing row from the table.

Parameters:

[in] row The row to be removed.

Returns:
B_OK if the entry was removed, some other error code on error. In particular, B_ENTRY_NOT_FOUND if the given INode does not map to a row in the table.
This is like ICatalog::RemoveEntry(), but allows you to identify the row to be removed through its INode object. This allows it to work with tables that do not have names for their rows -- that is, a table that is only an IIterable.

Todo:
This should probably be removed from this interface, and put on ICatalog.

Implements ITable.

status_t RenameEntry ( const SString & entry,

const SString & name

) [virtual]

Change the name of an entry in the catalog.

Parameters:

[in] entry Name of the entry to be renamed.

[in] name New name for the entry.

Returns:
B_OK if the entry was removed, some other error code on error. Most common errors are B_ENTRY_NOT_FOUND (entry does not exist), B_ENTRY_EXISTS (there is already an existing entry named name), B_UNSUPPORTED (this catalog does not support renaming).

Implements ICatalog.

void ReportChangeAtLocked ( size_t rowid,

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.

bool RowIDIsValidLocked ( uint32_t rowID ) const

Return true if the given row ID exists in the table.

SString RowMimeTypeLocked ( ) const

Retrieve the MIME type of entries (row nodes).

SValue Schema ( ) const [virtual]

Return all information about columns.

Todo:
Should be replaced with an IIterable interface.

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.

status_t StatusCheck ( )

Returns initialization state of object, such as error code when opening database.

status_t StoreRowMimeTypeLocked ( const SString & mimeType )

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

SString TableName ( ) const

Return the name of this table.

void Unlock ( ) const [virtual]

Disambiguate.

Reimplemented from BGenericIterable.

Friends And Related Function Documentation

friend class CustomColumn [friend]

friend class DataAccessor [friend]

friend class QueryIterator [friend]

friend class RowNode [friend]

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


ITable Implementation
virtual status_t	AddColumn (const SString &name, uint32_t typeCode, size_t maxSize, uint32_t flags, const SValue &extras)
	Add a new column to the table.
virtual SValue	ColumnNames () const
	Return set of column names.
virtual status_t	CreateRow (SString name, const SValue &columns, uint32_t flags=0, sptr< INode > createdRow=NULL)
	Create a new row in the table.
virtual status_t	RemoveColumn (const SString &name)
	Remove an existing column from the table.
virtual status_t	RemoveRow (const sptr< INode > &row)
	Remove an existing row from the table.
virtual SValue	Schema () const
	Return all information about columns.
ICatalog Implementation
virtual status_t	AddEntry (const SString &name, const SValue &entry)
	Add or modify an entry in the catalog.
virtual sptr< IDatum >	CreateDatum (SString name, uint32_t flags, status_t err)
	Create a new IDatum object inside of this catalog.
virtual sptr< INode >	CreateNode (SString name, status_t err)
	Create a new INode in this catalog.
virtual status_t	RemoveEntry (const SString &name)
	Remove an existing entry from the catalog.
virtual status_t	RenameEntry (const SString &entry, const SString &name)
	Change the name of an entry in the catalog.
Bookkeeping
Creation, destruction, locking, etc.
	BSchemaTableNode (const SContext &context, const SDatabase &database, const SString &table, const SString &keyColumn=SString(), const SString &refPath=SString())
SContext	Context ()
	Disambiguate.
virtual void	InitAtom ()
	Open and initialize the database.
virtual SValue	Inspect (const sptr< IBinder > &caller, const SValue &which, uint32_t flags)
	Make INode, IIterable, ITable, and IReferable accessible.
virtual lock_status_t	Lock () const
	Disambiguate.
status_t	StatusCheck ()
	Returns initialization state of object, such as error code when opening database.
virtual void	Unlock () const
	Disambiguate.
virtual	~BSchemaTableNode ()
Data Model Implementation
Provide default implementation based on new capabilities.
ssize_t	ColumnIndexOfLocked (const SString &entry) const
	Return the index for a column entry name in the table.
SString	ColumnNameAtLocked (size_t index) const
	Return the name of a column at a given index.
type_code	ColumnTypeAtLocked (size_t index) const
	Return the type of a column at a given index.
size_t	CountColumnsLocked () const
	Returns the total number of columns in the table.
SString	EntryNameForLocked (uint32_t rowID) const
	Return the name associated with a particular row ID.
virtual status_t	LookupEntry (const SString &entry, uint32_t flags, SValue *node)
	Implemented by calling LookupNode().
virtual status_t	LookupNode (const SString &entry, sptr< RowNode > *outNode)
	Implemented by converting name to a rowID and then calling NodeForLocked().
virtual void	MapSQLOrderColumn (SValue inoutColumnName, SValue inoutOrder) const
	Map custom columns to underlying database columns when sorting by them.
sptr< RowNode >	NodeForLocked (uint32_t rowID)
	Return INode object for a particular table row ID.
virtual void	ReportChangeAtLocked (size_t rowid, 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.
bool	RowIDIsValidLocked (uint32_t rowID) const
	Return true if the given row ID exists in the table.
Object Generation
virtual sptr< GenericIterator >	NewGenericIterator (const SValue &args)
	Create and return a new iterator object.
virtual sptr< RowNode >	NewRowNodeLocked (uint32_t rowID)
	Called when a new row object needs to be created.
IReferable Implementation
virtual SString	Reference () const
	Official path to this object.
Configuration
Functions for customizing how the table is exposed. See the CustomColumn class for the API for adding new computed columns to the table.
SString	RowMimeTypeLocked () 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	StoreRowMimeTypeLocked (const SString &mimeType)
	Set the MIME type that all entries (row nodes) will report.
SString	TableName () const
	Return the name of this table.
Friends
class	CustomColumn
class	DataAccessor
class	QueryIterator
class	RowNode
Classes
struct	column_info
struct	custom_column_info
class	CustomColumn
	Base class for implementing custom column data in BSchemaTableNode. More...
class	DataAccessor
	Class providing direct access to BSchemaTableNode data. More...
class	QueryIterator
	Iterator over a BSchemaTableNode. More...
class	RowNode
	Node object generated for a row in BSchemaTableNode. More...

BSchemaTableNode Class Reference [CoreDataManagerProvider]

Detailed Description

ITable Implementation

ICatalog Implementation

Bookkeeping

Data Model Implementation

Object Generation

IReferable Implementation

Configuration

Friends

Classes

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

BSchemaTableNode Class Reference
[CoreDataManagerProvider]