BGenericNode Class Reference
[Data Model]

#include <storage/GenericNode.h>

Inheritance diagram for BGenericNode:

Detailed Description

This is the most generic base-class implementation of the INode interface.

The main purpose of this class is to deal with the mechanics of walking the node and basic management of attributes/meta-data.

XXX Should all of this functionality be here? There are some rare occasions where you will want a node without any meta data (that would be a node representing the meta data), in which case you still want to use BGenericNode for the other functionality; you'll need to override Attributes() et al to turn off the meta data functionality. I don't think there should be any other time you want such a node, though, so it seems like BGenericNode should be what we have here, fully functional.

INode Interface

Generic implementation of the INode interface. Note that you generally should never override these methods, instead customizing the new virtuals introduced by this class. Some very special implementations may override Attributes() and all of the meta data getter/setter methods.

virtual sptr< INode > Attributes () const

Returns a node to access this node's meta-data.

virtual nsecs_t CreationDate () const

Acquires the node lock and calls CreationDateLocked().

virtual SString MimeType () const

Acquires the node lock and calls MimeTypeLocked().

virtual nsecs_t ModifiedDate () const

Acquires the node lock and calls ModifiedDateLocked().

virtual void SetCreationDate (nsecs_t value)

Acquires the node lock and calls SetCreationDateLocked().

status_t SetCreationDateLocked (nsecs_t value)

Calls StoreCreationDateLocked() and updates datums, pushes event.

virtual void SetMimeType (const SString &value)

Acquires the node lock and calls SetMimeTypeLocked().

status_t SetMimeTypeLocked (const SString &value)

Calls StoreMimeTypeLocked() and updates datums, pushes event.

virtual void SetModifiedDate (nsecs_t value)

Acquires the node lock and calls SetModifiedDateLocked().

status_t SetModifiedDateLocked (nsecs_t value)

Calls StoreModifiedDateLocked() and updates datums, pushes event.

virtual status_t Walk (SString *path, uint32_t flags, SValue *node)

Takes care of standard node walking algorithm.

Bookkeeping

Creation, destruction, locking, etc.

BGenericNode (const SContext &context)

BGenericNode ()

virtual lock_status_t Lock () const

Lock the node's state.

virtual void Unlock () const

Unlock the node's state.

virtual ~BGenericNode ()

Meta Data Virtuals

You can override these methods to support additional meta-data in your node. The default implementation of them only supports the standard meta-data that is common to all nodes: mimeType, creationDate, and modifiedDate.
To implement your own meta-data, you can choose to either override all of the virtuals here, OR only override LookupMetaEntry() and Attributes(). In the latter case, you are supplying your own complete custom implementation for meta-data through the object returned by Attributes(); LookupMetaEntry() must also be implemented because it can be called by the standard Walk() implementation.

Note:
This API is TEMPORARY until the complete set of data model classes have been implemented (it depends on them for its internal implementation, which will have repercussions for how these APIs operate).

virtual size_t CountMetaEntriesLocked () const

Return the number of meta-data entries in the node.

virtual status_t CreateMetaEntry (const SString &name, const SValue &initialValue, sptr< IDatum > *outDatum=NULL)

Create a new piece of meta-data in the node.

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

Used by Walk() and others to find a meta-data entry in the node.

virtual status_t MetaEntryAtLocked (ssize_t index, uint32_t flags, SValue *key, SValue *entry)

Return a meta-data entry at a particular offset in the node.

virtual status_t RemoveMetaEntry (const SString &name)

Remove a piece of meta-data from the node.

virtual status_t RenameMetaEntry (const SString &old_name, const SString &new_name)

Change the name of a piece of meta-data in the node.

New Node Virtuals

Subclasses can override these (instead of the raw INode APIs) to customize the behavior of their node.

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

Called as part of walking with the CREATE_DATUM flag set.

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

Called as part of walking with the CREATE_NODE flag set.

virtual nsecs_t CreationDateLocked () const =0

You must implement this to return the creation date.

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

Used by Walk() to find a normal entry in the node.

virtual SString MimeTypeLocked () const

Default implementation always returns "application/vnd.palm.catalog".

virtual nsecs_t ModifiedDateLocked () const =0

You must implement this to return the last modification date.

virtual status_t StoreCreationDateLocked (nsecs_t value)

Default implementation does nothing, returning B_UNSUPPORTED.

virtual status_t StoreMimeTypeLocked (const SString &value)

Default implementation does nothing, returning B_UNSUPPORTED.

virtual status_t StoreModifiedDateLocked (nsecs_t value)

Default implementation does nothing, returning B_UNSUPPORTED.

Friends

class meta_datum

class node_state

Constructor & Destructor Documentation

BGenericNode ( )

BGenericNode ( const SContext & context )

~BGenericNode ( ) [protected, virtual]

Member Function Documentation

sptr< INode > Attributes ( ) const [virtual]

Returns a node to access this node's meta-data.

Implements INode.

size_t CountMetaEntriesLocked ( ) const [virtual]

Return the number of meta-data entries in the node.

Note:
This count is only of user meta-data. The standard BGenericNode meta-data is not included in the count. The default implementation returns 0.

Reimplemented in BMetaDataCatalog.

sptr< IDatum > CreateDatum ( SString * name,

uint32_t flags,

status_t * err

) [virtual]

Called as part of walking with the CREATE_DATUM flag set.
The default implementation simply returns NULL.
Reimplemented in BSchemaTableNode, BSchemaTableNode::RowNode, BCatalogDelegate, BGenericCatalog, BIndexedCatalog, and BCatalog.

status_t CreateMetaEntry ( const SString & name,

const SValue & initialValue,

sptr< IDatum > * outDatum = NULL

) [virtual]

Create a new piece of meta-data in the node.
The default implementation returns B_UNSUPPORTED to indicate that it can not create any new meta-data. Extend this to implement nodes that can contain additional meta-data.
Reimplemented in BMetaDataCatalog.

sptr< INode > CreateNode ( SString * name,

status_t * err

) [virtual]

Called as part of walking with the CREATE_NODE flag set.
The default implementation simply returns NULL.
Reimplemented in BSchemaTableNode, BSchemaTableNode::RowNode, BCatalogDelegate, BGenericCatalog, BIndexedCatalog, and BCatalog.

nsecs_t CreationDate ( ) const [virtual]

Acquires the node lock and calls CreationDateLocked().

Implements INode.

nsecs_t CreationDateLocked ( ) const [pure virtual]

You must implement this to return the creation date.

Implemented in BMetaDataNode, and BNodeDelegate.

lock_status_t Lock ( ) const [virtual]

Lock the node's state.
To keep itself consistent, this class provides a public lock that is used when doing read/write operations on the class state as well as the actual data. The default implemention of this method acquires an internal lock. You can override it to cause all internal implementation to acquire some other lock. Be sure to also override Unlock() if doing so.
Reimplemented in BSchemaRowIDJoin, BSchemaRowIDJoin::RowNode, BSchemaTableNode, BSchemaTableNode::RowNode, BCatalogDelegate, BIndexedDataNode, BIndexedTableNode, BIndexedTableNode::RowNode, BIndexedCatalog, and BCatalog.

virtual status_t LookupEntry ( const SString & entry,

uint32_t flags,

SValue * node

) [pure virtual]

Used by Walk() to find a normal entry in the node.
At this point you MUST deal correctly with the REQUEST_DATA and COLLAPSE_NODE flags, by either returning the actual value or an object.
Implemented in BSchemaRowIDJoin, BSchemaRowIDJoin::RowNode, BSchemaTableNode, BIndexedDataNode, BIndexedTableNode, BNodeDelegate, and BCatalog.

status_t LookupMetaEntry ( const SString & entry,

uint32_t flags,

SValue * node

) [virtual]

Used by Walk() and others to find a meta-data entry in the node.
At this point you MUST deal correctly with the REQUEST_DATA flag, by either returning an actual value or an object.
Reimplemented in BMetaDataCatalog.

status_t MetaEntryAtLocked ( ssize_t index,

uint32_t flags,

SValue * key,

SValue * entry

) [virtual]

Return a meta-data entry at a particular offset in the node.
Like LookupMetaEntry(), you must correctly respect the REQUEST_DATA flag.
Note:
The index is signed, so that 0 is the start of user meta data. The standard node meta-data is retrieved through negative numbers: -1 = mimeType, -2 = creationDate, -3 = modifiedDate; you should normally pass these through as-is to the base class.

Reimplemented in BMetaDataCatalog.

SString MimeType ( ) const [virtual]

Acquires the node lock and calls MimeTypeLocked().

Implements INode.

SString MimeTypeLocked ( ) const [virtual]

Default implementation always returns "application/vnd.palm.catalog".

Reimplemented in BSchemaRowIDJoin::RowNode, BSchemaTableNode::RowNode, BIndexedTableNode::RowNode, BMetaDataNode, and BNodeDelegate.

nsecs_t ModifiedDate ( ) const [virtual]

Acquires the node lock and calls ModifiedDateLocked().

Implements INode.

nsecs_t ModifiedDateLocked ( ) const [pure virtual]

You must implement this to return the last modification date.

Implemented in BMetaDataNode, and BNodeDelegate.

status_t RemoveMetaEntry ( const SString & name ) [virtual]

Remove a piece of meta-data from the node.
The default implementation returns B_UNSUPPORTED to indicate that it can not remove meta-data.
Reimplemented in BMetaDataCatalog.

status_t RenameMetaEntry ( const SString & old_name,

const SString & new_name

) [virtual]

Change the name of a piece of meta-data in the node.
The default implementation returns B_UNSUPPORTED to indicate that it can not rename meta-data.
Reimplemented in BMetaDataCatalog.

void SetCreationDate ( nsecs_t value ) [virtual]

Acquires the node lock and calls SetCreationDateLocked().

Implements INode.

status_t SetCreationDateLocked ( nsecs_t value )

Calls StoreCreationDateLocked() and updates datums, pushes event.

void SetMimeType ( const SString & value ) [virtual]

Acquires the node lock and calls SetMimeTypeLocked().

Implements INode.
Reimplemented in BSchemaRowIDJoin, BSchemaTableNode, and BIndexedTableNode.

status_t SetMimeTypeLocked ( const SString & value )

Calls StoreMimeTypeLocked() and updates datums, pushes event.

void SetModifiedDate ( nsecs_t value ) [virtual]

Acquires the node lock and calls SetModifiedDateLocked().

Implements INode.

status_t SetModifiedDateLocked ( nsecs_t value )

Calls StoreModifiedDateLocked() and updates datums, pushes event.

status_t StoreCreationDateLocked ( nsecs_t value ) [virtual]

Default implementation does nothing, returning B_UNSUPPORTED.

Reimplemented in BMetaDataNode, and BNodeDelegate.

status_t StoreMimeTypeLocked ( const SString & value ) [virtual]

Default implementation does nothing, returning B_UNSUPPORTED.

Reimplemented in BSchemaRowIDJoin::RowNode, BSchemaTableNode::RowNode, BIndexedTableNode::RowNode, BMetaDataNode, and BNodeDelegate.

status_t StoreModifiedDateLocked ( nsecs_t value ) [virtual]

Default implementation does nothing, returning B_UNSUPPORTED.

Reimplemented in BMetaDataNode, and BNodeDelegate.

void Unlock ( ) const [virtual]

Unlock the node's state.

Reimplemented in BSchemaRowIDJoin, BSchemaRowIDJoin::RowNode, BSchemaTableNode, BSchemaTableNode::RowNode, BCatalogDelegate, BIndexedDataNode, BIndexedTableNode, BIndexedTableNode::RowNode, BIndexedCatalog, and BCatalog.

status_t Walk ( SString * path,

uint32_t flags,

SValue * node

) [virtual]

Takes care of standard node walking algorithm.

Implements INode.

Friends And Related Function Documentation

friend class meta_datum [friend]

friend class node_state [friend]

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


INode Interface
Generic implementation of the INode interface. Note that you generally should never override these methods, instead customizing the new virtuals introduced by this class. Some very special implementations may override Attributes() and all of the meta data getter/setter methods.
virtual sptr< INode >	Attributes () const
	Returns a node to access this node's meta-data.
virtual nsecs_t	CreationDate () const
	Acquires the node lock and calls CreationDateLocked().
virtual SString	MimeType () const
	Acquires the node lock and calls MimeTypeLocked().
virtual nsecs_t	ModifiedDate () const
	Acquires the node lock and calls ModifiedDateLocked().
virtual void	SetCreationDate (nsecs_t value)
	Acquires the node lock and calls SetCreationDateLocked().
status_t	SetCreationDateLocked (nsecs_t value)
	Calls StoreCreationDateLocked() and updates datums, pushes event.
virtual void	SetMimeType (const SString &value)
	Acquires the node lock and calls SetMimeTypeLocked().
status_t	SetMimeTypeLocked (const SString &value)
	Calls StoreMimeTypeLocked() and updates datums, pushes event.
virtual void	SetModifiedDate (nsecs_t value)
	Acquires the node lock and calls SetModifiedDateLocked().
status_t	SetModifiedDateLocked (nsecs_t value)
	Calls StoreModifiedDateLocked() and updates datums, pushes event.
virtual status_t	Walk (SString path, uint32_t flags, SValue node)
	Takes care of standard node walking algorithm.
Bookkeeping
Creation, destruction, locking, etc.
	BGenericNode (const SContext &context)
	BGenericNode ()
virtual lock_status_t	Lock () const
	Lock the node's state.
virtual void	Unlock () const
	Unlock the node's state.
virtual	~BGenericNode ()
Meta Data Virtuals
You can override these methods to support additional meta-data in your node. The default implementation of them only supports the standard meta-data that is common to all nodes: mimeType, creationDate, and modifiedDate. To implement your own meta-data, you can choose to either override all of the virtuals here, OR only override LookupMetaEntry() and Attributes(). In the latter case, you are supplying your own complete custom implementation for meta-data through the object returned by Attributes(); LookupMetaEntry() must also be implemented because it can be called by the standard Walk() implementation. Note: This API is TEMPORARY until the complete set of data model classes have been implemented (it depends on them for its internal implementation, which will have repercussions for how these APIs operate).
virtual size_t	CountMetaEntriesLocked () const
	Return the number of meta-data entries in the node.
virtual status_t	CreateMetaEntry (const SString &name, const SValue &initialValue, sptr< IDatum > *outDatum=NULL)
	Create a new piece of meta-data in the node.
virtual status_t	LookupMetaEntry (const SString &entry, uint32_t flags, SValue *node)
	Used by Walk() and others to find a meta-data entry in the node.
virtual status_t	MetaEntryAtLocked (ssize_t index, uint32_t flags, SValue key, SValue entry)
	Return a meta-data entry at a particular offset in the node.
virtual status_t	RemoveMetaEntry (const SString &name)
	Remove a piece of meta-data from the node.
virtual status_t	RenameMetaEntry (const SString &old_name, const SString &new_name)
	Change the name of a piece of meta-data in the node.
New Node Virtuals
Subclasses can override these (instead of the raw INode APIs) to customize the behavior of their node.
virtual sptr< IDatum >	CreateDatum (SString name, uint32_t flags, status_t err)
	Called as part of walking with the CREATE_DATUM flag set.
virtual sptr< INode >	CreateNode (SString name, status_t err)
	Called as part of walking with the CREATE_NODE flag set.
virtual nsecs_t	CreationDateLocked () const =0
	You must implement this to return the creation date.
virtual status_t	LookupEntry (const SString &entry, uint32_t flags, SValue *node)=0
	Used by Walk() to find a normal entry in the node.
virtual SString	MimeTypeLocked () const
	Default implementation always returns "application/vnd.palm.catalog".
virtual nsecs_t	ModifiedDateLocked () const =0
	You must implement this to return the last modification date.
virtual status_t	StoreCreationDateLocked (nsecs_t value)
	Default implementation does nothing, returning B_UNSUPPORTED.
virtual status_t	StoreMimeTypeLocked (const SString &value)
	Default implementation does nothing, returning B_UNSUPPORTED.
virtual status_t	StoreModifiedDateLocked (nsecs_t value)
	Default implementation does nothing, returning B_UNSUPPORTED.
Friends
class	meta_datum
class	node_state

BGenericNode Class Reference [Data Model]

Detailed Description

INode Interface

Bookkeeping

Meta Data Virtuals

New Node Virtuals

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

BGenericNode Class Reference
[Data Model]