public abstract class CSDatabaseItem
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable
This class is used to load drivers and initialise access to a database. If database connection pooling is requested,
'brokers' will be used to reuse one or more configurable pools of pre-established connections. A different broker,
and hence a different connection pool, will be used for each database driver/datasource/username/password
combination. Each broker is responsible for handing out and returning database connections from its pool of
connections. Connection pooling is recommended for efficiency as it avoids the overhead required in establishing new
database connections (typically around 1 to 2 seconds). All CSDatabaseItem
derived classes will
implement connection pooling if the DBConnectionPooling
property is set to true
/yes
within the database property file.
Any one property file will be read the once only and then stored in memory and re-used by all
CSDatabaseItem
derived classes specifying the same property file. Each property file should contain
the following information :
DBDriver
- the name of the database driver class to be used e.g.
allaire.jrun.jdbc.JRunDriver
. This property must be supplied.
DBDatasource
- the database connection string e.g.
jdbc:jrun:sqlserver://10.10.10.36:1433;databaseName=demo
. This property must be supplied.
DBUsername
- the database login name. This property must be supplied.
DBPassword
- the database password. This property must be supplied.
DBMinCons
- if connection pooling is on, the minimum number of database connections required in
the connection pool. 1
is used if this property is not supplied.
DBMaxCons
- if connection pooling is on, the maximum number of database connections required in
the connection pool. 3
is used if this property is not supplied.
DBLogFile
- if connection pooling is on, the name/location of the log file. The current working
directory is assumed if no path is specified. LOG.TXT
is assumed if this property is not supplied.
DBMaxConTime
- if connection pooling is on, the maximum time a connection should be kept open
before refreshing it. 1
day is used if this property is not supplied.
DBLongStreaming
- the type of streaming to be used to read/write LONGVARCHAR values. Set this to
NONE
if no streaming is required, to ASCII
if ascii streaming is required, or to
CHARACTER
if character (unicode) streaming is required. Typically MS Access requires ascii streaming
and Oracle/SQLServer require character streaming. Character streaming will be used if this property is not supplied.
DBConnectionPooling
- set this to true
in order to use database connection
pooling. Database connection pooling will be used if this property is not supplied.
DBDebugOutput
- if connection pooling is on, set this to true
in order to display
debug information to the java console indicating when connections are opened/closed, etc. Debug information will not
be displayed if this property is not supplied.
The framework for the exist
, get
, update
, and
delete
methods that form the bulk of the API are provided by this class. The specifics of these
methods are implemented by the derived classes.
Modifier and Type | Field and Description |
---|---|
static int |
LEVEL_ALL
A valid value that can be passed to the
setDetailLevel method. |
static int |
LEVEL_ALL_PLUS_RELATED
A valid value that can be passed to the
setDetailLevel method. |
static int |
LEVEL_DETAIL
A valid value that can be passed to the
setDetailLevel method. |
static int |
LEVEL_ID
A valid value that can be passed to the
setDetailLevel method. |
static int |
LEVEL_SUMMARY
A valid value that can be passed to the
setDetailLevel method. |
Constructor and Description |
---|
CSDatabaseItem()
Creates an empty
CSDatabaseItem , no database information is specified. |
CSDatabaseItem(java.lang.String strPropertyFile)
Creates a new
CSDatabaseItem , specifying a property files that contains all of the database
connection details. |
Modifier and Type | Method and Description |
---|---|
void |
clearRecordedGatewayMessages()
Clears the record of sent gateway messages.
|
java.lang.Object |
clone()
Creates a duplicate of this
CSDatabaseItem object. |
int |
count()
Counts the number of items that are retrievable by get().
|
void |
delete()
Deletes an item from the database.
|
boolean |
equals(java.lang.Object obj)
Determines whether the data contained in this
CSDatabaseItem object is the same as that contained
within the one supplied. |
boolean |
exist()
Checks to see whether this item exists on the database.
|
void |
get()
Retrieves the details of an item from the database.
|
java.util.ArrayList<?> |
getCache()
Get the contents of the cache.
|
boolean |
getCachingEnabled()
Indicate if caching is enabled globally.
|
double |
getDatabaseVersion()
Returns the iCM version number as a double in the format N.NNNN
For example, iCM 5.4.1 would return as 5.0401, and iCM 8.0.0 would be returned as 8.0
|
static double |
getDatabaseVersion(java.lang.String strPropertyFile)
Returns the iCM version number as a double in the format N.NNNN
For example, iCM 5.4.1 would return as 5.0401, and iCM 8.0.0 would be returned as 8.0
|
boolean |
getDebugOutput()
Gets the state of the debug output flag.
|
int |
getDetailLevel()
|
boolean |
getPreview()
Gets the state of the preview flag.
|
java.lang.String |
getPropertyFile()
Indicates the name of the property file in which the database connection details are held.
|
java.lang.String |
getPropertyFileExtension()
Indicates the file extension of the property file in which the database connection details are held.
|
java.lang.String |
getPropertyFilePathname()
Indicates the full path name of the property file in which the database connection details are held.
|
java.util.ArrayList |
getRecordedGatewayMessages()
Returns an array of recorded gateway messages.
|
boolean |
getRecordGatewayMessages()
Determines whether a record of any sent gateway messages should be kept.
|
boolean |
getSendGatewayMessages()
Indicates whether gateway messages should be generated and sent
Gateway messages are used to ensure that content event handlers get called,
that search collections get updated, that the file store is kept in sync, and so on.
|
boolean |
getUseCache()
Determines whether the cache is to be used for retrieving object definition information.
|
void |
setDebugOutput(boolean bDebugOutput)
Sets the state of the debug output flag.
|
void |
setDetailLevel(int nDetailLevel)
|
void |
setPreview(boolean bPreview)
Sets the state of the preview flag.
|
void |
setPropertyFile(java.lang.String strPropertyFile)
Specifies the property file from which database connection details are to be taken.
|
void |
setRecordGatewayMessages(boolean bRecord)
Specifies whether a record of any sent gateway messages should be kept.
|
void |
setSendGatewayMessages(boolean value)
Indicates whether gateway messages should be generated and sent
Gateway messages are used to ensure that content event handlers get called,
that search collections get updated, that the file store is kept in sync, and so on.
|
void |
setUseCache(boolean bUseCache)
Specifies whether the cache should be used to retrieve object definition information.
|
java.lang.String |
toString()
Outputs the contents of this
CSDatabaseItem object to a String object in a
user-friendly format. |
void |
update()
Writes the contents of this
CSDatabaseItem object to the database. |
public static final int LEVEL_ID
setDetailLevel
method. LEVEL_ID
indicates that just ID information should be retrieved from the database. Refer to the help for a particular
derived class for more information.public static final int LEVEL_SUMMARY
setDetailLevel
method.
LEVEL_SUMMARY
indicates that just summary information should be retrieved from the database. Refer
to the help for a particular derived class for more information.public static final int LEVEL_DETAIL
setDetailLevel
method.
LEVEL_DETAIL
indicates that detailed information should be retrieved from the database. Refer to
the help for a particular derived class for more information.public static final int LEVEL_ALL
setDetailLevel
method.
LEVEL_ALL
indicates that all information should be retrieved from the database. Refer to the help
for a particular derived class for more information.public static final int LEVEL_ALL_PLUS_RELATED
setDetailLevel
method.
LEVEL_ALL_PLUS_RELATED
indicates that all information about the item plus details of related items
should be retrieved from the database. Refer to the help for a particular derived class for more information.public CSDatabaseItem()
CSDatabaseItem
, no database information is specified.public CSDatabaseItem(java.lang.String strPropertyFile)
CSDatabaseItem
, specifying a property files that contains all of the database
connection details.
strPropertyFile
- the property file that contains the connection details.public void setPropertyFile(java.lang.String strPropertyFile)
strPropertyFile
- the name/location of the property file.public java.lang.String getPropertyFile()
public java.lang.String getPropertyFilePathname()
public java.lang.String getPropertyFileExtension()
public boolean getCachingEnabled()
enableCaching
to false. This is required when using the API from within the
icmapi worker within the API Server.true
if caching is globally enabled.public void setUseCache(boolean bUseCache)
bUseCache
- Set to true
if the cache is to be used wherever possiblepublic boolean getUseCache()
true
if the cache is currently being usedpublic void setRecordGatewayMessages(boolean bRecord)
bRecord
- Set to true
to record gateway messagespublic boolean getRecordGatewayMessages()
true
if gateway messages should be recordedpublic void clearRecordedGatewayMessages()
public java.util.ArrayList getRecordedGatewayMessages()
ArrayList
of String
objects, each containing a comma-separated list of
values for one of the specified columns.public boolean getSendGatewayMessages()
public void setSendGatewayMessages(boolean value)
value
- true if the gateway messages should be sent, false otherwisepublic void setDetailLevel(int nDetailLevel) throws CSParameterException
get
and update
methods.
Typically, the valid detail levels are as follows, though these can be restricted by derived classes :
LEVEL_ID
LEVEL_SUMMARY
LEVEL_DETAIL
LEVEL_ALL
nDetailLevel
- the detail level to be used.CSParameterException
- if an invalid detail level is specified.public int getDetailLevel()
public boolean getDebugOutput()
true
then the results of each
exist
, get
, update
, and delete
operation
are written to standard out.
true
if debug output is turned on.public void setDebugOutput(boolean bDebugOutput)
true
then the results of each
exist
, get
, update
, and delete
operation
are written to standard out.
bDebugOutput
- set true
to turn on debugging.public boolean getPreview()
This should be true
when an article is being previewed from within iCM.
true
if preview tables are being used rather than live article tables.public void setPreview(boolean bPreview)
This should be true
when an article is being previewed from within iCM.
bPreview
- a value of true
means that database queries will use preview tables rather than live
article tables.public boolean exist() throws CSException
true
if the item exists on the database.CSDatabaseException
- if there are problems accessing the database.CSParameterException
- if an invalid combination of key information has been supplied.CSException
- the base class for exceptions thrown by this method.public int count() throws CSException
CSDatabaseException
- if there are problems accessing the database.CSParameterException
- if an invalid combination of key information has been supplied.CSException
- the base class for exceptions thrown by this method.public void get() throws CSException
CSDatabaseItem
object.
CSDatabaseException
- if there are problems accessing the database.CSNotFoundException
- if the specified item cannot be found on the database.CSParameterException
- if an invalid combination of key information has been supplied.CSSecurityException
- if security has been breached.CSException
- the base class for exceptions thrown by this method.public void update() throws CSException
CSDatabaseItem
object to the database. The implementation details of
this function are specific to each subclass, but generally if an item with the supplied key information does not
already exist on the database it will be created. Otherwise, the existing item will be updated.
CSDatabaseException
- if there are problems accessing the database.CSNotFoundException
- if the specified item cannot be found on the database.CSParameterException
- if an invalid combination of key information has been supplied.CSException
- the base class for exceptions thrown by this method.public void delete() throws CSException
CSDatabaseException
- if there are problems accessing the database.CSNotFoundException
- if the specified item cannot be found on the database.CSParameterException
- if an invalid combination of key information has been supplied.CSException
- the base class for exceptions thrown by this method.public java.lang.Object clone() throws java.lang.CloneNotSupportedException, java.lang.OutOfMemoryError
CSDatabaseItem
object.
clone
in class java.lang.Object
CSDatabaseItem
object, distinct from, but identical in every way to the
original.java.lang.CloneNotSupportedException
- thrown if cloning is not supported/allowed.java.lang.OutOfMemoryError
- thrown if there are any problems allocating memory.public boolean equals(java.lang.Object obj)
CSDatabaseItem
object is the same as that contained
within the one supplied.
equals
in class java.lang.Object
obj
- the CSDatabaseItem
object to be tested for equality.true
if the data matches, false
otherwise.public java.lang.String toString()
CSDatabaseItem
object to a String
object in a
user-friendly format.
toString
in class java.lang.Object
String
containing the user-friendly output.public static double getDatabaseVersion(java.lang.String strPropertyFile) throws CSException
strPropertyFile
- the property file that contains the connection details.double
that represents the iCM versionCSException
public double getDatabaseVersion() throws CSException
double
that represents the iCM versionCSException
- CSExceptionpublic java.util.ArrayList<?> getCache()
Copyright © 2022 Goss Interactive Ltd. All Rights Reserved.