public class CSObject extends CSItem
The CSObject
class includes methods for the retrieval, update, and removal of a particular object. It
also provides a method that checks for the existence of a object. All such methods require that certain database and
key information (object ID, for example) be specified via the set
methods provided, prior to their
invocation.
It's possible to relate one or more CSObject
s to another CSObject
. Therefore, this
class also includes methods for the creation and removal of these object relationships. Again, these methods require
that certain database and key information be specified via the set
methods provided, prior to their
invocation.
All database access/connectivity is handled internally by the CSObject
class.
EXAMPLES
Retrieve a 'UserProfile' object, change the billing email address, and then save it :
try
{
CSObject obj = new CSObject("dbprops.dat");
obj.setDetailLevel(CSObject.LEVEL_ALL);
obj.setObjectID(1089);
obj.get();
obj.setItem("BILLTO.ELECTRONICINFO.EMAIL", "joe.bloggs@freeserve.co.uk");
obj.update();
}
catch ( CSException e )
{
System.err.println("ERROR : " + e.getMessage());
}
Remove all user profile objects :
try
{
CSObject obj = new CSObject("dbprops.dat");
obj.setType("UserProfile");
obj.delete();
}
catch ( CSException e )
{
System.err.println("ERROR : " + e.getMessage());
}
Specify the related objects for a particular object :
try
{
CSObject obj = new CSObject("dbprops.dat");
obj.setObjectID(1089);
obj.setRelatedList(1088+","+1067);
obj.setRelatedDirection(CSObject.DIRECTION_DESTINATION);
obj.update();
}
catch ( CSException e )
{
System.err.println("ERROR : " + e.getMessage());
}
Remove all relationships for a particular object :
try
{
CSObject obj = new CSObject("dbprops.dat");
obj.setObjectID(1089);
obj.setRelatedDirection(CSObject.DIRECTION_BOTH);
obj.delete();
}
catch ( CSException e )
{
System.err.println("ERROR : " + e.getMessage());
}
CSObjectContent
,
CSState
,
CSObjectMultiple
,
CSObjectDefinition
,
Serialized FormModifier and Type | Field and Description |
---|---|
static java.lang.String |
DIRECTION_BOTH
A valid value for the
setRelatedDirection method. |
static java.lang.String |
DIRECTION_DESTINATION
A valid value for the
setRelatedDirection method. |
static java.lang.String |
DIRECTION_SOURCE
A valid value for the
setRelatedDirection method. |
ACCESS_GRANTED, DOES_NOT_EXIST, EMPTY, EXISTS, SECURE_ACCESS_DENIED, SECURE_ACCESS_GRANTED, UPDATE_ACTION_INSERTED, UPDATE_ACTION_UPDATED
LEVEL_ALL, LEVEL_ALL_PLUS_RELATED, LEVEL_DETAIL, LEVEL_ID, LEVEL_SUMMARY
Constructor and Description |
---|
CSObject()
Creates an empty
CSObject object. |
CSObject(java.lang.String strPropertyFile)
Creates an empty
CSObject object, specifying a property file that contains all of the database
connection details. |
Modifier and Type | Method and Description |
---|---|
void |
delete()
Removes an iCM object from the database.
|
boolean |
exist()
Checks to see whether a iCM object exists on the database.
|
boolean |
existsItem(java.lang.String strObject)
States if a particular element (property) is present in the object's data structure (see
getObjectData ). |
java.lang.String |
generateXMLDocAsString()
Returns a string containing a representation of the object's data as a complete XML document.
|
java.lang.String |
generateXMLFragment()
Returns a string containing a representation of the object's data as an XML fragment.
|
void |
get()
Retrieves the details of a iCM object from the database.
|
boolean |
getCheckTypeExistsOnCreate()
Indicates whether or not we will enforce the check that the type must
exist before an object can be created
This property is false by default.
|
java.lang.String |
getCreatedBy()
Gets the name of the person who created this object.
|
java.util.Date |
getDateCreated()
Gets the Date upon which this object was created.
|
java.util.Date |
getDateLastUpdated()
Gets the Date upon which this object was last updated.
|
static java.util.Map<java.lang.String,java.lang.String> |
getDefaultHandlebarsHelpers()
Gets the static default handlebars helpers that can be used when formatting object data.
|
static java.lang.String |
getDefaultUserProfileType()
Gets the static default object type that is used to store user profile information.
|
java.lang.String |
getHandlebarsResult() |
java.lang.String |
getHandlebarsResult(Context.Builder hbCntxBuilder)
Uses Handlebars to create and return a String rendered from the supplied template using the ObjectData as the context.
|
java.util.Hashtable<java.lang.String,?> |
getHbContextData()
returns the Object that is added to the handlebars context as the
data member. |
Template |
getHbTemplate()
gets the template used by
getHandlebarsResult() |
java.lang.Object |
getItem(java.lang.String strObject)
Retrieves a stated element (property) from the object's data structure
getObjectData . |
java.lang.String |
getLabel()
Gets the textual identifier of this object.
|
java.lang.String |
getLastUpdatedBy()
Gets the name of the person who last updated this object.
|
java.lang.Object |
getObjectData()
Gets the object's data.
|
int |
getObjectID()
Gets the numeric identifier of this
CSObject instance. |
java.lang.String |
getRelatedDirection()
Gets the direction of the relationship between this
CSObject and the supplied related object(s) (setRelatedID ,
setRelatedList ). |
int |
getRelatedID()
Gets the related object ID currently specified as key information.
|
java.lang.String |
getRelatedList()
Gets the list of related object IDs currently specified as key information.
|
java.lang.String |
getType()
Gets the object type.
|
boolean |
getUpdateData()
Indicates whether or not any properties that exist in the type definition
should be added to any existing object data when the object data is
retrieved.
|
java.lang.String |
getUpdatedLabel()
Gets the updated object label, if any.
|
boolean |
getUpdateIndex()
Deprecated.
Use
CSDatabaseItem.getSendGatewayMessages() instead. |
java.lang.String |
getUserProfileType()
Gets the object type that is used to store user profile information.
|
void |
readXMLDocument(java.lang.String documentString,
boolean ignoreID) |
void |
readXMLFragment(java.lang.String xmlString,
boolean forceIgnoreId) |
void |
setCheckTypeExistsOnCreate(boolean value)
Indicates whether or not we will enforce the check that the type must
exist before an object can be created
This property is false by default.
|
void |
setCreatedBy(java.lang.String strCreatedBy)
Sets the name of the user who created this object.
|
void |
setDateCreated(java.util.Date dDateCreated)
Sets the Date upon which the object was first created.
|
void |
setDateLastUpdated(java.util.Date dDateLastUpdated)
Sets the Date upon which the object was last updated.
|
static void |
setDefaultHandlebarsHelpers(java.util.Map<java.lang.String,java.lang.String> defaultHandlebarsHelpers)
Staticaly sets the default handlebars helper script that is used by all instances of handlebars.
|
static void |
setDefaultUserProfileType(java.lang.String defaultUserProfileType)
Statically sets the default object type that is used to store user profile information.
|
void |
setDetailLevel(int nDetailLevel)
Sets the level of detail to be handled by the
get method. |
void |
setHbContextData(java.util.Hashtable<java.lang.String,?> hbContextData)
sets the Object that is added to the handlebars context as the
data member.. |
void |
setHbTemplate(java.lang.String hbTemplate)
set the template to be used by
getHandlebarsResult() |
void |
setItem(java.lang.String strObject,
java.lang.Object objData)
Sets a stated element in the object's data structure
getObjectData . |
void |
setItem(java.lang.String strObject,
java.lang.Object objData,
java.lang.Boolean mustExistInObjectTypeDefinition)
Sets a stated element in the object's data structure
getObjectData . |
void |
setLabel(java.lang.String strLabel)
Sets the label to be used as key information.
|
void |
setLastUpdatedBy(java.lang.String strLastUpdatedBy)
Sets the name of the user who last updated this object.
|
void |
setObjectData(java.lang.Object objObjectData)
Sets the object's data to that provided.
|
void |
setObjectID(int nObjectID)
Sets the object ID to be used as key information.
|
void |
setRelatedDirection(java.lang.String strRelatedDirection)
Sets the direction of the relationship between this
CSObject and the supplied related object(s) (setRelatedID ,
setRelatedList ). |
void |
setRelatedID(int nRelatedID)
Sets the related object ID to be used as key information when handling object relationships.
|
void |
setRelatedList(java.lang.String strRelatedList)
Sets the list of related object IDs to be used as key information when handling object relationships.
|
void |
setType(java.lang.String strType)
Sets the object type to be used as key information.
|
void |
setUpdateData(boolean value)
Indicates whether or not any properties that exist in the type definition
should be added to any existing object data when the object data is
retrieved.
|
void |
setUpdatedLabel(java.lang.String strLabel)
Specifies an updated object label.
|
void |
setUpdateIndex(boolean value)
Deprecated.
Use
CSDatabaseItem.setSendGatewayMessages(boolean) instead. |
void |
setUserProfileType(java.lang.String strType)
Sets the object type that is used to store user profile information.
|
java.lang.String |
toString()
Outputs the contents of this
CSObject object to a String object in a
user-friendly format. |
void |
update()
Updates an iCM object on the database.
|
equals, getID, getStatus, hashCode, jsonString, serialiseWithTypes, setID, setStatus, unset
clearRecordedGatewayMessages, clone, count, getCache, getCachingEnabled, getDatabaseVersion, getDatabaseVersion, getDebugOutput, getDetailLevel, getPreview, getPropertyFile, getPropertyFileExtension, getPropertyFilePathname, getRecordedGatewayMessages, getRecordGatewayMessages, getSendGatewayMessages, getUseCache, setDebugOutput, setPreview, setPropertyFile, setRecordGatewayMessages, setSendGatewayMessages, setUseCache
public static final java.lang.String DIRECTION_BOTH
setRelatedDirection
method.
DIRECTION_BOTH
indicates all relationships between this CSObject
and those supplied
via the setRelatedID
or setRelatedList
method.public static final java.lang.String DIRECTION_SOURCE
setRelatedDirection
method.
DIRECTION_SOURCE
indicates that this CSObject
is a related object of the object(s)
supplied via the setRelatedID
or setRelatedList
method.public static final java.lang.String DIRECTION_DESTINATION
setRelatedDirection
method.
DIRECTION_DESTINATION
indicates that object(s) supplied via the
setRelatedID
or setRelatedList
method are related
objects of this CSObject
.public CSObject()
CSObject
object.
Use the various set methods provided to initialise the CSObject
object prior to invoking any of
its query methods.
public CSObject(java.lang.String strPropertyFile)
CSObject
object, specifying a property file that contains all of the database
connection details.
Use the various set methods provided to initialise the CSObject
object prior to invoking any of
its query methods.
strPropertyFile
- the name of the property file from which the database connection details are to be readpublic static java.lang.String getDefaultUserProfileType()
The type is used to identify insert/update/delete of UserProfile objects so that the site user search index is kept up to date.
The user profile object type may be accessed and overridden at an instance level via
setUserProfileType(String)
, and retrieved via getUserProfileType()
.
public static void setDefaultUserProfileType(java.lang.String defaultUserProfileType)
The type is used to identify insert/update/delete of UserProfile objects so that the site user search index is kept up to date.
The user profile object type may be accessed and overridden at an instance level via
setUserProfileType(String)
, and retrieved via getUserProfileType()
.
defaultUserProfileType
- The default user profile object typepublic static java.util.Map<java.lang.String,java.lang.String> getDefaultHandlebarsHelpers()
public static void setDefaultHandlebarsHelpers(java.util.Map<java.lang.String,java.lang.String> defaultHandlebarsHelpers)
defaultHandlebarsHelpers
- A map containing a name and the javascript code for
the helpers typically this is the swag.js librarypublic boolean existsItem(java.lang.String strObject)
getObjectData
). This CSObject
must have been populated via the
get
method before existsItem
can be used.
strObject
- The name of the element to be searched for within the object's data structure. For example, the name
for the EMAIL
property that resides within the ELECTRONIC
property which
in turn resides within the BILLTO
property of a UserProfile
object would
be BILLTO.ELECTRONIC.EMAIL
.true
if the item exists, false
otherwisepublic java.lang.Object getItem(java.lang.String strObject) throws CSParameterException
getObjectData
.
strObject
- The name of the element to be retrieved from the object's data structure (e.g.
billto.electronic.email
)CSParameterException
- if an invalid object was specified.public void setItem(java.lang.String strObject, java.lang.Object objData) throws CSParameterException
getObjectData
.
strObject
- The name of the element to be set in the object's data structure (e.g.
billto.electronic.email
)objData
- The data to be assigned to the specified elementCSParameterException
- if invalid object data was specified.public void setItem(java.lang.String strObject, java.lang.Object objData, java.lang.Boolean mustExistInObjectTypeDefinition) throws CSParameterException
getObjectData
.
strObject
- The name of the element to be set in the object's data structure (e.g.
billto.electronic.email
)objData
- The data to be assigned to the specified elementmustExistInObjectTypeDefinition
- A boolean that indicates if the name of the element must be present in the objects type definition. If it's not present then the data won't be setCSParameterException
- if invalid object data was specified.public void setRelatedDirection(java.lang.String strRelatedDirection)
CSObject
and the supplied related object(s) (setRelatedID
,
setRelatedList
).
Valid values are :
BOTH
- the supplied object(s) are either related objects of this CSObject
or
have this CSObject
as a related object
SOURCE
- the supplied object(s) are related objects of this CSObject
DESTINATION
- this CSObject
is a related object of the supplied object(s)
strRelatedDirection
- The direction of the relationshippublic boolean getUpdateIndex()
CSDatabaseItem.getSendGatewayMessages()
instead.public void setUpdateData(boolean value)
value
- true if any missing properties in the object data that exist in the type
definition should be added automaticallypublic boolean getUpdateData()
public void setCheckTypeExistsOnCreate(boolean value)
value
- true if the check is to be enforcedpublic boolean getCheckTypeExistsOnCreate()
public void setUpdateIndex(boolean value)
CSDatabaseItem.setSendGatewayMessages(boolean)
instead.value
- true if the search index should be updated following update of
the object, false otherwisepublic java.lang.String getRelatedDirection()
CSObject
and the supplied related object(s) (setRelatedID
,
setRelatedList
).
Valid values are :
BOTH
- the supplied object(s) are either related objects of this CSObject
or
have this CSObject
as a related object
SOURCE
- the supplied object(s) are related objects of this CSObject
DESTINATION
- this CSObject
is a related object of the supplied object(s)
public void setRelatedList(java.lang.String strRelatedList)
CSObject
is indicated by the supplied
related type (setRelatedDirection
).
strRelatedList
- A comma-separated list of object IDspublic java.lang.String getRelatedList()
public void setRelatedID(int nRelatedID)
CSObject
is indicated by the supplied related
type (setRelatedDirection
).
nRelatedID
- The related object ID.public int getRelatedID()
public void setObjectID(int nObjectID)
setObjectID
followed by a call to get
will return details of the object with the
specified object ID.
nObjectID
- The numeric identifier of this objectpublic int getObjectID()
CSObject
instance.
public void setLabel(java.lang.String strLabel)
The label is used to identify the object when combined with setType
. Each Type and
Label pair are a unique combination.
strLabel
- The desired String
to be used to identify this objectpublic java.lang.String getLabel()
Can only be used as a unique identifier when combined with getType
. Each Type and Label pair
are a unique combination.
public void setUpdatedLabel(java.lang.String strLabel)
This property allows the label of an existing object to be updated and will only take effect when updating an existing object.
As this is a separate property from Label, it is possible to update the label of an object identified by label.
strLabel
- The updated desired String
to be used to identify this objectpublic java.lang.String getUpdatedLabel()
This property allows the label of an existing object to be updated and will only take effect when updating an existing object. It will not be populated when an object is retrieved from the database.
public void setType(java.lang.String strType)
The type is used to identify the object when combined with setLabel
. Each Type and
Label pair are a unique combination. The Type string must identify a valid CSObjectDefinition
object e.g.
UserProfile
.
strType
- The object typepublic java.lang.String getType()
Can only be used as a unique identifier when combined with getLabel
. Each Type and Label
pair are a unique combination. The Type returned identifies a CSObjectDefinition
object that describes
the contents of this object's data.
public void setUserProfileType(java.lang.String strType)
The type is used to identify insert/update/delete of UserProfile objects so that the site user search index is kept up to date.
strType
- The object typepublic java.lang.String getUserProfileType()
The type is used to identify insert/update/delete of UserProfile objects so that the site user search index is kept up to date.
public Template getHbTemplate() throws java.io.UnsupportedEncodingException, CSException
getHandlebarsResult()
java.io.UnsupportedEncodingException
CSException
public void setHbTemplate(java.lang.String hbTemplate)
getHandlebarsResult()
hbTemplate
- a Handlebars templatepublic java.util.Hashtable<java.lang.String,?> getHbContextData()
data
member.data
Objectpublic void setHbContextData(java.util.Hashtable<java.lang.String,?> hbContextData)
data
member..hbContextData
- the data
Objectpublic java.lang.String getHandlebarsResult() throws CSException, java.io.UnsupportedEncodingException
CSException
java.io.UnsupportedEncodingException
public java.lang.String getHandlebarsResult(Context.Builder hbCntxBuilder) throws CSException, java.io.UnsupportedEncodingException
CSException
- if there is an error compiling or rendering the templatejava.io.UnsupportedEncodingException
public void setCreatedBy(java.lang.String strCreatedBy)
strCreatedBy
- The name of the userpublic java.lang.String getCreatedBy()
getCreatedBy
.
public void setLastUpdatedBy(java.lang.String strLastUpdatedBy)
strLastUpdatedBy
- The name of the userpublic java.lang.String getLastUpdatedBy()
getLastUpdatedBy
.
public void setDateCreated(java.util.Date dDateCreated)
update
method when creating a fresh object and will be set to the current server's time.
dDateCreated
- The date this object was createdpublic java.util.Date getDateCreated()
public void setDateLastUpdated(java.util.Date dDateLastUpdated)
This is normally set automatically by the update
method when updating an existing object and
will be set to the current server's time.
dDateLastUpdated
- The date upon which this object was last updatedpublic java.util.Date getDateLastUpdated()
public void setObjectData(java.lang.Object objObjectData) throws CSException
The object data supplied should comply with the structure determined by this object's Type (getType
)
and described by the corresponding CSObjectDefinition
. The preferred way of accessing the object data is
via the getItem
and setItem
methods.
objObjectData
- A Hashtable
cast to Object
containing valid data for this type of
object.CSException
- CSExceptionpublic java.lang.Object getObjectData()
The object data returned complies with the structure determined by this object's Type (getType
)
and described by the corresponding CSObjectDefinition
. The preferred way of accessing the object data is
via the getItem
and setItem
methods.
Hashtable
cast to an object
.public void setDetailLevel(int nDetailLevel) throws CSParameterException
get
method.
Valid detail levels for an object are :
LEVEL_ID - the object ID
LEVEL_SUMMARY - the object type and label
LEVEL_DETAIL - the object's date and time created/last updated, and the name of the person that create/last updated it
LEVEL_ALL - the object's data
Each detail level processes the information specified alongside it in addition to the information specified for all detail levels listed above it. The default detail level is LEVEL_ALL.
setDetailLevel
in class CSDatabaseItem
nDetailLevel
- The detail level to be usedCSParameterException
- if an invalid detail level is specified.public boolean exist() throws CSException
Use setObjectID
followed by exist
to determine whether an object with
the specified ID exists on the database.
Use setLabel
and setType
followed by exist
to
determine whether an object identified by a particular label/type combination exists on the database.
If setRelatedID
is used in addition to one of the above, the exist
method will determine whether there is a relationship between this CSObject
and the one supplied.
The direction of the relationship needs to be specified via the
setRelatedDirection
method.
exist
in class CSItem
true
if the object/relationship exists on the databaseCSParameterException
- if an invalid combination of key information has been suppliedCSDatabaseException
- if there are problems accessing the databaseCSException
- the base class for exceptions thrown by this method.public void get() throws CSException
Use setObjectID
followed by get
to populate this CSObject
object with the details of the iCM object identified by the specified ID.
Use setLabel
and setType
followed by get
to
retrieve the object identified by a particular label/type combination from the database.
Use setType
followed by get
to retrieve an empty object of the specified
type. For example, a type of UserProfile
would retrieve an empty user profile data structure.
get
in class CSItem
CSParameterException
- if an invalid combination of key information has been suppliedCSDatabaseException
- if there are problems accessing the databaseCSNotFoundException
- if the specified object cannot be found on the databaseCSSecurityException
- if security has been breachedCSException
- the base class for exceptions thrown by this method.public void update() throws CSException
Use update
to store the current contents of this CSObject
on the database. If an
object with the current ID or Type/Label already exists, that object's details will be updated. Otherwise, a new
object will be created on the database.
If setRelatedID
or setRelatedList
is used in addition
to setObjectID
OR setType
and
setLabel
, the update
method will create a relationship between this
CSObject
and the one(s) supplied. The direction of the relationship needs to be specified via the
setRelatedDirection
method.
update
in class CSItem
CSParameterException
- if an invalid combination of key information has been suppliedCSDatabaseException
- if there are problems accessing the databaseCSNotFoundException
- if the specified object cannot be found on the databaseCSException
- the base class for exceptions thrown by this method.public void delete() throws CSException
Use setObjectID
followed by delete
to remove the iCM object with the
specified ID from the database.
Use setLabel
and setType
followed by delete
to
remove the object identified by that Label/Type combination.
Use setType
followed by delete
to remove all objects of the specified
type e.g. all user profile objects.
If setRelatedID
or setRelatedList
is used in addition
to one of the above, the delete
method will remove the relationships between this
CSObject
and the one(s) supplied. The direction of the relationship needs to be specified via the
setRelatedDirection
method. If no related object ID(s) are supplied, all
relationships for this CSObject
of the specified type will be deleted.
delete
in class CSItem
CSParameterException
- if an invalid combination of key information has been suppliedCSDatabaseException
- if there are problems accessing the databaseCSNotFoundException
- if the specified object cannot be found on the databaseCSException
- the base class for exceptions thrown by this method.public java.lang.String generateXMLFragment() throws CSException
CSException
- CSExceptionpublic java.lang.String generateXMLDocAsString() throws CSException
CSException
- CSExceptionpublic void readXMLFragment(java.lang.String xmlString, boolean forceIgnoreId) throws CSException
CSException
public void readXMLDocument(java.lang.String documentString, boolean ignoreID) throws CSException
CSException
Copyright © 2022 Goss Interactive Ltd. All Rights Reserved.