public class CSMediaMultiple extends CSItemMultiple
The CSMediaMultiple
class provides a method, get()
, that retrieves several media items
from the database. This method requires that certain database and key information (media IDs, for example) be
specified via the set
methods provided, prior to its invocation.
All database access/connectivity is handled internally by the CSMediaMultiple
class.
CSMedia
,
CSMediaContent
,
Serialized FormModifier and Type | Field and Description |
---|---|
static int |
CHANGE_CREATED
A valid value that can be passed to the
setChangedAction method. |
static int |
CHANGE_UPDATED
A valid value that can be passed to the
setChangedAction method. |
LEVEL_ALL, LEVEL_ALL_PLUS_RELATED, LEVEL_DETAIL, LEVEL_ID, LEVEL_SUMMARY
Constructor and Description |
---|
CSMediaMultiple()
Default constructor that creates an empty
CSMediaMultiple object. |
CSMediaMultiple(java.lang.String strPropertyFile)
Creates an empty
CSMediaMultiple object, specifying a property file that contains all of the
database connection details. |
Modifier and Type | Method and Description |
---|---|
void |
get()
Retrieves the details of several media items from the database.
|
int |
getArticleID()
Get the article ID.
|
boolean |
getChanged()
Gets the flag that indicates whether only those media items that have been changed within a specified time frame
are to be retrieved.
|
int |
getChangedAction()
Gets the type of changes that are of interest when the
setChanged method is used. |
java.util.Date |
getChangedEndDate()
Gets the End Date of the time frame used by the
setChanged method. |
boolean |
getChangedSignificantly()
Gets the flag used by the
setChanged method that indicates whether only media items
that have been changed significantly are of interest. |
java.util.Date |
getChangedStartDate()
Gets the Start Date of the time frame used by the
setChanged method. |
boolean |
getExcludeFailedItems()
Gets a flag which indicates whether or not media items which could not not be retrieved should be included in
the results.
|
java.lang.String |
getExcludeGroupName()
Get the exclude media group name.
|
java.lang.String |
getExcludeGroupNameList()
Get the list of media group names whose items are to be excluded by the
get method. |
java.lang.String |
getExcludeMetaDataIDs()
Gets the list of exclude metadata values IDs specified as key information.
|
java.lang.String |
getGroupList()
Get the list of group IDs for which the UserId belongs.
|
java.lang.String |
getGroupName()
Get the media group name.
|
java.lang.String |
getGroupNameList()
Get the list of media group names.
|
boolean |
getIgnoreVisibility()
Gets the flag which indicates whether invisible media items should be retrieved.
|
java.lang.String |
getMediaDirectory()
Get the media's absolute directory path where the media files are stored for the website, for example,
'C:\inetpub\wwwroot\website\media'.
|
java.lang.String |
getMediaList()
Get the list of media IDs.
|
int |
getMetaDataID()
Deprecated.
Use
getMetaDataIDs() instead. |
java.lang.String |
getMetaDataIDs()
Gets the list of metadata values IDs specified as key information.
|
java.lang.String |
getMetaDataOptionalIDs()
Gets the list of optional metadata values IDs specified as key information.
|
boolean |
getOverrideSecurity()
Gets the flag which indicates whether media should be retrieved, (except filenames) even if they fail media
security checks.
|
int |
getProductOptionID()
Get the product option ID.
|
java.lang.String |
getRootMediaIDs()
Gets the IDs of Root Media Groups.
|
java.lang.String |
getSubType()
Get the media sub-type.
|
boolean |
getTolerateNotFound()
Gets the flag that indicates whether a 'not found' exception is suppressed when a requested media item cannot be
found.
|
java.lang.String |
getType()
Get the media type.
|
int |
getUserID()
Gets the website User ID specified as key information.
|
void |
setArticleID(int nArticleID)
Set the article ID.
|
void |
setChanged(boolean bChanged)
Set to True to retrieve just those media items that have been changed within a specified time frame.
|
void |
setChangedAction(int nAction)
Specifies the type of changes that are of interest when the
setChanged method is
used. |
void |
setChangedEndDate(java.util.Date objEndDate)
Sets the End Date of the time frame used by the
setChanged method. |
void |
setChangedSignificantly(boolean bChangedSignificantly)
Set to false when using the
setChanged method to indicate that all media item
changes (both creates and updates) are of interest. |
void |
setChangedStartDate(java.util.Date objStartDate)
Sets the Start Date of the time frame used by the
setChanged method. |
void |
setDetailLevel(int nDetailLevel)
Sets the level of detail to be handled by the
get method. |
void |
setExcludeFailedItems(boolean bExcludeFailedItems)
Sets a flag which indicates whether or not media items which could not not be retrieved should be included in
the results.
|
void |
setExcludeGroupName(java.lang.String strExcludeGroupName)
Set the exclude media group name.
|
void |
setExcludeGroupNameList(java.lang.String strExcludeGroupNameList)
Set the list of exclude media group names.
|
void |
setExcludeMetaDataIDs(java.lang.String strExcludeMetaDataIDs)
Specifies IDs of the metadata values that all retrieved media must NOT be related to.
|
void |
setGroupList(java.lang.String strGroupList)
Set the list of group IDs for which the UserID belongs (provided to optimise performance).
|
void |
setGroupName(java.lang.String strGroupName)
Set the media group name.
|
void |
setGroupNameList(java.lang.String strGroupNameList)
Set the list of media group names.
|
void |
setIgnoreVisibility(boolean bIgnoreVisibility)
Sets the flag which indicates whether invisible media items should be retrieved.
|
void |
setMediaDirectory(java.lang.String strMediaDirectory)
Set the media's absolute directory path where the media files are stored for the website, for example,
'C:\inetpub\wwwroot\website\media'.
|
void |
setMediaList(java.lang.String strMediaList)
Set the list of media IDs.
|
void |
setMetaDataID(int nMetaDataID)
Deprecated.
Use
setMetaDataIDs(String) instead. |
void |
setMetaDataIDs(java.lang.String strMetaDataIDs)
Specifies IDs of the metadata values that all retrieved media must be related to.
|
void |
setMetaDataOptionalIDs(java.lang.String strMetaDataOptionalIDs)
Specifies IDs of the metadata values that all retrieved media must be related to one or more of.
|
void |
setOverrideSecurity(boolean bOverrideSecurity)
Sets a flag to indicate whether media should be retrieved, even if they fail the media security checks.
|
void |
setProductOptionID(int nProductOptionID)
Set the product option ID.
|
void |
setRootMediaIDs(java.lang.String strRootMediaIDs)
Sets the IDs of Root Media Groups.
|
void |
setSortOrder(java.lang.String strSortOrderList)
Set the order in which media items will be retrieved.
|
void |
setSubType(java.lang.String strSubType)
Set the media sub-type.
|
void |
setTolerateNotFound(boolean bTolerateNotFound)
Sets a flag to prevent a 'not found' exception from being generated when a requested media item cannot be found.
|
void |
setType(java.lang.String strType)
Set the required media type.
|
void |
setUserID(int nUserID)
Sets the website User ID to be used as key information.
|
java.lang.String |
toString()
Output the contents of this
CSMediaMultiple object to a String object in a
user-friendly format. |
delete, equals, exist, getItems, getMaxRows, getSortOrder, getStartRow, iterator, setItems, setMaxRows, setStartRow, update
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 int CHANGE_CREATED
setChangedAction
method.
CHANGE_CREATED
indicates that just media items created within the specified timeframe should be
retrieved. Refer to the help for the setChanged
method for more information.public static final int CHANGE_UPDATED
setChangedAction
method.
CHANGE_UPDATED
indicates that just media items updated within the specified time frame should be
retrieved. Refer to the help for the setChanged
method for more information.public CSMediaMultiple()
CSMediaMultiple
object.
Use the various set methods provided to initialise the CSMediaType
object prior to invoking any of
its query methods.
public CSMediaMultiple(java.lang.String strPropertyFile)
CSMediaMultiple
object, specifying a property file that contains all of the
database connection details.
Use the various set
methods to initialise the CSMediaMultiple
object prior to
invoking get()
.
strPropertyFile
- the name of the property file from which the database connection details are to be read.public void setChanged(boolean bChanged)
Use in conjunction with the setChangedStartDate
,
setChangedEndDate
, setChangedAction
and setChangedSignificantly
methods to indicate the type of change and
the time frame within which the changes need to have occurred.
As well as being specified on their own, these methods can also be used in conjunction with the other methods
such as setArticleID
. It may not, however, be used in conjunction with the
setMediaList
method.
bChanged
- true if only retrieving media items that have been changed within a specified time frame, false
otherwise.public boolean getChanged()
public void setChangedAction(int nAction) throws CSParameterException
setChanged
method is
used.
Valid actions are :
CSMediaMultiple.CHANGE_CREATED
Retrieves just those media items that were created
within the specified time frame.
CSMediaMultiple.CHANGE_UPDATED
Retrieves just those media items that were updated
within the specified time frame.
More than one action can be specified by ORing valid actions together. The default, for example, is CSMediaMultiple.CHANGE_CREATED | CSMediaMultiple.CHANGE_UPDATED so that both created and updated media items will be retrieved.
nAction
- the action to be used.CSParameterException
- if an invalid action is specified.public int getChangedAction()
setChanged
method is used.
public void setChangedStartDate(java.util.Date objStartDate)
setChanged
method.
Media items created/modified after this date and before the date specified via the
setChangedEndDate
method (inclusive) will be retrieved. Defaults to 7
days before the current date.
objStartDate
- the start date to be used as key information.public java.util.Date getChangedStartDate()
setChanged
method.
Media items created/modified after this date and before the date specified via the
setChangedEndDate
method (inclusive) will be retrieved.
public void setChangedEndDate(java.util.Date objEndDate)
setChanged
method.
Media items modified before this date and after the 'ChangedStartDate' (inclusive) will be retrieved. Defaults to the current date.
objEndDate
- the end date to be used as key information.public java.util.Date getChangedEndDate()
setChanged
method.
public void setChangedSignificantly(boolean bChangedSignificantly)
setChanged
method to indicate that all media item
changes (both creates and updates) are of interest. Defaults to true so that only media items that are marked as
having significant changes made during the specified time frame will be retrieved. The ability to flag a change
as significant was introduced in iCM 7.0 and so this parameter will be ignored when running against earlier
versions of the database.
Use in conjunction with the setChangedStartDate
,
setChangedEndDate
, setChangedAction
methods to indicate the type of change and the time frame within which the changes need to have occurred.
bChangedSignificantly
- true to retrieve media items flagged as having significant changes, false to retrieve media items that
have been changed regardless of significance.public boolean getChangedSignificantly()
setChanged
method that indicates whether only media items
that have been changed significantly are of interest.
The ability to flag a change as significant was introduced in iCM 7.0.
public void setMediaDirectory(java.lang.String strMediaDirectory)
The value of this MediaDirectory setting will be used to form the complete file path for each associated media
file in its CSMediaContentFile
object. This media file path is only required when using the media
webservice to insert a new, or update an existing, media item.
strMediaDirectory
- a String
containing the media's absolute directory path.public java.lang.String getMediaDirectory()
The value of this MediaDirectory setting will be used to form the complete file path for each associated media
file in its CSMediaContentFile
object. This media file path is only required when using the media
webservice to insert a new, or update an existing, media item.
String
containing the media's absolute directory path.public void setMediaList(java.lang.String strMediaList)
get
. If the media ID list is specified, ArticleID should not be.
strMediaList
- a String
containing a comma-separated list of IDs of the specific media items to be
retrieved.public java.lang.String getMediaList()
String
containing a comma-separated list of IDs of the specific media items to be
retrieved.public void setArticleID(int nArticleID)
get
. If
the article ID is is specified, MediaList should not be.
nArticleID
- the unique numeric ID of the article whose related media will be retrieved.public int getArticleID()
public void setProductOptionID(int nProductOptionID)
get
. If the product option ID is specified, ProductTypeID, ContactID, MediaList, ArticleID,
AttributeID, AttributeTypeID, and CreditCardID should not be.
nProductOptionID
- the unique numeric ID of the product option.public int getProductOptionID()
public void setTolerateNotFound(boolean bTolerateNotFound)
If this flag is set, any items not found will be included in the list of returned items but with 'nulled' content.
bTolerateNotFound
- The flag indicating if missing media items should be included in the returned set.public boolean getTolerateNotFound()
If this flag is set, any media items not found will be included in the set of returned items but with 'nulled' content.
public void setExcludeFailedItems(boolean bExcludeFailedItems)
The setTolerateNotFound
and setOverrideSecurity
properties make it possible to make requests for items which are not
found (possibly due to display criteria) or inaccessible due to security without an exception being thrown. If these flags are set then any inaccessible
items will be included in the results list with their Status set to DOES_NOT_EXIST or SECURE_ACCESS_DENIED.
If the ExcludeFailedItems flag is also set then any inaccessible items will not be included in the results list.
Note that it will still be necessary to set setTolerateNotFound
and/or setOverrideSecurity
as required.
bExcludeFailedItems
- The flag which indicates whether or not media items which could not not be retrieved should be included in the results.public boolean getExcludeFailedItems()
The setTolerateNotFound
and setOverrideSecurity
properties make it possible to make requests for items which are not
found (possibly due to display criteria) or inaccessible due to security without an exception being thrown. If these flags are set then any inaccessible
items will be included in the results list with their Status set to DOES_NOT_EXIST or SECURE_ACCESS_DENIED.
If the ExcludeFailedItems flag is also set then any inaccessible items will not be included in the results list.
Note that it will still be necessary to set setTolerateNotFound
and/or setOverrideSecurity
as required.
public void setMetaDataID(int nMetaDataID)
setMetaDataIDs(String)
instead.
setMetaDataID
followed by a call to get
will return details of the media which have
the specified metadata item.
nMetaDataID
- the ID of the metadata item which is asociated with the media to be retrieved.public int getMetaDataID()
getMetaDataIDs()
instead.get
method.public void setMetaDataIDs(java.lang.String strMetaDataIDs)
setMetaDataIDs
followed by a call to get
returns details of all the media that are
related to ALL of the specified metadata values.
setMetaDataIDs
may be used as a primary key or in conjunction with other primary keys (e.g.
setArticleID
) as a further filter.
strMetaDataIDs
- a comma-separated list of metadata value IDs.setMetaDataOptionalIDs
,
setExcludeMetaDataIDs
public java.lang.String getMetaDataIDs()
public void setMetaDataOptionalIDs(java.lang.String strMetaDataOptionalIDs)
setMetaDataOptionalIDs
followed by a call to get
returns details of all the media
that are related to at least one of the specified metadata values.
setMetaDataOptionalIDs
may be used as a primary key or in conjunction with other primary keys
(e.g. setArticleID
) as a further filter.
strMetaDataOptionalIDs
- a comma-separated list of metadata value IDs.setMetaDataIDs
,
setExcludeMetaDataIDs
public java.lang.String getMetaDataOptionalIDs()
public void setExcludeMetaDataIDs(java.lang.String strExcludeMetaDataIDs)
setExcludeMetaDataIDs
followed by a call to get
returns details of all the media
that are NOT related to any of the specified metadata values.
setExcludeMetaDataIDs
may be used as a primary key or in conjunction with other primary keys (e.g.
setArticleID
) as a further filter.
strExcludeMetaDataIDs
- a comma-separated list of metadata value IDs.setMetaDataOptionalIDs
,
setMetaDataIDs
public java.lang.String getExcludeMetaDataIDs()
public void setGroupName(java.lang.String strGroupName)
get
method. If * is placed at the end of the group name it means 'starting with'. You should not
specify media group name if you are specifying a list of media IDs.
strGroupName
- a String
containing the name of the media group.public java.lang.String getGroupName()
String
containing the name of the media group.public void setGroupNameList(java.lang.String strGroupNameList)
get
method.
strGroupNameList
- a String
containing a comma-separated list of media group names.public java.lang.String getGroupNameList()
String
containing a comma-separated list of media group names.public void setGroupList(java.lang.String strGroupList)
strGroupList
- a String
containing a comma-separated list of IDs of the UserIDs groups.public java.lang.String getGroupList()
String
containing a comma-separated list of IDs of the UserIDs groups.public void setExcludeGroupName(java.lang.String strExcludeGroupName)
get
method. If * is placed at the end of the group name it means 'starting with'. You should
not specify an exclude media group name if you are specifying a list of media IDs.
strExcludeGroupName
- a String
containing the name of the media group.public java.lang.String getExcludeGroupName()
String
containing the name of the media group.public void setExcludeGroupNameList(java.lang.String strExcludeGroupNameList)
get
method.
strExcludeGroupNameList
- a String
containing a comma-separated list of media group names.public java.lang.String getExcludeGroupNameList()
get
method.
String
containing a comma-separated list of media group names.public void setType(java.lang.String strType)
get
method.
This parameter should not be specified in conjunction with a list of media IDs.
strType
- a String
containing one of [images, docs, video, quicktime, audio, adobe, powerpoint,
excel, zip] or any other defined media type, or a comma seperated list of these.public java.lang.String getType()
String
containing a comma-separated list of media types which can be retrieved by the
get
function.public void setSubType(java.lang.String strSubType)
strSubType
- a String
containing the required media sub-type.public java.lang.String getSubType()
String
containing the required media sub-type.public void setUserID(int nUserID)
Do not set User ID if you are only interested in retrieving unsecured media, as this will result in a faster query.
setUserID
and an appropriate set
method for media ID followed by a call to
get
will return details of the media which are either unsecured articles, or secured articles to
which the specified user has access.
nUserID
- the ID of the user to be used in media security checks.public int getUserID()
public void setOverrideSecurity(boolean bOverrideSecurity)
If this flag is set, media security checks are still performed but the media details (except filenames) are retrieved even if the checks fail.
bOverrideSecurity
- true if media should be retrieved regardless of the outcome of the media security checks.public boolean getOverrideSecurity()
If this flag is set, media security checks are still performed but the media details are retrieved even if the checks fail.
public void setIgnoreVisibility(boolean bIgnoreVisibility)
Set IgnoreVisibility
to true
prior to a call to get
to retrieve
media items regardless of their visibility settings. By default, IgnoreVisibility
is set to
false
so that only visible media items (those in date and turned on) will be returned.
bIgnoreVisibility
- true if the media items should be retrieved regardless of visibility; otherwise false.public boolean getIgnoreVisibility()
Set IgnoreVisibility
to true
prior to a call to get
to retrieve
media items regardless of their visibility settings. By default, IgnoreVisibility
is set to
false
so that only visible media items (those in date and turned on) will be returned.
public void setSortOrder(java.lang.String strSortOrderList) throws CSParameterException
One or more of the available sort orders may be specified as a comma-delimited list. Use ASC or DESC to indicate
the direction of ordering for a sort order. For example, "TYPE DESC" would order in descending media type order.
ASC is assumed if neither ASC or DESC are specified. If using the setArticleID
method,
the default sort order will be as configured for media within iCM.
Available sort orders are :
MEDIAID - order by media ID
DISPLAYDATE - order by media display date
TYPE - order by media type
GROUPNAME - order by media group name
TITLE - order by media title
setSortOrder
in class CSItemMultiple
strSortOrderList
- a comma-separated list of one or more of the available sort orders.CSParameterException
- if an invalid sort order was specifiedpublic void setDetailLevel(int nDetailLevel) throws CSParameterException
get
method.
Valid detail levels for media are :
LEVEL_ID - the media ID
LEVEL_SUMMARY - the title, description, linked article ID, external link ID, media directory and group name
LEVEL_DETAIL - the creation date, display on/off state, display start and end dates, last modified date, review details
LEVEL_ALL - the media file details
LEVEL_ALL_PLUS_RELATED - the related metadata IDs
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 used.CSParameterException
- if an invalid detail level is specified.public void setRootMediaIDs(java.lang.String strRootMediaIDs)
strRootMediaIDs
- A comma seperated list of poll group IDs.public java.lang.String getRootMediaIDs()
public void get() throws CSException
CSNotFoundException
to
be thrown. Use the setIgnoreVisibility
method with a true
parameter if you wish to retrieve media items regardless of their visibility settings.
Use setMediaList
followed by get
to populate this
CSMediaMultiple
object with the details of the media items specified in the list. If a sort order
was specified using the setSortOrder
method then the retrieved media items will
appear within CSMediaMultiple
in that order, else they will be in the order that their IDs appear
within the supplied list. Key information set using setMaxRows
and
setStartRow
is not valid in this instance.
Use setGroupName
followed by get
to populate this
CSMediaMultiple
object with the details of the media items for the specified media group.
Use setGroupNameList
followed by get
to populate this
CSMediaMultiple
object with the details of the media items for the specified list of media groups.
Use setSubType
followed by get
to populate this
CSMediaMultiple
object with the details of the media items for the specified sub-type [i.e.
'Thumbnail', 'Image' or 'LargeImage'].
Use setType
followed by get
to populate this CSMediaMultiple
object with the details of the media items for the specified type [i.e. images, docs, video, quicktime, audio,
adobe, powerpoint, excel or zip].
Use setUserID
followed by get
to populate this
CSMediaMultiple
object with the details of the media items for the specified web user.
Use setGroupList
followed by get
to populate this
CSMediaMultiple
object with the details of the media items for the specified list of web user
groups.
Use setArticleID
followed by get
to populate this
CSMediaMultiple
object with the details of the media items for the specified article.
Use setMetaDataIDs
followed by get
to populate this
CSMediaMultiple
object with the details of the media that are related to ALL of the specified
metadata values.
Use setMetaDataOptionalIDs
followed by get
to populate
this CSMediaMultiple
object with the details of the media that are related to one or more of the
specified metadata values.
Use setExcludeMetaDataIDs
followed by get
to populate this
CSMediaMultiple
object with the details of the media that are NOT related to any of the specified
metadata values.
The setMetaDataIDs
, setMetaDataOptionalIDs
and setExcludeMetaDataIDs
methods may be used as the primary key information or in conjunction with other primary keys (with the exception
of setMediaList
).
Use setChanged
and the associated methods, followed by get
to
retrieve all media items that have been modified within a specified time frame. These methods may not be used in
conjunction with the setMediaList
method.
Each retrieved media item is stored as a CSMedia
object within the item ArrayList
member
of CSMediaMultiple
- use getItems
or iterator
to
access/navigate through them. These media items will be stored in the ArrayList
in the order
specified using the setSortOrder
method, or the default sort order of 'Media Title
ASC'). However, if a list of media IDs was specified, the media items are stored in the same order as in the
specified list.
To be retrieved, a media item's display date range must be current and the media item must be turned on within
iCM. During the get()
operation, a CSMediaContentFile
object is created for each filename,
filepath and filetype, and is stored via an ArrayList
within this CSMediaMultiple
object. Use the getFileArray
method of CSMedia
to retrieve these file name objects.
NOTE ON MEDIA SECURITY :
If a list of media IDs is specified using the setMediaList
method, every media item in the list
must pass security checks. A CSSecurityException
will be thrown if no User ID has been specified
using the setUserID
method, and one or more of the media items is a secured media item,
or a User ID has been specified, but the specified user does not have access to one or more of the media items.
For all other types of retrieval, any media items which do not pass security checks are simply ignored.
For performance reasons, you should not specify a User ID if you are not interested in secure articles. It is
also more efficient to specify the user groups to which the user belongs, using the
setGroupList
method, if they are already known.
OVERRIDING MEDIA SECURITY :
For all types of retrieval, use the setOverrideSecurity
method if you want
to retrieve limited media details even if no User ID has been specified, or the specified user fails the media
security checks described above.
The same security checks are performed, but the media details (with the exception of filenames), are retrieved regardless of the outcome of these checks.
get
in class CSItemMultiple
CSParameterException
- if an invalid combination of key information has been supplied.CSDatabaseException
- if there are problems accessing the database.CSNotFoundException
- if one of the specified articles cannot be found on the database.CSSecurityException
- if security has been breached.CSException
- the base class for exceptions thrown by this method.public java.lang.String toString()
CSMediaMultiple
object to a String
object in a
user-friendly format.
toString
in class CSItemMultiple
String
containing the user-friendly output.Copyright © 2022 Goss Interactive Ltd. All Rights Reserved.