BSchemaTableNode Class Reference
[CoreDataManagerProvider]

#include <dmprovider/SchemaTableNode.h>

Inheritance diagram for BSchemaTableNode:

BMetaDataNode BGenericIterable BnCatalog BnTable BnReferable BBinder IReferable BBinder ITable BBinder ICatalog SSQLBuilder BnIterable BGenericNode List of all members.

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< IDatumCreateDatum (SString *name, uint32_t flags, status_t *err)
 Create a new IDatum object inside of this catalog.
virtual sptr< INodeCreateNode (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< RowNodeNodeForLocked (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< RowNodeNewRowNodeLocked (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: