Enterprise Information Portal APIs

com.ibm.mm.sdk.common
Class DKDDO

java.lang.Object
  |
  +--com.ibm.mm.sdk.common.dkAbstractDataObjectBase
        |
        +--com.ibm.mm.sdk.common.dkDataObject
              |
              +--com.ibm.mm.sdk.common.DKDDOBase
                    |
                    +--com.ibm.mm.sdk.common.DKDDO
All Implemented Interfaces:
DKConstant, dkDataObjectBase, DKMessageId, java.io.Serializable
Direct Known Subclasses:
dkResource

public class DKDDO
extends DKDDOBase
implements DKConstant, java.io.Serializable

DKDDO is the class to represents a Dynamic Data Object (DDO). It is a sub-class of DKDDOBase with additional methods to support persistency, such as add(), retrieve(), update(), and del(). Its purpose is for representing data-objects and to transfer tehm to and from the persistent store. See DKDDOBase for more information.

See Also:
Serialized Form

Fields inherited from interface com.ibm.mm.sdk.common.DKConstant
    For details, see the class or interface
 
Fields inherited from interface com.ibm.mm.sdk.common.DKMessageId
    For details, see the class or interface
 
Constructor Summary
DKDDO()
          Constructs a DDO object.
DKDDO(dkDatastore ds, DKPid pid)
          Constructs a DDO object with a given PID and the datastore associated with it.
DKDDO(dkDatastore ds, DKPid pid, short initialSize)
          Constructs a DDO object with a given PID, the datastore associated with it, and an initial number of data-items.
DKDDO(dkDatastore ds, java.lang.String objectType)
          Constructs a DDO object for a given object type in the specified datastore.
DKDDO(dkDatastore ds, java.lang.String objectType, short initialSize)
          Constructs a DDO object for a given object type, with an initial number of data-items and the datastore associated with it.
DKDDO(DKDDO ddo)
          Constructs a DDO object by copying another DDO object (copy constructor).
DKDDO(DKPid pid)
          Constructs a DDO object with a given PID.
DKDDO(DKPid pid, short initialSize)
          Constructs a DDO object with a given PID and an initial number of data-items.
DKDDO(short initialSize)
          Constructs a DDO object which has enough space for the given initial number of data-items.
DKDDO(java.lang.String objectType)
          Constructs a DDO object for a given object type.
DKDDO(java.lang.String objectType, short initialSize)
          Constructs a DDO object for a given object type, with an initial number of data-items.
 
Method Summary
 void add()
          Adds this data-object to the persistent store.
 void add(DKNVPair[] options)
          Adds this data-object to the persistent store with options.
 void add(int option)
          Adds this data-object to the persistent store with option.
 void del()
          Deletes this object from the persistent store.
 void del(DKNVPair[] options)
          Deletes this object from the persistent store with options.
 void del(int option)
          Deletes this object from the persistent store with option.
static dkDataObjectBase fromXML(DKNVPair xmlSource)
          Creates a new DKDDO object using the given XML input source.
static dkDataObjectBase fromXML(DKNVPair xmlSource, int options)
          Creates a new DKDDO object using the given XML input source.
 dkDatastore getDatastore()
          Gets the associated datastore for this DDO.
 short protocol()
          Returns the protocol type supported by this data-object.
 void retrieve()
          Retrieve this data-object from the persistent store.
 void retrieve(DKNVPair[] options)
          Retrieve this data-object from the persistent store with options.
 void retrieve(int option)
          Retrieve this data-object from the persistent store with option.
 void setDatastore(dkDatastore ds)
          Sets this datastore as the one associated with this DDO; that is, the datastore to keep the persistent copy of this DDO.
 void toXML(DKNVPair xmlDestination, java.lang.String path, int options)
          Generates the corresponding XML from this DKDDO.
 void update()
          Updates this object in the persistent store.
 void update(DKNVPair[] options)
          Updates this object in the persistent store with options.
 void update(int option)
          Updates this object in the persistent store with option.
 
Methods inherited from class com.ibm.mm.sdk.common.DKDDOBase
addData, addData, addData, addDataProperty, addDataProperty, addDataProperty, addProperty, addProperty, addProperty, dataCount, dataId, dataId, dataIdsByNameSpace, dataNameSpaceCount, dataPropertyCount, dataPropertyId, getData, getDataByName, getDataByName, getDataName, getDataNameSpace, getDataProperty, getDataPropertyByName, getDataPropertyByName, getDataPropertyByName, getDataPropertyName, getObjectType, getProperty, getPropertyByName, getPropertyName, isDataPropertySet, isDataSet, isNull, isPropertySet, propertyCount, propertyId, setData, setDataName, setDataName, setDataNameSpace, setDataProperty, setDataPropertyName, setNull, setObjectType, setProperty, setPropertyName, updatable
 
Methods inherited from class com.ibm.mm.sdk.common.dkDataObject
getPid, getPidObject, setPid, setPidObject
 
Methods inherited from class com.ibm.mm.sdk.common.dkAbstractDataObjectBase
getParent, getRootObject, setParent, setRootObject
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DKDDO

public DKDDO()
Constructs a DDO object.

DKDDO

public DKDDO(short initialSize)
Constructs a DDO object which has enough space for the given initial number of data-items.
Parameters:
initialSize - the initial number of data-items.

DKDDO

public DKDDO(DKDDO ddo)
Constructs a DDO object by copying another DDO object (copy constructor).
Parameters:
ddo - the other existing DDO object.

DKDDO

public DKDDO(java.lang.String objectType)
Constructs a DDO object for a given object type.
Parameters:
objectType - an object-type. The object type which usually corresponds to an entity name.

DKDDO

public DKDDO(java.lang.String objectType,
             short initialSize)
Constructs a DDO object for a given object type, with an initial number of data-items.
Parameters:
objectType - an object-type.
initialSize - the initial number of data items.

DKDDO

public DKDDO(dkDatastore ds,
             java.lang.String objectType)
Constructs a DDO object for a given object type in the specified datastore. The object type usually corresponds to an entity name defined in the datastore.
Parameters:
ds - a datastore object.
objectType - an object-type.

DKDDO

public DKDDO(dkDatastore ds,
             java.lang.String objectType,
             short initialSize)
Constructs a DDO object for a given object type, with an initial number of data-items and the datastore associated with it.
Parameters:
ds - a datastore object.
objectType - an object-type.
initialSize - the initial number of data-items.

DKDDO

public DKDDO(DKPid pid)
Constructs a DDO object with a given PID.
Parameters:
pid - a PID object.

DKDDO

public DKDDO(DKPid pid,
             short initialSize)
Constructs a DDO object with a given PID and an initial number of data-items.
Parameters:
pid - a PID object.
initialSize - the initial number of data-items.

DKDDO

public DKDDO(dkDatastore ds,
             DKPid pid)
Constructs a DDO object with a given PID and the datastore associated with it.
Parameters:
ds - a datastore object.
pid - a PID object.

DKDDO

public DKDDO(dkDatastore ds,
             DKPid pid,
             short initialSize)
Constructs a DDO object with a given PID, the datastore associated with it, and an initial number of data-items.
Parameters:
ds - a datastore object.
pid - a PID object.
initialSize - the initial number of data-items.
Method Detail

fromXML

public static dkDataObjectBase fromXML(DKNVPair xmlSource,
                                       int options)
                                throws DKException,
                                       java.lang.Exception
Creates a new DKDDO object using the given XML input source.
Parameters:
xmlSource - a DKNVPair object specifyng the XML source characteristics, with the following possible values:
  • ("BUFFER",) : buffer_ref (String) containing an XML contents in memory
  • ("FILE", ) : file_name (String) is the name of the file to contain the output XML. File name must contain the full path.
  • ("URL", ): url_address (String) containing the URL of an XML file
  • ("STDIN", null) : the contents of an XML file, from standard input (STDIN)
options - options for XML processing
  • DK_CM_XML_VALIDATION : The XML parser perform validation. Default is no validation. Optional
Returns:
new DDO object
Throws:
DKException - if a problem is encountered.

fromXML

public static dkDataObjectBase fromXML(DKNVPair xmlSource)
                                throws DKException,
                                       java.lang.Exception
Creates a new DKDDO object using the given XML input source.
Parameters:
xmlSource - a DKNVPair object specifyng the XML source characteristics, with the following possible values:
  • ("BUFFER",) : buffer_ref (String) containing an XML contents in memory
  • ("FILE", ) : file_name (String) is the name of the file to contain the output XML. File name must contain the full path.
  • ("URL", ): url_address (String) containing the URL of an XML file
  • ("STDIN", null) : the contents of an XML file, from standard input (STDIN)
Returns:
new DDO object
Throws:
DKException - if a problem is encountered.

toXML

public void toXML(DKNVPair xmlDestination,
                  java.lang.String path,
                  int options)
           throws DKException,
                  java.lang.Exception
Generates the corresponding XML from this DKDDO. If the DDO is a nested object, it assumes that the DDO has been instantiated/retrieved upto the desired level of depth.
Parameters:
xmlDestination - specifies where the XML output should go, valid values are:
  • ("BUFFER", ) : buffer_ref (String) is a reference to a buffer in memory to contain the output XML
  • ("FILE", ) : file_name (String) is the name of the file to contain the output XML. File name must contain the full path.
  • ("URL", ): url_address (String) is the URL-address location for the output XML
  • ("STDOUT", null) : the output XML is directed to the standard output (STDOUT)
path - indicates the file directory of the ddo.dtd
options - options for XML processing
  • DK_CM_XDO_EMBED : to embed the xdo value in the generated XML, either in plain text form (#PCDATA) or in Base64 encoding.
  • DK_CM_XDO_REFERENCE : to represent any blob with a reference to a file or URL where the file or URL will be created by writing the xdo content out to it. Both options above are mutually exclusive.
Throws:
DKException - if a problem is encountered.

setDatastore

public void setDatastore(dkDatastore ds)
Sets this datastore as the one associated with this DDO; that is, the datastore to keep the persistent copy of this DDO.
Parameters:
ds - a datastore object.

getDatastore

public dkDatastore getDatastore()
Gets the associated datastore for this DDO.
Returns:
the datastore object.

protocol

public short protocol()
Returns the protocol type supported by this data-object. In this case, it is DK_CM_PDDO, which essentially means that this object knows the datastore which it is associated with. With the help of the datastore, this object can transfer itself in and out of the datastore, thus making itself persistent.
Overrides:
protocol in class DKDDOBase
Returns:
the protocol

add

public void add()
         throws DKException,
                java.lang.Exception
Adds this data-object to the persistent store. An initial persistent copy of this data-object is created, according to the corresponding entity structure defined in the datastore. Only persistent data-items (or attributes) are saved.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

add

public void add(int option)
         throws DKException,
                java.lang.Exception
Adds this data-object to the persistent store with option. An initial persistent copy of this data-object is created, according to the corresponding entity structure defined in the datastore. Only persistent data-items (or attributes) are saved.
Parameters:
option - option for add. It is a combination of flag settings to pass additional information, such as checkout after creation. See valid option values under the specific datastore class documentation.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

add

public void add(DKNVPair[] options)
         throws DKException,
                java.lang.Exception
Adds this data-object to the persistent store with options. An initial persistent copy of this data-object is created, according to the corresponding entity structure defined in the datastore. Only persistent data-items (or attributes) are saved.
Parameters:
options - options for add. Currently this option is not enabled.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

retrieve

public void retrieve()
              throws DKException,
                     java.lang.Exception
Retrieve this data-object from the persistent store. The in-memory values of this data-object is replaced with the persistent copy retrieved from the datastore. Only persistent data-items (or attributes) are retrieved.
Throws:
DKException - if a problem is encountered.

retrieve

public void retrieve(int option)
              throws DKException,
                     java.lang.Exception
Retrieve this data-object from the persistent store with option. The in-memory values of this data-object is replaced with the persistent copy retrieved from the datastore. Only persistent data-items (or attributes) are retrieved.
Parameters:
option - option for retrieve. It is a combination of flag settings to tailor the granularity of the retrieval. See valid option values under the specific datastore class documentation.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

retrieve

public void retrieve(DKNVPair[] options)
              throws DKException,
                     java.lang.Exception
Retrieve this data-object from the persistent store with options. The in-memory values of this data-object is replaced with the persistent copy retrieved from the datastore. Only persistent data-items (or attributes) are retrieved.
Parameters:
options - options for retrieve. The option is in the form of name-value pairs, to allow a more flexible way of passing information such as projection list and version number. See vaild option values under the specific datastore class documentation.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

update

public void update()
            throws DKException,
                   java.lang.Exception
Updates this object in the persistent store. The persistent copy of this data-object is updated with the current values in-memory. Only persistent data-items (or attributes) are updated.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

update

public void update(int option)
            throws DKException,
                   java.lang.Exception
Updates this object in the persistent store with option. The persistent copy of this data-object is updated with the current values in-memory. Only persistent data-items (or attributes) are updated.
Parameters:
option - option for update. It is a combination of flag settings to pass additional information, such as creating a new version instead of update in place. See valid option values under the specific datastore class documentation.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

update

public void update(DKNVPair[] options)
            throws DKException,
                   java.lang.Exception
Updates this object in the persistent store with options. The persistent copy of this data-object is updated with the current values in-memory. Only persistent data-items (or attributes) are updated.
Parameters:
options - options for update. The option is in the form of name-value pairs, to allow a more flexible way of passing information such as version number to update. See valid option values under the specific datastore class documentation.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

del

public void del()
         throws DKException,
                java.lang.Exception
Deletes this object from the persistent store. The persistent copy of this data-object is deleted from the datastore. The in-memory copy of this object is not affected. After this method is executed, a subsequent call to retrieve(), update(), or del(), will cause an exception because the persistent copy of this data-object no longer exists.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

del

public void del(int option)
         throws DKException,
                java.lang.Exception
Deletes this object from the persistent store with option. The persistent copy of this data-object is deleted from the datastore. The in-memory copy of this object is not affected. After this method is executed, a subsequent call to retrieve(), update(), or del(), will cause an exception because the persistent copy of this data-object no longer exists.
Parameters:
option - option for delete. It is a combination of flag settings to pass additional information, such as delete the latest version. See valid option values under the specific datastore class documentation.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

del

public void del(DKNVPair[] options)
         throws DKException,
                java.lang.Exception
Deletes this object from the persistent store with options. The persistent copy of this data-object is deleted from the datastore. The in-memory copy of this object is not affected. After this method is executed, a subsequent call to retrieve(), update(), or del(), will cause an exception because the persistent copy of this data-object no longer exists.
Parameters:
options - options for delete. The option is in the form of name-value pairs, to allow a more flexible way of passing information, such as version number to delete. See valid option values under the specific datastore class documentation.

Note:DKUsageError exception thrown if method is not implemented

Throws:
DKException - if a problem is encountered.

EIP Java APIs

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