com.jivesoftware.community
Class DocumentResultFilter

java.lang.Object
  com.jivesoftware.community.ResultFilter
      com.jivesoftware.community.DocumentResultFilter

public class DocumentResultFilter
extends ResultFilter

Filters and sorts lists of Documents. This allows for a very rich set of possible queries that can be run. Some examples are: "Show all documents in the community, sorted by their modification date" or "Show all documents in the community created after xxx and with the extended property 'test' having a value of '12345'".

The class also supports pagination of results with the setStartIndex(int) and setNumResults(int) methods. If the start index is not set, it will begin at index 0 (the start of results). If the number of results is not set, it will be unbounded and return as many results as available.

Factory methods to create common queries are provided for convenience.

Field Summary

static int

NOT_MODE

Fields inherited from class com.jivesoftware.community.ResultFilter

AND_MODE, ASCENDING, CONTAINS_MATCH, DESCENDING, EXACT_MATCH, NULL_INT, OR_MODE

Constructor Summary

DocumentResultFilter()

Method Summary

void	addBinaryBodyContentType(java.lang.String contentType) Adds a content type to the list of content types that binary body documents will be filtered upon.
void	addDocumentField(DocumentField field, long optionID) Adds a document field option to the list of options that will be filtered upon
void	addDocumentState(DocumentState state) Add a document state to the list of document states that will be filtered upon.
void	addDocumentType(DocumentType type) Sets the document type to filter results selected by the result filter.
void	addLanguage(java.lang.String language) Add a language to the list of languages that will be filtered upon.
static DocumentResultFilter	createAllStatesFilter()
static DocumentResultFilter	createDefaultFilter() Creates a default document ResultFilter: no filtering with results sorted on the document's creation date in descending order.
void	deleteDocumentState(DocumentState state) Deletes a document state from the list of document states that will be filtered upon.
void	deleteDocumentType(DocumentType type) Add a document type to the list of document states that will be filtered upon.
void	deleteLanguage(java.lang.String language) Deletes a language from the list of languages that will be filtered upon.
java.lang.String	getBinaryBodyContentType(int index) Returns the binary body content type at the specified index.
int	getBinaryBodyContentTypeCount() Returns the count of the content types that will be used to filter binary documents
int	getBinaryBodyMode() Returns the mode that will be used to select results if binary body content types have been specified.
DocumentField	getDocumentField(int index) Returns the document field at the specified index in the list of document fields to be filtered on.
int	getDocumentFieldCount()
int	getDocumentFieldMode() Returns the mode that will be used to select results if multiple document field values have been specified.
java.lang.Object	getDocumentFieldValue(int index) Returns the optionID(s) at the specified index in the list of DocumentFields to be filtered on.
int	getDocumentStateCount() Returns the number of document states that results will be filtered on.
java.util.Iterator<DocumentState>	getDocumentStates() Returns the list of document states to filter results selected by the result filter.
java.util.Iterator<DocumentType>	getDocumentTypes() Returns the list of document types to filter results selected by the result filter.
int	getDocumentTypesCount() Returns the number of document types that results will be filtered on.
java.util.Date	getExpirationDateRangeMax() Returns a date that represents the upper boundry for documents to be selected by the result filter.
java.util.Date	getExpirationDateRangeMin() Returns a date that represents the lower boundry for documents to be selected by the result filter.
java.util.List<java.lang.String>	getLanguages() Returns the list of languages to filter results selected by the result filter.
DocumentField	getSortDocumentField() Returns the document field that will be sorted on.
boolean	isExcludeOwnerInUserFilter() Returns true if the document owner should be excluded when filtering by user id.
boolean	isIncludeAuthorsInUserFilter() Returns true if users who have been added as authors to a document should be included when filtering by user.
boolean	isIncludeNonRecommendedDocuments() Returns whether the result to be selected by the result filter should include documents with a recommended attribute set to false.
boolean	isIncludeRecommendedDocuments() Returns whether the result to be selected by the result filter should include documents with a recommended attribute set to true.
boolean	isIncludeReviewersInUserFilter() Returns true if users who have been added as reviewers to a document should be included when filtering by user.
boolean	isIncludeUnSearchableDocuments() Returns whether the result to be selected by the result filter should include documents with a searchable attribute set to false.
boolean	isOnlyIncludeCollaborativeDocuments() Returns true to only include collaborative documents (documents having textual bodies instead of binary bodies) in the list of document to filter upon.
boolean	isRestrictToLatestVersion() Returns true if only the latest document version will be tested when filtering on document state.
void	setBinaryBodyMode(int binaryBodyMode) Sets the mode that will be used to select results if binary body content types have been specified.
void	setDocumentFieldMode(int documentFieldMode) Sets the mode that will be used to select results if multiple document field values have been specified.
void	setExcludeOwnerInUserFilter(boolean excludeOwner) Sets whether the document owner should be excluded when filtering by user id.
void	setExpirationDateRangeMax(java.util.Date expirationDateRangeMax) Sets a date that represents the upper boundry for documents to be selected by the result filter.
void	setExpirationDateRangeMin(java.util.Date expirationDateRangeMin) Sets a date that represents the lower boundry for documents to be selected by the result filter.
void	setIncludeAuthorsInUserFilter(boolean includeAuthorsInUserFilter) Sets whether users who have been added as authors to a document should be included when filtering by user.
void	setIncludeNonRecommendedDocuments(boolean include) Sets whether the result to be selected by the result filter should include documents with a recommended attribute set to false.
void	setIncludeRecommendedDocuments(boolean include) Sets whether the result to be selected by the result filter should include documents with a recommended attribute set to true.
void	setIncludeReviewersInUserFilter(boolean includeReviewersInUserFilter) Sets whether users who have been added as reviewers to a document should be included when filtering by user.
void	setIncludeUnSearchableDocuments(boolean include) Sets whether the result to be selected by the result filter should include documents with a searchable attribute set to false.
void	setOnlyIncludeCollaborativeDocuments(boolean onlyIncludeCollaborativeDocuments) Set to true to only include collaborative documents (documents having textual bodies instead of binary bodies) in the list of document to filter upon.
void	setRestrictToLatestVersion(boolean restrictToLatestVersion) By default, all versions of a document will be tested when filtering on document state.
void	setSortDocumentField(DocumentField field) Sets the document field to sort on.

Methods inherited from class com.jivesoftware.community.ResultFilter

addProperty, addProperty, addTag, createDefaultContentFilter, createDefaultRecursiveContentFilter, getCreationDateRangeMax, getCreationDateRangeMin, getModificationDateRangeMax, getModificationDateRangeMin, getNumResults, getPropertyCount, getPropertyMatchType, getPropertyMode, getPropertyName, getPropertyValue, getPropertyValueString, getSortField, getSortOrder, getSortPropertyName, getStartIndex, getTags, getUserID, isAllTagsRequired, isPerformDistinctCount, isRecursive, setAllTagsRequired, setCreationDateRangeMax, setCreationDateRangeMin, setModificationDateRangeMax, setModificationDateRangeMin, setNumResults, setPerformDistinctCount, setPropertyMode, setRecursive, setSortField, setSortOrder, setSortPropertyName, setStartIndex, setTags, setUserID

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NOT_MODE

public static final int NOT_MODE

See Also:

Constant Field Values

Constructor Detail

DocumentResultFilter

public DocumentResultFilter()

Method Detail

createDefaultFilter

public static DocumentResultFilter createDefaultFilter()

Creates a default document ResultFilter: no filtering with results sorted on the document's creation date in descending order.

createAllStatesFilter

public static DocumentResultFilter createAllStatesFilter()

getExpirationDateRangeMin

public java.util.Date getExpirationDateRangeMin()

Returns a date that represents the lower boundry for documents to be selected by the result filter. If this value is not set it will return null and the results filter will return only documents that have not yet expired.

Returns:

a date representing the lower value of the expiration date to be selected.

setExpirationDateRangeMin

public void setExpirationDateRangeMin(java.util.Date expirationDateRangeMin)

Sets a date that represents the lower boundry for documents to be selected by the result filter. If this value is not set the results filter will return only documents that have not yet expired.

Setting a date range for a ResultFilter is a potential performance bottleneck. For example, if the argument for the date range is "new Date()" then the corresponding database query will map to an accuracy of a particular millisecond in time. This means that the results can't be cached. A better solution is to round dates to the nearest minute, hour, etc (whatever accuracy you need).

Parameters:

expirationDateRangeMin - a date representing the highest value of the expiration date range to be selected.

getExpirationDateRangeMax

public java.util.Date getExpirationDateRangeMax()

Returns a date that represents the upper boundry for documents to be selected by the result filter. If this value is not set it will return null and the results filter will be unbounded for the latest expiration date selected.

Returns:

a date representing the highest value of the expiration date to be selected.

setExpirationDateRangeMax

public void setExpirationDateRangeMax(java.util.Date expirationDateRangeMax)

Sets a date that represents the upper boundry for documents to be selected by the result filter. If this value is not set the results filter will be unbounded for the latest expiration date selected.

Setting a date range for a ResultFilter is a potential performance bottleneck. For example, if the argument for the date range is "new Date()" then the corresponding database query will map to an accuracy of a particular millisecond in time. This means that the results can't be cached. A better solution is to round dates to the nearest minute, hour, etc (whatever accuracy you need).

Parameters:

expirationDateRangeMax - a date representing the highest value of the expiration date range to be selected.

isIncludeUnSearchableDocuments

public boolean isIncludeUnSearchableDocuments()

Returns whether the result to be selected by the result filter should include documents with a searchable attribute set to false. The default value is true, or to include unsearchable documents.

Returns:

whether the result to be selected by the result filter should include searchable documents or not.

setIncludeUnSearchableDocuments

public void setIncludeUnSearchableDocuments(boolean include)

Sets whether the result to be selected by the result filter should include documents with a searchable attribute set to false. The default value is true, or to include unsearchable documents.

Parameters:

include - true to include searchable documents, false otherwise.

isIncludeRecommendedDocuments

public boolean isIncludeRecommendedDocuments()

Returns whether the result to be selected by the result filter should include documents with a recommended attribute set to true. The default value is true, or to include recommended documents.

Returns:

whether the result to be selected by the result filter should include recommended documents or not.

setIncludeRecommendedDocuments

public void setIncludeRecommendedDocuments(boolean include)

Sets whether the result to be selected by the result filter should include documents with a recommended attribute set to true. The default value is true, or to include recommended documents.

Parameters:

include - true to include recommended documents, false otherwise.

isIncludeNonRecommendedDocuments

public boolean isIncludeNonRecommendedDocuments()

Returns whether the result to be selected by the result filter should include documents with a recommended attribute set to false. The default value is true, or to include unrecommended documents.

Returns:

whether the result to be selected by the result filter should include unrecommended documents or not.

setIncludeNonRecommendedDocuments

public void setIncludeNonRecommendedDocuments(boolean include)

Sets whether the result to be selected by the result filter should include documents with a recommended attribute set to false. The default value is true, or to include unrecommended documents.

Parameters:

include - true to include unrecommended documents, false otherwise.

getDocumentTypesCount

public int getDocumentTypesCount()

Returns the number of document types that results will be filtered on.

Returns:

the number of document types that results will be filtered on.

getDocumentTypes

public java.util.Iterator<DocumentType> getDocumentTypes()

Returns the list of document types to filter results selected by the result filter. If no document types were specified filtering will include all document types.

Returns:

the list of document types to filter results selected by the result filter.

addDocumentType

public void addDocumentType(DocumentType type)

Sets the document type to filter results selected by the result filter. If this value is not set the results filter will not be filtered to any specific document type.

Parameters:

type - the document type to filter results selected by the result filter.

deleteDocumentType

public void deleteDocumentType(DocumentType type)

Add a document type to the list of document states that will be filtered upon.

Parameters:

type - a document type

getLanguages

public java.util.List<java.lang.String> getLanguages()

Returns the list of languages to filter results selected by the result filter. If no languages were specified filtering will not occur based upon languages.

Returns:

the list of languages to filter results selected by the result filter.

addLanguage

public void addLanguage(java.lang.String language)

Add a language to the list of languages that will be filtered upon.

Parameters:

language - an ISO-639 language code.

deleteLanguage

public void deleteLanguage(java.lang.String language)

Deletes a language from the list of languages that will be filtered upon.

Parameters:

language - an ISO-639 language code.

isIncludeAuthorsInUserFilter

public boolean isIncludeAuthorsInUserFilter()

Returns true if users who have been added as authors to a document should be included when filtering by user.

Returns:

true if users who have been added as authors to a document should be included when filtering by user.

setIncludeAuthorsInUserFilter

public void setIncludeAuthorsInUserFilter(boolean includeAuthorsInUserFilter)

Sets whether users who have been added as authors to a document should be included when filtering by user.

Parameters:

includeAuthorsInUserFilter - true when users who have been added as authors to a document should be included when filtering by user.

isIncludeReviewersInUserFilter

public boolean isIncludeReviewersInUserFilter()

Returns true if users who have been added as reviewers to a document should be included when filtering by user.

Returns:

true if users who have been added as reviewers to a document should be included when filtering by user.

setIncludeReviewersInUserFilter

public void setIncludeReviewersInUserFilter(boolean includeReviewersInUserFilter)

Sets whether users who have been added as reviewers to a document should be included when filtering by user.

Parameters:

includeReviewersInUserFilter - true when users who have been added as reviewers to a document should be included when filtering by user.

getDocumentStateCount

public int getDocumentStateCount()

Returns the number of document states that results will be filtered on.

Returns:

the number of document states that results will be filtered on.

getDocumentStates

public java.util.Iterator<DocumentState> getDocumentStates()

Returns the list of document states to filter results selected by the result filter. If no document states were specified filtering will only include documents with the state of DocumentState.PUBLISHED.

Returns:

the list of document states to filter results selected by the result filter.

addDocumentState

public void addDocumentState(DocumentState state)

Add a document state to the list of document states that will be filtered upon.

Parameters:

state - a document state

deleteDocumentState

public void deleteDocumentState(DocumentState state)

Deletes a document state from the list of document states that will be filtered upon.

Parameters:

state - a document state to remove

getDocumentFieldMode

public int getDocumentFieldMode()

Returns the mode that will be used to select results if multiple document field values have been specified. By default the mode is ResultFilter.AND_MODE which specifies that all document field values must match for the object to be selected. ResultFilter.OR_MODE is useful if you want objects to be returned if any of the document field values match.

Returns:

the mode that will be used to select results if multiple document field values have been specified.

setDocumentFieldMode

public void setDocumentFieldMode(int documentFieldMode)

Sets the mode that will be used to select results if multiple document field values have been specified. ResultFilter.AND_MODE (the default) specifies that all document field values must match for the object to be selected. ResultFilter.OR_MODE is useful if you want objects to be returned if any of the document field values match.

Parameters:

documentFieldMode - the mode that will be used to select results if multiple document field values have been specified.

getDocumentFieldCount

public int getDocumentFieldCount()

getDocumentField

public DocumentField getDocumentField(int index)

Returns the document field at the specified index in the list of document fields to be filtered on. If the index is invalid, null will be returned.

Returns:

the document field at the specified index in the document field filter list.

getDocumentFieldValue

public java.lang.Object getDocumentFieldValue(int index)

Returns the optionID(s) at the specified index in the list of DocumentFields to be filtered on. If the index is invalid, null will be returned. The returned object will either be a Long or a list of Long values.

Returns:

the optionID at the specified index in the document field filter list.

addDocumentField

public void addDocumentField(DocumentField field,
                             long optionID)

Adds a document field option to the list of options that will be filtered upon

Parameters:

field - a document field with a DocumentFieldType.DataType.LIST_SINGLE or DocumentFieldType.DataType.LIST_MULTI data type

optionID - an option from the field

getSortDocumentField

public DocumentField getSortDocumentField()

Returns the document field that will be sorted on. Returns null if sorting will not be done on a document field.

Returns:

the document field that will be sorted on.

setSortDocumentField

public void setSortDocumentField(DocumentField field)

Sets the document field to sort on. You must also call the setSortField(int) method with JiveConstants.DOCUMENT_FIELD as an argument. Attempting to sort on a document field that does not have the filterable attribute set to true will result in a IllegalArgumentException being thrown.

Parameters:

field - the document field to sort on.

Throws:

java.lang.IllegalArgumentException - if the document field is unfilterable

isOnlyIncludeCollaborativeDocuments

public boolean isOnlyIncludeCollaborativeDocuments()

Returns true to only include collaborative documents (documents having textual bodies instead of binary bodies) in the list of document to filter upon. Default is false.

Returns:

true to only include collaborative documents, false to include both text and binary body documents in the filtered results.

setOnlyIncludeCollaborativeDocuments

public void setOnlyIncludeCollaborativeDocuments(boolean onlyIncludeCollaborativeDocuments)

Set to true to only include collaborative documents (documents having textual bodies instead of binary bodies) in the list of document to filter upon. Default is false.

Parameters:

onlyIncludeCollaborativeDocuments - true to only include textual documents in the filtered results, false to include both text and binary body documents in the filtered results.

getBinaryBodyMode

public int getBinaryBodyMode()

Returns the mode that will be used to select results if binary body content types have been specified. By default the mode is ResultFilter.OR_MODE which specifies that any specified content type must match for the object to be selected. NOT_MODE is useful if you want objects to be returned if none of the specified content types match for the object to be selected.

Returns:

the mode that will be used to select results if binary body content types have been specified.

setBinaryBodyMode

public void setBinaryBodyMode(int binaryBodyMode)

Sets the mode that will be used to select results if binary body content types have been specified. ResultFilter.OR_MODE (the default) specifies that any specified content type must match for the object to be selected. NOT_MODE is useful if you want objects to be returned if none of the specified content types match for the object to be selected

Parameters:

binaryBodyMode - the mode that will be used to select results if binary body content types have been specified.

getBinaryBodyContentTypeCount

public int getBinaryBodyContentTypeCount()

Returns the count of the content types that will be used to filter binary documents

Returns:

the count of the content types that will be used to filter binary documents

getBinaryBodyContentType

public java.lang.String getBinaryBodyContentType(int index)

Returns the binary body content type at the specified index. If the index is invalid, null will be returned.

Parameters:

index - the index

Returns:

the binary body content type at the specified index

addBinaryBodyContentType

public void addBinaryBodyContentType(java.lang.String contentType)

Adds a content type to the list of content types that binary body documents will be filtered upon. Adding a binary body content type to the result filter will result in only documents with binary bodies being filtered - normal textual documents will not be included in the results. This may conflict with the isOnlyIncludeCollaborativeDocuments() setting, in which case the results are undefined.

Adding multiple content types results in 'OR' type filtering since documents cannot have multiple content types.

Note that wildcards (*) are allowed such that adding a content type such as image/* will include all documents with an image based binary body being included in the filtered results.

Parameters:

contentType - the binary body content type to add to the filter.

isRestrictToLatestVersion

public boolean isRestrictToLatestVersion()

Returns true if only the latest document version will be tested when filtering on document state.

Returns:

true if only the latest document version will be tested when filtering on document state.

setRestrictToLatestVersion

public void setRestrictToLatestVersion(boolean restrictToLatestVersion)

By default, all versions of a document will be tested when filtering on document state. Set to true to restrict this test to only the lates document version.

Parameters:

restrictToLatestVersion - set true to restrict this test to only the lates document version.

isExcludeOwnerInUserFilter

public boolean isExcludeOwnerInUserFilter()

Returns true if the document owner should be excluded when filtering by user id.

Returns:

true if the document owner should be excluded when filtering by user id.

setExcludeOwnerInUserFilter

public void setExcludeOwnerInUserFilter(boolean excludeOwner)

Sets whether the document owner should be excluded when filtering by user id.

Parameters:

excludeOwner - true when the document owner should be excluded when filtering by user id.

Throws:

java.lang.IllegalStateException - if this filter is not set to include authors or reviewers when filtering by user id.