gi.controlsite.objects

Class CSFeatureMultiple

java.lang.Object

gi.controlsite.objects.CSDatabaseItem

gi.controlsite.objects.CSItemMultiple

gi.controlsite.objects.CSFeatureMultiple

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class CSFeatureMultiple
extends CSItemMultiple

Class that handles the querying and storage of a multiple feature groups.

The CSFeatureMultiple class provides a method that retrieves several features from the database. This method requires that certain database and key information (feature IDs, for example) be specified via the set methods provided, prior to its invocation.

All database access/connectivity is handled internally by the CSFeatureMultiple class.

See Also:

CSFeatureGroup, CSFeatureGroupContent, CSFeature, CSFeatureContent, CSArticle, Serialized Form

Field Summary

Fields inherited from class gi.controlsite.objects.CSDatabaseItem

LEVEL_ALL, LEVEL_ALL_PLUS_RELATED, LEVEL_DETAIL, LEVEL_ID, LEVEL_SUMMARY

Constructor Summary

Constructors

Constructor and Description
CSFeatureMultiple() Creates an empty CSFeatureMultiple object.
CSFeatureMultiple(java.lang.String strPropertyFile) Creates an empty CSFeatureMultiple object, specifying a property file that contains all of the database connection details.

Method Summary

Modifier and Type	Method and Description
void	delete() Not currently implemented for CSFeatureMultiple.
boolean	exist() Not currently implemented for CSFeatureMultiple.
void	get() Retrieves the details of several features from the database.
boolean	getArticleExtensionDataReqd() Gets the flag which indicates whether article extension data should be retrieved.
boolean	getDisplayAll() Deprecated. Replaced by getIgnoreVisibility().
java.lang.String	getFeatureGroupName() Gets the feature group name currently specified as key information.
java.lang.String	getFeatureList() Gets list of feature IDs currently specified as key information.
java.lang.String	getGroupList() Gets the IDs of the user groups in which the current user resides.
boolean	getIgnoreVisibility() Gets the flag that indicates whether the feature articles should be retrieved regardless of their visibility settings.
boolean	getOverrideSecurity() Indicates whether override security is on or not.
int	getRelatedArticleID() Gets the article ID currently specified as key information.
java.lang.String	getRootFeatureIDs() Gets the IDs of Root Feature Groups.
int	getUserID() Gets the ID of the website user specified as key information.
void	setArticleExtensionDataReqd(boolean bArticleExtensionDataReqd) Sets a flag to allow article extension data to be retrieved.
void	setDetailLevel(int nDetailLevel) Sets the level of detail to be handled by the get method.
void	setDisplayAll(boolean bDisplayAll) Deprecated. Replaced by setIgnoreVisibility(boolean).
void	setFeatureGroupName(java.lang.String strFeatureGroupName) Specifies the name of the feature group to be used as key information.
void	setFeatureList(java.lang.String strFeatureList) Specifies a list of feature IDs to be used as key information.
void	setGroupList(java.lang.String strGroupList) Specifies the IDs of all user groups of which the current user is a member.
void	setIgnoreVisibility(boolean bIgnoreVisibility) Sets the flag indicating whether the feature articles should be retrieved regardless of their visibility settings.
void	setOverrideSecurity(boolean bOverrideSecurity) Specifies whether to override security or not.
void	setRelatedArticleID(int nRelatedArticleID) Specifies the article ID to be used as key information.
void	setRootFeatureIDs(java.lang.String strRootFeatureIDs) Sets the IDs of Root Feature Groups.
void	setSortOrder(java.lang.String strSortOrder) Sets the order in which the features are to be retrieved.
void	setUserID(int nUserID) Specifies the ID of the current website user to be used as key information.
java.lang.String	toString() Outputs the contents of this CSFeatureMultiple object to a String object in a user-friendly format.
void	update() Not currently implemented for CSFeatureMultiple.

Methods inherited from class gi.controlsite.objects.CSItemMultiple

equals, getItems, getMaxRows, getSortOrder, getStartRow, iterator, setItems, setMaxRows, setStartRow

Methods inherited from class gi.controlsite.objects.CSDatabaseItem

clearRecordedGatewayMessages, clone, count, getCache, getCachingEnabled, getDatabaseVersion, getDatabaseVersion, getDebugOutput, getDetailLevel, getPreview, getPropertyFile, getPropertyFileExtension, getPropertyFilePathname, getRecordedGatewayMessages, getRecordGatewayMessages, getSendGatewayMessages, getUseCache, setDebugOutput, setPreview, setPropertyFile, setRecordGatewayMessages, setSendGatewayMessages, setUseCache

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CSFeatureMultiple

public CSFeatureMultiple()

Creates an empty CSFeatureMultiple object.

Use the various set methods provided to initialise the CSFeatureMultiple object prior to invoking any of its query methods.

CSFeatureMultiple

public CSFeatureMultiple(java.lang.String strPropertyFile)

Creates an empty CSFeatureMultiple object, specifying a property file that contains all of the database connection details.

Use the various set methods provided to initialise the CSFeatureMultiple object prior to invoking any of its query methods.

Parameters:

strPropertyFile - the name of the property file from which the database connection details are to be read.

Method Detail

setDetailLevel

public void setDetailLevel(int nDetailLevel)
                    throws CSParameterException

Sets the level of detail to be handled by the get method.

Valid detail levels for a feature are :

• LEVEL_ID - the feature, group and article IDs
• LEVEL_SUMMARY - the feature article's heading, intro text and template ID
• LEVEL_DETAIL - the feature article's parent ID, creation date, user ID, display toggle, display start date, display end date, archive flag and last modified date
• LEVEL_ALL - the feature article's text

Each detail level processes the information specified alongside it along with the information specified for all detail levels listed above it. The default level is LEVEL_DETAIL.

Overrides:

setDetailLevel in class CSDatabaseItem

Parameters:

nDetailLevel - the detail level to be used.

Throws:

CSParameterException - if an invalid detail level is specified.

setFeatureList

public void setFeatureList(java.lang.String strFeatureList)

Specifies a list of feature IDs to be used as key information.

setFeatureList followed by a call to get will populate this CSFeatureMultiple object with details of all the listed features. Each feature will be stored as a CSFeature object within the item ArrayList member - use getItems or iterator to access/navigate through the features. The features will be stored in the ArrayList in the order that the IDs are specified in the supplied list.

Parameters:

strFeatureList - a String object containing a comma-separated list of feature IDs.

getFeatureList

public java.lang.String getFeatureList()

Gets list of feature IDs currently specified as key information.

Returns:

A String object containing a comma-separated list of feature IDs.

setFeatureGroupName

public void setFeatureGroupName(java.lang.String strFeatureGroupName)

Specifies the name of the feature group to be used as key information.

setFeatureGroupName followed by get will result in this CSFeatureMultiple object being populated with the details of all features within the specified group. Each filter will be stored as a CSFeature object within the item ArrayList member - use getItems or iterator to access/navigate through the features. By default, the features will be stored in the ArrayList in ARTICLEDISPLAYDATE ASC order. This can be overridden by using the setSortOrder method. Use the setStartRow and setMaxRows methods to limit the number of groups retrieved.

Parameters:

strFeatureGroupName - the name of the feature group.

getFeatureGroupName

public java.lang.String getFeatureGroupName()

Gets the feature group name currently specified as key information.

Returns:

The name of the feature group.

setRelatedArticleID

public void setRelatedArticleID(int nRelatedArticleID)

Specifies the article ID to be used as key information.

setRelatedArticleID followed by get will result in this CSFeatureMultiple object being populated with the details of all features that are related to the article specified. Each feature will be stored as a CSFeature object within the item ArrayList member - use getItems or iterator to access/navigate through the features. By default, the features will be stored in the ArrayList in display order configured via iCM. This can be overridden by using the setSortOrder method. Use the setStartRow and setMaxRows methods to limit the number of features retrieved.

Parameters:

nRelatedArticleID - the ID of the article whose related features are required.

getRelatedArticleID

public int getRelatedArticleID()

Gets the article ID currently specified as key information.

Returns:

The article ID.

setDisplayAll

public void setDisplayAll(boolean bDisplayAll)

Deprecated. Replaced by setIgnoreVisibility(boolean).

Specifies whether or not feature articles that are currently turned 'off' or out of date are to be retrieved.

Typically, only those articles that are currently turned 'on' and in date will be retrieved. If bDisplayAll is set to true, turned 'off' and out of date feature articles will also be included.

Parameters:

bDisplayAll - true to include feature articles that are turned 'off' or out of date.

getDisplayAll

public boolean getDisplayAll()

Deprecated. Replaced by getIgnoreVisibility().

Indicates whether or not feature articles that are currently turned 'off' or out of date are to be retrieved.

Returns:

true indicates that feature articles that are turned 'off' or out of date will be included.

setIgnoreVisibility

public void setIgnoreVisibility(boolean bIgnoreVisibility)

Sets the flag indicating whether the feature articles should be retrieved regardless of their visibility settings.

Set to true if the feature articles are to be retrieved by the get method regardless of display dates and display flag. By default, a feature article will only be retrieved if its display start and end dates are current and its display flag is set to 'on'. In the default scenario where the ignore visibility flag is set to false, if a requested feature article does not exist, exists but is turned 'off', or is out of date a CSNotFoundException will be generated by the get method.

Parameters:

bIgnoreVisibility - true to include feature articles that are turned 'off' or out of date.

getIgnoreVisibility

public boolean getIgnoreVisibility()

Gets the flag that indicates whether the feature articles should be retrieved regardless of their visibility settings.

Returns:

true true indicates that feature articles that are turned 'off' or out of date will be included.

setUserID

public void setUserID(int nUserID)

Specifies the ID of the current website user to be used as key information.

This will be used to determine which feature articles the current user has access to and will affect which feature articles (or the status of the feature articles) that are retrieved.

To prevent unnecessary database access, do not specify the user ID if you are only interested in retrieving unsecured articles.

Parameters:

nUserID - the user's ID.

getUserID

public int getUserID()

Gets the ID of the website user specified as key information.

Returns:

The user's ID.

setGroupList

public void setGroupList(java.lang.String strGroupList)

Specifies the IDs of all user groups of which the current user is a member.

If this is not provided, the specified user ID (if any) will be used to retrieve this information from the database as required. Use this method to prevent unnecessary database access if the groups IDs have already been retrieved.

Do not set this list unless a user ID is also being specified.

Parameters:

strGroupList - a comma-separated list of user group IDs.

getGroupList

public java.lang.String getGroupList()

Gets the IDs of the user groups in which the current user resides.

Returns:

the list of user group IDs.

setOverrideSecurity

public void setOverrideSecurity(boolean bOverrideSecurity)

Specifies whether to override security or not.

Normally, only those feature articles that the current user has access to will be retrieved. If override security is set to 'on', however, feature articles that the user does not have access to will be included and their status can then be used to determine accessibility.

Parameters:

bOverrideSecurity - true to override security, or false to use security.

getOverrideSecurity

public boolean getOverrideSecurity()

Indicates whether override security is on or not.

Returns:

true if override security is on.

setArticleExtensionDataReqd

public void setArticleExtensionDataReqd(boolean bArticleExtensionDataReqd)

Sets a flag to allow article extension data to be retrieved. This allows article extension data to be returned for articles in the feature.

Parameters:

bArticleExtensionDataReqd - flag indicating if article extension data should be retrieved.

getArticleExtensionDataReqd

public boolean getArticleExtensionDataReqd()

Gets the flag which indicates whether article extension data should be retrieved. This allows article extension data to be returned for articles in the feature.

If this flag is set, article extension data will be retrieved.

Returns:

the flag indicating if article extension data should be retrieved.

setSortOrder

public void setSortOrder(java.lang.String strSortOrder)
                  throws CSParameterException

Sets the order in which the features are to be retrieved.

This method should not be used if the setFeatureList key information is being supplied - in this instance the features are retrieved in the same order as the supplied IDs. Otherwise, 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, "FEATUREGROUPNAME DESC" would order in descending group name order. ASC is assumed if neither ASC or DESC are specified. If using the setRelatedArticleID method, the default sort order will be as configured for the features within iCM. If using the setFeatureGroupName method, the default sort order will be ARTICLEDISPLAYDATE ASC. In both cases, use the setSortOrder method to override the default ordering.

Available sort orders are :

• FEATUREID - order by feature ID
• FEATUREGROUPID - order by group ID
• FEATUREGROUPNAME - order by group name
• ARTICLEID - order by article ID
• ARTICLEHEADING - order by the feature article's heading
• ARTICLEINTROTEXT - order by the feature article's intro text
• ARTICLEDATE - order by the feature article's creation date
• ARTICLEDISPLAYDATE - order by the feature article's display start date
• ARTICLEDISPLAYEDATE - order by the feature article's display end date
• LASTMODIFIEDDATE - order by the feature article's last modified date
• ARTICLETEMPLATEID - order by the feature article's template ID
• ARTICLEUSERID - order by the feature article's last updated by user ID

Overrides:

setSortOrder in class CSItemMultiple

Parameters:

strSortOrder - a comma-separated list of one or more of the available sort orders.

Throws:

CSParameterException - if an invalid sort order was specified

setRootFeatureIDs

public void setRootFeatureIDs(java.lang.String strRootFeatureIDs)

Sets the IDs of Root Feature Groups. If this parameter is set, then features are only considered to exist if they are within one of these groups (or their subgroups).

This parameter is useful to restrict feature queries to one particular subsite.

Parameters:

strRootFeatureIDs - A comma seperated list of feature group IDs.

getRootFeatureIDs

public java.lang.String getRootFeatureIDs()

Gets the IDs of Root Feature Groups. If this parameter is set, then features are only considered to exist if they are within one of these groups (or their subgroups).

Returns:

The A comma seperated list of feature group IDs.

exist

public boolean exist()
              throws CSException

Not currently implemented for CSFeatureMultiple.

Overrides:

exist in class CSItemMultiple

Returns:

true if all features exist on the database.

Throws:

CSParameterException - if an invalid combination of key information has been supplied.

CSDatabaseException - if there are problems accessing the database.

CSException - the base class for exceptions thrown by this method.

get

public void get()
         throws CSException

Retrieves the details of several features from the database.

By default, only those feature articles that are in date and currently turned 'on' will be retrieved. However, if setIgnoreVisibility is called with a true parameter, any feature articles that have been turned 'off' and/or that are not in date will also be retrieved.

Use setFeatureList followed by get to populate this CSFeatureMultiple object with details of all the features identified by the specified IDs. The retrieved features will appear within CSFeatureMultiple in the order that their IDs appear within the supplied list - as such, setSortOrder, setMaxRows and setStartRow are not valid in this instance.

Use setRelatedArticleID followed by get to populate this CSFeatureMultiple object with the details of all features that are related to the specified article. By default, the features will be retrieved in the display order configured via iCM. This can be overridden if required by using the setSortOrder method. The setStartRow and setMaxRows methods can be used to restrict the number of features that are retrieved.

Use setFeatureGroupName followed by get to populate this CSFeatureMultiple object with the details of all features that are within the specified group. By default, the features will be retrieved in article display start date (ARTICLEDISPLAYDATE) ascending order. This can be overridden if required by using the setSortOrder method. The setStartRow and setMaxRows methods can be used to restrict the number of features that are retrieved.

If none of setFeatureList, setRelatedArticleID or setFeatureGroupName are used, ALL features will be retrieved.

Each retrieved feature will be stored as a CSFeature object within the item ArrayList member of this CSFeatureMultiple object - use getItems or iterator to access/navigate through the features.

Overrides:

get in class CSItemMultiple

Throws:

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 features cannot be found on the database.

CSSecurityException - if security has been breached.

CSException - the base class for exceptions thrown by this method.

update

public void update()
            throws CSException

Not currently implemented for CSFeatureMultiple.

Overrides:

update in class CSItemMultiple

Throws:

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 features cannot be found on the database.

CSException - the base class for exceptions thrown by this method.

delete

public void delete()
            throws CSException

Not currently implemented for CSFeatureMultiple.

Overrides:

delete in class CSItemMultiple

Throws:

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 features cannot be found on the database.

CSException - the base class for exceptions thrown by this method.

toString

public java.lang.String toString()

Outputs the contents of this CSFeatureMultiple object to a String object in a user-friendly format.

Overrides:

toString in class CSItemMultiple

Returns:

The String containing the user-friendly output.