Index

DKDDOBase (Dynamic Data Object)

Purpose:

DKDDOBase is the base class used to represent a Dynamic Data Object (DDO).

Dynamic Data Object is the main class used to transfer data in and out of persistent store. It is a self-describing data object, flexible enough for representing data that originated from heterogeneous stores. Currently, DDO is used to represent data objects from about a dozen or more disparate data sources.

A DDO is essentially a container for data-items, such as EmployeeNo, Name, Address, VideoClip, myPicture, etc. Sometimes data-items are referred to as attributes. A data-item has a name, several properties, and one or more values. The name is usually a string, like "EmployeeNo", "myPicture", etc. Properties describe the characteristics of this data-item, for example, its basic type, like integer, string, decimal, etc. Non basic types are also supported, such as a reference to other data objects, a reference to a collection of strings, shorts, and other types. Other useful properties include the following:

Depending on the underlying back-end datastore support, properties can be persistent, that is, they can be saved in the persistent store, or they can be transient, only represented in memory. In addition to properties of a data-item, the DDO itself can have properties applicable to the whole DDO, like DDO type. The DDO class provides methods for adding data-items and properties, getting and setting properties, and more importantly, getting and setting data-item values.

Data-items are flexible and can be used to represent data from different groups or domains. To avoid naming conflicts between groups, the DDO class supports namespace for data-item names. Content Manager supports DK_CM_NAMESPACE_ATTR, DK_CM_NAMESPACE_LINK, and DK_CM_NAMESPACE_CHILD namespaces, for organizing attribute, link and child data-item names.

Important: Names are case sensitive, and data-items and property positions start from 1, not from 0.

A DDO has a persistent identifier (PID), which is used for locating the data object in the persistent store during retrieve, update and delete operations. A PID contains information about the datastore name, datastore type or entity name, and the address of the data object itself according to the underlying persistent store. See the DKPid class for details.

The DDO implementation is based on the OMG Persistent Object Services (POS) specification available at http://cgi.omg.org/docs/formatl/97-12-12.pdf

DKDDOBase is a subclass of dkDataObject. See also DKDDO (Dynamic Data Object)

Heirarchy:

dkDataObjectBase
 dkDataObject
   DKDDOBase
     DKDDO

Class summary:

typedef unsigned short ushort;
class DKDDOBase : public dkDataObject {
  public:
     DKDDOBase(ushort initialSize = DK_DDO_INITIAL_SIZE);
     DKDDOBase(const char* objectType, ushort initialSize = 
               DK_DDO_INITIAL_SIZE);
     DKDDOBase(const DKPid& pid, ushort initialSize = 
               DK_DDO_INITIAL_SIZE);
     virtual DKDDOBase();
     virtual short    protocol() const;
     virtual DKString  getObjectType() const;
     virtual void      setObjectType(const char * toObjectType);
     virtual DKBoolean updatable() const;
     virtual ushort    addData(const char* dataName = 0);
     virtual ushort    addDataProperty(ushort data_id
                                       const char* propertyName,
                                       const DKAny& propertyValue);
     virtual ushort    dataCount() const;
     virtual ushort    dataPropertyCount(ushort data_id) const;
     virtual void      setDataProperty(ushort data_id, 
                                       ushort property_id,
                                       const DKAny& property_value);
     virtual DKAny     getDataProperty(ushort data_id, 
                                       ushort property_id) const;
     virtual void      setDataPropertyName(ushort data_id, 
                                           ushort property_id,
                                           const char * property_name);
     virtual DKString  getDataPropertyName(ushort data_id, 
                                           ushort property_id) const;
     virtual void      setData(ushort data_id, 
                               const DKAny& data_value);
     virtual DKAny     getData(ushort data_id);
     virtual void      setDataName(ushort data_id, 
                                   const char * data_name );
     virtual DKString  getDataName(ushort data_id) const;
     virtual ushort    dataId(const char * data_name ) const;
     virtual ushort    dataPropertyId(ushort data_id,
                                      const char * property_name)
                                      const;
     virtual void      setNull(ushort data_id);
     virtual DKBoolean isNull(ushort data_id) const;
     virtual DKBoolean isDataSet(ushort data_id) const;
     virtual DKBoolean isDataPropertySet(ushort data_id, 
                                         ushort property_id) const;
     virtual DKAny     getDataByName(const char * data_name);
     virtual DKAny     getDataPropertyByName(ushort data_id, 
                                             const char* 
                                             property_name)  
                                             const;
     virtual DKAny     getDataPropertyByName(const char * 
                                             data_name,
                                             const char * 
                                             property_name) 
                                             const;
        // properties of this DDO
     virtual ushort    addProperty (const char * 
                                    property_name = 0);
     virtual ushort    addProperty (const char * 
                                    property_name, 
                                    const DKAny& 
                                    property_value);
     virtual ushort    propertyCount    () const;
     virtual void      setProperty      (ushort property_id, 
                                         const DKAny& 
                                         property_value);
     virtual DKAny     getProperty      (ushort property_id) const;
     virtual void      setPropertyName  (ushort property_id, 
                                         const char * 
                                         property_name);
     virtual DKString  getPropertyName  (ushort property_id) const;
     virtual ushort    propertyId       (const char * 
                                         property_name) 
                                         const;
     virtual DKAny     getPropertyByName (const char * 
                                          property_name) 
                                          const;
     virtual DKBoolean isPropertySet     (ushort property_id) const;
    };

Members:

Constructors
DKDDOBase(ushort initialSize = DK_DDO_INITIAL_SIZE);
DKDDOBase(const char* objectType, ushort initialSize = DK_DDO_INITIAL_SIZE);
DKDDOBase(const DKPid& pid, ushort initialSize = DK_DDO_INITIAL_SIZE);

A DDOBase object can be created by calling the constructor with or without supplying any parameter, or by copying information from another DDOBase.

Member functions

addData
Adds a new data-item to a DDO and returns the new data item number (data ID).

Exceptions

DKUsageError
Error messages:
  • Data definition not modifiable
  • Data object invalid
virtual ushort addProperty(const char * property_name = 0);

addDataProperty
Adds a new property to a given data-item and returns the new property number.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data property value already set
  • Data definition not modifiable
  • Data object invalid
virtual ushort addProperty(const char * property_name, const DKAny& property_value);

dataCount
Gets the number of data-items in this DDO.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
virtual ushort dataCount ( ) const;

dataPropertyCount
Gets the number of properties associated with this data-item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data object invalid
virtual ushort dataPropertyCount (ushort data_id) const;

setDataProperty
Sets the value of a given property in a data-item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Property ID invalid
  • Value type invalid
  • Data value already set
  • Data property not named
  • Data definition not modifiable
  • Data object invalid
  virtual void  setDataProperty (ushort data_id, ushort property_id, const DKAny& propertyValue);

getDataProperty
Gets the value of a given property in a data item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Property ID invalid
  • Data object invalid
  virtual DKAny  getDataProperty (ushort data_id, ushort property_id) const;

setDataPropertyName
Sets the name of a given property ID in a data-item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Property ID invalid
  • Property name invalid
  • Value type invalid
  • Data property value already set
  • Data definition not modifiable
  • Data object invalid
virtual void  setDataPropertyName (ushort data_id, ushort property_id, const char * property_name);

getDataPropertyName
Gets the name of a given property ID in a data-item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Property ID invalid
  • Data object invalid
  virtual DKString getDataPropertyName(ushort data_id, ushort property_id) const;

setData
Sets the value of a given data-item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • data item not nullable
  • Data property not set
  • data item not named
  • Value type invalid
  • Data object invalid
virtual void setData (ushort data_id, const DKAny& dataValue);

getData
Gets the value of a given data item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data object invalid
virtual DKAny  getData (ushort data_id);

setDataName
Sets the name of a given data-item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data name invalid
  • Data object invalid
virtual void setDataName (ushort data_id , const char * data_name);

getDataName
Gets the name of a given data-item.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data object invalid
virtual DKString getDataName (ushort data_id) const;

dataId
Gets the data ID of a given data-item name.

Exceptions

DKUsageError
Error messages:
  • Data name invalid
  • Data object invalid
virtual ushort dataId (const char * data_name) const;

dataPropertyId
Gets the property ID of a given property name in a data item.

Exceptions

DKUsageError
Error messages:
  • Data name invalid
  • Property name invalid
  • Data object invalid
virtual ushort dataPropertyId (ushort data_id, const char * property_name) const;

setNull
Sets the value of a data-item to a null value. The data-item must be nullable and the DDO must be updatable.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data object invalid
  • data-item not nullable
virtual void setNull (ushort data_id);

isNull
Returns a TRUE value if this data-item value is null or zero.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data object invalid
  • data-item not nullable
virtual DKBoolean isNull (ushort data_id) const;

isDataSet
Returns a TRUE value if this data-item value is already set.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data object invalid
virtual DKBoolean isDataSet (ushort data_id) const;

isDataPropertySet
Returns a TRUE value if the given property of a data item is set.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data object invalid
  • Property ID invalid
virtual DKBoolean isDataPropertySet (ushort data_id, ushort property_id) const;

getDataByName
Gets the value of a data-item, given its name.

Exceptions

DKUsageError
Error messages:
  • Data name invalid
  • Data object invalid
virtual DKAny  getDataByName (const char * data_name);

getDataPropertyByName
Gets the value of the given property name of a data-item.

Exceptions

DKUsageError
Error messages:
  • Data name invalid
  • Data object invalid
  • Property name invalid
virtual DKAny getDataPropertyByName(ushort data_id, const char* property_name) const; virtual DKAny getDataPropertyByName(const char * data_name, const char * property_name)const;  

getObjectType
Gets the object type of this DDO.
virtual DKString getObjectType() const;

setObjectType
Sets the object type of this DDO and synchronize it with the object type of its PID.
virtual void setObjectType (const char * aObjectType);

addProperty
Add a new property to this DDO and returns the new property number.

Exceptions

DKUsageError
Error messages:
  • Data definition not modifiable
  • Data object invalid
virtual ushort  addProperty(const char *  property_name = 0);

propertyCount
Gets the number of properties associated with this DDO.

Exceptions

DKUsageError
Error messages:
  • Data object invalid
virtual ushort propertyCount() const;

setProperty
Sets the value of a given property ID in this DDO.

Exceptions

DKUsageError
Error messages:
  • Property ID invalid
  • Value type invalid
  • Data property not named
  • Data definition not modifiable
  • Data object invalid
virtual void setProperty (ushort property_id, const DKAny&  property_value );

getProperty
Gets the value of a given property ID in this DDO.

Exceptions

DKUsageError
Error messages:
  • Property ID invalid
  • Data object invalid
virtual DKAny getProperty (ushort property_id) const;

setPropertyName
Sets the name of a given property ID in this DDO.

Exceptions

DKUsageError
Error messages:
  • Property ID invalid
  • Property name invalid
  • Value type invalid
  • Data property value already set
  • Data definition not modifiable
  • Data object invalid
  virtual void setPropertyName (ushort property_id, const char * property_name);

getPropertyName
Gets the name of a given property ID in this DDO.

Exceptions

DKUsageError
Error messages:
  • Property ID invalid
  • Data object invalid
virtual DKString getPropertyName (ushort  property_id) const;

propertyId
Gets the property ID of a given property-name in this DDO.

Exceptions

DKUsageError
Error messages:
  • Property name invalid
  • Data object invalid
virtual ushort propertyId (const char *  property_name) const;

getPropertyByName
Gets the value of the given property-name of this DDO.

Exceptions

DKUsageError
Error messages:
  • Data object invalid
  • Property name invalid
  virtual DKAny getPropertyByName (const char * property_name) const;

isPropertySet
Returns TRUE if the given property ID of this DDO is set.

Exceptions

DKUsageError
Error messages:
  • Data ID invalid
  • Data object invalid
  • Property ID invalid
virtual DKBoolean isPropertySet (ushort property_id) const;

protocol
Returns the protocol type supported by this data-object. In this case, it is DK_CM_DDO, which essentially means that this data-object can be made persistent with the help of an associated datastore object. The DK_CM_DDO protocol consists of get/setData, get/setDataProperty, and other methods in this object, which support the representation of a self describing data-object. Parameters: None Returns: The protocol
virtual short protocol() const;

Exceptions:

DKUsageError -- The following are possible error messages:

Data definition not modifiable:
the data definition part of this DDO is frozen and cannot be modified.

Data object invalid:
this DDO has an invalid structure; for example, an incorrect PID.

Data ID invalid:
the input data ID is invalid; for example, it's out of range or order.

Data name invalid:
the input data name is invalid; for example, it doesn't exist.

Property ID invalid:
the input property ID is invalid; for example, it's out of range order.

Property name invalid:
the input property name is invalid; for example, it doesn't exist.

Property name already exists:
the input property name is invalid, as a property name with the same name already exists.

Data property not named:
this data-item property does not have a name yet.

Data property not set:
this data-item property is not yet set.

Data property value already set:
the value of this data-item property is already set.

Value type invalid:
the data does not have a valid or supported type.

data-item cannot be set to null:
this data-item cannot be set to a null value.

data-item not named:
this data-item does not have a name yet.

(c) Copyright International Business Machines Corporation 1996, 2003. IBM Corp. All rights reserved.