Index

dkResource

Purpose:

dkResource is a common abstract class used to represent resources and provides a generic interface to resource object functions. It can represent a simple LOB (large object) or a more complex type defined by the user, such as video stream, audio, large text, and so forth. A resource object consists of a content, usually a LOB (large object), and the meta-data or attributes describing the content. To implement more specific resource types in your application, subclass dkResource. Currently, this class library provides the following subclasses:

Since: Version 8

Class summary:

class DKEXPORT dkResource : public DKDDO, public dkXDO
{
  public:
        virtual  ~dkResource();
        virtual const DKPid*  getPidObject();
        virtual void  setPidObject(const DKPid* aPid);
 
        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);
        virtual dkDataObjectBase&  getContentToClientFile(const char* afileName,int fileOption) const =0;
        virtual dkDataObjectBase&  setContentFromClientFile(const char* afileName) =0;
        virtual dkDataObjectBase&  operator= (const dkDataObjectBase& aXDO);
        virtual dkDataObjectBase&   copyData(const dkXDO& adkXDO) = 0;       
      virtual DKBoolean  compareData(const dkXDO& adkXDO);  
      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();  // for ANNOTATION, NOTES, etc
      virtual void setAffiliatedType(unsigned long affiliatedType);
      virtual DKString getMimeType();
      virtual void setMimeType(const char* mimeType);
      virtual DKString getContentType();          // e.g: ASCII, JPG, AVI, GIF, etc.
      virtual void setContentType(const char* contentType);
      virtual DKString getContent() const = 0;
      virtual dkDataObjectBase& 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);
       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:

Constructors and destructor
virtual ~dkResource();

Member functions

setDatastore
Sets this datastore as the one associated with this resource; that is, the datastore to keep the persistent copy of this resource.

Parameters:ds - A datastore object

virtual void setDatastore(dkDatastore* ds);

getDatastore
Gets the datastore.

Returns: the datastore object

virtual dkDatastore* getDatastore();

add
Adds or stores the content and meta-data of this resource object into the persistent store. If the content is not available, then only the meta-data is created. The content can be added later.

Returns: A reference to this resource object

virtual dkDataObjectBase&  add();

Note: DKUsageError exception is thrown if this method is not implemented.

add
Adds or stores the content and meta-data of this resource object into the persistent store with an input file. If the content is stored directly from the input file into the persistent store.

Parameters:aFullFileName - a fully qualified path and file name, The default is in the current directory

Returns:a reference to this resource object

virtual dkDataObjectBase&  add(const char* aFullFileName);

Note: DKUsageError exception is thrown if this method is not implemented.

retrieve
Retrieves the meta-data and the content from the persistent store.

Returns: a reference to this resource object

virtual dkDataObjectBase&  retrieve();

retrieve
Retrieves the meta-data and the content from the persistent store to memory, but streams the content directly into the specified filename.

Parameters: aFileName - a fully qualified path and file name, The default is in the current directory

Returns: A reference to this resource object

virtual dkDataObjectBase&  retrieve(const char* aFileName);

Note: DKUsageError exception is thrown if this method is not implemented.

update
Updates the meta-data and content of this resource in the persistent store from the value in-memory.

Returns: A reference to this resource object

virtual dkDataObjectBase&  update();

update
Updates the meta-data and content of this resource in the persistent store, but updates the content directly from the content from the specified file name.

Parameters: aFileName - a fully qualified path and file name, The default is in the current directory

Returns: A reference to this resource object

virtual dkDataObjectBase&  update(const char*  aFileName);

Note: DKUsageError exception is thrown if this method is not implemented.

update
Updates the meta-data and content of this resource in the persistent store, but updates the content directly from the content from the specified file name.

Parameters: aFileName - a fully qualified path and file name, The default is in the current directory

Returns: A reference to this resource object

virtual dkDataObjectBase&  update(const char*  aFileName);

Note: DKUsageError exception is thrown if this method is not implemented.

del
Deletes this resource from the persistent store. The in-memory copy is not changed.

Returns:A reference to this resource object

virtual dkDataObjectBase&  del();

Note: DKUsageError exception is thrown if this method is not implemented.

del
Deletes this resource from the persistent store and apply the specified option.

Parameters: flush - if true the memory content will be flush, if false and content is not set, the object will be retrieved before delete it. The default is to flush.

Returns:A reference to this resource object

virtual dkDataObjectBase&  del(DKBoolean flush);

Note: DKUsageError exception is thrown if this method is not implemented.

getContentToClientFile
Copies the content of this resource object to the specified file.

Parameters: afileName - a fully qualified path with file name, default is current directory(if no path) fileOption -

  • DK_CM_XDO_FILE_OVERWRITE create or overwrite an existing file
  • DK_CM_XDO_FILE_NOOVERWRITE only create file, but throw an exception if the file already exists
  • DK_CM_XDO_FILE_APPEND appends to an existing file

Returns:A reference to this resource object

virtual dkDataObjectBase&  getContentToClientFile(const char* afileName, int fileOption) const =0;

Note: DKException exception is thrown if an error occurred.

setContentFromClientFile
Replaces the content of this resource in memory with the content obtained from the specified filename.

Parameters: afileName - a fully qualified path with file name, if no path, the default is in the current directory

Returns:A reference to this resource object

virtual dkDataObjectBase&  setContentFromClientFile(const char* afileName) =0;

Note: DKException exception is thrown if an error occurred.

getPidObject
Gets a copy of the persistent ID object of this object.

Returns: a copy of the persistent ID object of this object

virtual const DKPid* getPidObject();

setPidObject
Sets the PID information of this object with the new provided PID.

Parameters: aPid - a DKPid object

virtual void setPidObject(const DKPid* aPid);

operator=
Assignment operator. Assigns the content of a resource object to this resource object.

Parameters: aXDO - a resource object

Returns: A reference to this resource object

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

copyData
Replaces the content of this object with the content of another resource object.

Parameters: adkXDO - a resource object

Returns: A reference to this resource object

virtual dkDataObjectBase&   copyData(const dkXDO& adkXDO) = 0;

Note: DKUsageError exception is thrown if this method is not implemented.

compareData
Compares the content of this object with the content of another resource object.

Parameters: adkXDO - a resource object

Returns:TRUE if content of this object is equal. Otherwise FALSE.

virtual DKBoolean compareData(const dkXDO& adkXDO);

Note: DKUsageError exception is thrown if this method is not implemented.

isContentChanged
Checks if the content of this resource in-memory has changed.

Returns:TRUE if the content is changed; FALSE otherwise.

virtual DKBoolean  isContentChanged() const = 0;

isSet
Checks if the content of this resource is set.

Returns:TRUE if the content is set; FALSE otherwise.

virtual DKBoolean  isSet() const  = 0;

protocol
Returns the protocol supported by this object.

Returns:The protocol "DK_CM_RESOURCE"

short protocol() const;

length
Gets the length of this resource content in memory The subclass need to override the behaviour of the default implementation of this method.

Returns:Length of this resource content in memory

virtual long length() const;

Note: DKUsageError exception is thrown if this method is not implemented.

size
Gets the actual size of this resource content in the persistent store.

Returns:Length of this resource content in the persistent store

virtual long size();

Note: DKUsageError exception is thrown if this method is not implemented.

size
Gets the actual size of this resource content in the persistent store.

Returns:Length of this resource content in the persistent store

virtual long size();

Note: DKUsageError exception is thrown if this method is not implemented.

cloneSkeleton
Clone this resource with its persistent-identifier only, that is, with its data content set to empty.

Returns:The new resource

virtual dkXDO*  cloneSkeleton() = 0;

Note: DKUsageError exception is thrown if this method is not implemented.

getAffiliatedType
Gets the affiliated type of this object. An affiliated type could be ANNOTATION, NOTES, etc. The subclass need to override the behaviour of the default implementation of this method.

Returns:The affiliated type for this object, for example: DK_CM_ANNOTATION, DK_CM_NOTE, etc.

virtual unsigned long getAffiliatedType();

Note: DKUsageError exception is thrown if this method is not implemented.

setAffiliatedType
Sets the affiliated type for this object. The subclass need to override the behaviour of the default implementation of this method.

Parameters:affiliatedType - the affiliated type

virtual void setAffiliatedType(unsigned long affiliatedType);

Note: DKUsageError exception is thrown if this method is not implemented.

getMimeType
Gets the MIME type of this object. The subclass need to override the behaviour of the default implementation of this method.

Returns:The MIME type for this object

virtual DKString getMimeType();

setMimeType
Sets the MIME type for this object. The subclass need to override the behaviour of the default implementation of this method.

Parameters:mimeType - the MIME type

virtual void setMimeType(const char* mimeType);

Note: DKUsageError exception is thrown if this method is not implemented.

getContentType
Gets the content type of this object. A content type could be ASCII, JPG, AVI, GIF, HTML, etc The subclass need to override the behavior of the default implementation of this method.

Returns:The content type for this object. If not supported empty string is returned. This is the default.

virtual DKString getContentType();

setContentType
Sets the content type for this object. The subclass need to override the behaviour of the default implementation of this method.

Parameters:contentType - the content type

virtual void setContentType(const char* contentType);

Note: DKUsageError exception is thrown if this method is not implemented.

getContent
Gets the content of this object.

Returns:The object content

virtual DKString getContent() const = 0;

Note: DKException exception is thrown if a problem is encountered.

setContent
Sets the content of this object.

Parameters:astring - the object content

Returns:Return a reference to this resource object

virtual dkDataObjectBase& setContent(const DKString& astring) = 0;

Note: DKException exception is thrown if a problem is encountered.

getOption
Gets the option value of a specified option. The subclass need to override the behaviour of the default implementation of this method.

Parameters:option - a specified option value - object contains the option value

virtual void getOption (long option, DKAny& value);

Note: DKUsageError exception is thrown if this method is not implemented.

setOption
Sets the option value to a specified option. The subclass need to override the behaviour of the default implementation of this method.

Parameters:option - a specified option value - object contains the option value

virtual void getOption (long option, DKAny& value);

Note: DKUsageError exception is thrown if this method is not implemented.

getRank
Gets the ranking value of a query. If not supported rank is zero.

Returns:aRank - a ranking value

virtual long getRank();

setRank
Sets the ranking value of a query. If not supported rank is zero.

Parameters:aRank - a ranking value

virtual void setRank (long aRank);

addExtension
Add the extension to this resource object. The extension has an identifier and the corresponding object that implements the extension functions.

Parameters:extensionName - the extension name extensionObj - a source extension object

virtual void addExtension(const char* extensionName, dkExtension* extensionObj);

Note: DKUsageError exception is thrown if this method is not implemented.

removeExtension
Add the extension to this resource object. The extension has an identifier and the corresponding object that implements the extension functions.

Parameters:extensionName - the extension name

virtual void removeExtension(const char* extensionName);

Note: DKUsageError exception is thrown if this method is not implemented.

getExtension
Gets the extension object with the given name.

Parameters:extensionName - the extension name

Returns:a dkExtension object

virtual const dkExtension* getExtension(const char* extensionName);

Note: DKUsageError exception is thrown if this method is not implemented.

getClassName
Gets class name of this object.

Returns:A class name

virtual DKString getClassName();

setClassName
Sets class name of this object.

Parameters:className - the class name

virtual void setClassName(const char* className);

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