Index

dkXDO (Extended Data Object)

Purpose:

The dkXDO is an abstract class that can represent a complex UDT (User Defined Type) or LOB (Large Object). You should subclass from dkXDO and provide methods relevant to the UDT or LOB being represented. This user-defined XDO subclass can either work with an associated DDO, or as a stand-alone object.

dkXDO extends the public interface of dkXDOBase mainly by defining independent datastore access Add/Retrieve/Update/Delete methods. These methods enable an application to store and retrieve the object's data to and from a datastore, without the existence of an associated DDO class object (stand-alone XDO). A stand-alone XDO must have its PID set in order to be able to locate the position in the datastore where it belongs. If the XDO is used in conjunction with the DDO, the PID is set automatically.

dkXDO inherits protocol from its parent dkDataObjectBase. It supports the following protocols:

Heirarchy:

dkDataObjectBase
 dkXDOBase
   dkXDO

Class summary:

 class dkXDO : public dkXDOBase  {
 
  public:
   virtual  ~dkXDO();
 
   // deprecated replaced by get/setPidObject 
   virtual void  setPid(const DKPid* aPid);
   virtual const DKPid*  getPid() const;
   virtual const DKPid*  getPidObject() = 0;
   virtual void  setPidObject(const DKPid* aPid) = 0;
   // Data access.
   virtual dkDataObjectBase&  add();
   virtual dkDataObjectBase&  add(const char* aFullFileName);
   virtual dkDataObjectBase&  retrieve();
   virtual dkDataObjectBase&  retrieve(const char*  aFileName);
   virtual dkDataObjectBase&  update();
   virtual dkDataObjectBase&  update(const char*  aFileName);
   virtual dkDataObjectBase&  del();
   virtual dkDataObjectBase&  del(DKBoolean flush);
   // Common Lob Accessor Functions :
   virtual dkDataObjectBase&  getContentToClientFile(const char* afileName, int fileOption) const =0;
   virtual dkDataObjectBase&  setContentFromClientFile(const char* afileName) =0;
   // Object assignment and copy
   virtual dkDataObjectBase&  operator= (const dkDataObjectBase& aXDO);
   virtual dkDataObjectBase&   copyData(const dkXDO& adkXDO) = 0;
   virtual DKBoolean compareData(const dkXDO& adkXDO) = 0;
   const   dkDatastore*    datastore() const;
   virtual void            setDatastore(dkDatastore* ds);
   virtual dkDatastore*    getDatastore() const;
   virtual DKBoolean       isContentChanged() const  = 0;
   virtual DKBoolean       isSet() const  = 0;
   short   protocol() const;
   virtual long     length() const;
   virtual long     size();
   virtual dkXDO*  cloneSkeleton() = 0;
   virtual unsigned long getAffiliatedType();  
   virtual void setAffiliatedType(unsigned long affiliatedType);
   virtual DKString getMimeType();
   virtual void setMimeType(const char* mimeType);
   virtual DKString getContentType();
   virtual void setContentType(const char* contentType);
   virtual DKString getContent() const = 0;
   virtual dkXDO&   setContent(const DKString& astring) = 0;
   virtual void getOption (long option, DKAny& value);
   virtual void setOption (long option, DKAny& value);
   virtual long  getRank();
   virtual void  setRank(long aRank);
   //extension methods 
   virtual void addExtension(const char* extensionName,
                             dkExtension* extensionObj);
   virtual void removeExtension(const char* extensionName);
   virtual const dkExtension* getExtension(const char* extensionName);   
   virtual DKString getClassName();
   virtual void setClassName(const char* className);
} 

Members:

Destructor
virtual  ~dkXDO();

Member functions

setPid
setPid has been deprecated and replaced by setPidObject.
virtual void  setPid(const DKPidXDO* aPidXDO) ;

getPid
getPid has been deprecated and replaced by getPidObject.
virtual const DKPidXDO*  getPid() const;

setPidObject
Sets the PID (persistent ID) information of this object with the new provided PID.
virtual void  setPidObject(const DKPidXDO* aPidXDO) ;

getPidObject
Gets a copy of the persistent ID object of this object.
virtual const DKPid*  getPidObject(); 

add
Add this XDO, identified by its PID, to the persistent datastore. A new object with the given PID will be created in the datastore; note that an object having the same PID cannot already exist, otherwise this method will throw an exception. The XDO itself is not changed. The filename could be a full path name. The add that takes a file will serve to help avoid any out-of-memory problems.
virtual dkDataObjectBase&  add();        virtual dkDataObjectBase&  add(const char* aFullFileName);

Note:
DKUsageError exception thrown if method is not implemented.

retrieve
Retrieves this XDO, identified by its PID, from the persistent datastore. The user can retrieve the content of the persistent datastore into the given filename, which can be an absolute pathname. For a very large object, this will serve to help avoid any out-of-memory problems.
virtual dkDataObjectBase&  retrieve();       virtual dkDataObjectBase&  retrieve(const char*  aFileName);

update
Updates the persistent data of this XDO, identified by its PID, in the persistent datastore. The XDO itself is not changed.
virtual dkDataObjectBase&  update();       virtual dkDataObjectBase&  update(const char*  aFileName);

Note:
DKUsageError exception thrown if method is not implemented.

del
Deletes the persistent data of this XDO, identified by its PID, in the persistent datastore. The XDO itself is not changed. The next delete method depends on the value of flush. If flush is TRUE, it will clear the content, otherwise the current content will be preserved. The default is to clear the current content, that is, flush is equal to TRUE.
virtual dkDataObjectBase&  del();       virtual dkDataObjectBase&  del(DKBoolean flush);

Note:
DKUsageError exception thrown if method is not implemented.

operator=
Assignment operator.
virtual dkDataObjectBase&  operator= (const dkDataObjectBase& aXDO);

copyData
Copies all relevant data from the source XDO to this XDO, except the PID.
virtual dkDataObjectBase& copyData(const dkXDO& adkXDO) = 0;

compareData
Compares all relevant data from the source XDO with this XDO, except the PID. This returns TRUE if both are the same.
virtual DKBoolean compareData(const dkXDO& adkXDO) = 0; 

datastore
Returns the datastore associated with this object.
const dkDatastore* datastore() const;

getDatastore
Returns the datastore associated with this object.
virtual dkDatastore* getDatastore() const;

setDatastore
Sets the datastore associated with this object.
virtual void            setDatastore(dkDatastore* ds);

isContentChanged
Returns TRUE if XDO content has changed.
virtual DKBoolean isContentChanged() const  = 0;

isSet
Returns TRUE if the part content is set.
virtual DKBoolean isSet() const  = 0;

protocol
Returns the protocol supported by this object, in this case DK_CM_XDO. This method should not be overridden by a subclass.
short protocol() const;

length
Gets the length of this object content in memory.
virtual long length() const;

Note:
DKUsageError exception thrown if method is not implemented.

size
Gets the size of this object from the datastore without retrieving the object content.
virtual long size();

cloneSkeleton
Clone this XDO with its persistent ID only, that is, with its data content set to empty.
virtual dkXDO*  cloneSkeleton() = 0;

getAffiliatedType
Gets the affiliated type of the object.
virtual unsigned long getAffiliatedType();

setAffiliatedType
Sets the affiliated type of the object.
virtual void setAffiliatedType(unsigned long affiliatedType);

Note:
DKUsageError exception thrown if method is not implemented.

getMimeType
Returns the mime type that corresponds to the object's content class.
virtual DKString getMimeType();

setMimeType
Sets the MIME type (for example, text or html).
virtual void setMimeType(const char* mimeType);

Note:
DKUsageError exception thrown if method is not implemented.

getContentType
Gets the document's file extension.
virtual DKString getContentType();

setContentType
Sets the document's file extension.
virtual void setContentType(const char* contentType);

Note:
DKUsageError exception thrown if method is not implemented.

getContent
Gets the stream object containing the large object (LOB) data of this object.
virtual DKString getContent() const = 0;

setContent
Replaces the document contents in memory with the input array.
virtual dkXDO& setContent(const DKString& astring) = 0;

getContentToClientFile
Copies the blob data of this object to the named file and path. FileOption 1 will create or overwrite an existing file; fileOption 2 will only create the file, but will also throw an exception if the file already exists; fileOption 3 appends to an existing file.
virtual dkDataObjectBase&  getContentToClientFile(const char* afileName, int fileOption) const =0;

setContentFromClientFile
Replaces the LOB data of this object with the contents of the file aFileName. The file must be accessible by the client.
virtual dkDataObjectBase&  setContentFromClientFile(const char* afileName) =0;

getOption
Gets a valid datastore option.
virtual void getOption (long option, DKAny& value);

setOption
Sets a valid datastore option.
virtual void setOption (long option, DKAny& value);

getRank
Gets the ranking value of a query.
virtual long  getRank();

setRank
Sets the ranking value of a query.
virtual void  setRank(long aRank);

addExtension
Add the extension object.
virtual void addExtension(const char* extensionName, dkExtension* extensionObj);

Note:
DKUsageError exception thrown if method is not implemented.

removeExtension
Remove an extension object.
virtual void removeExtension(const char* extensionName);

Note:
DKUsageError exception thrown if method is not implemented.

getExtension
Get an extension object.
virtual const dkExtension* getExtension(const char* extensionName);

Note:
DKUsageError exception thrown if method is not implemented.

getClassName
Gets the class name of this object.
virtual DKString getClassName();

setClassName
Sets the class name of this object.
virtual void setClassName(const char* className);

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