com.marklogic.client.io

Class SearchHandle

java.lang.Object

com.marklogic.client.impl.HandleImplementation<R,W>

com.marklogic.client.io.BaseHandle<InputStream,OperationNotSupported>

com.marklogic.client.io.SearchHandle

All Implemented Interfaces:

ContentDescriptor, AbstractReadHandle, SearchReadHandle, SearchResults

public class SearchHandle
extends BaseHandle<InputStream,OperationNotSupported>
implements SearchReadHandle, SearchResults

A SearchHandle represents a set of search results returned by the server.

The precise nature of the results returned depends on the query options used for the search and on the configuration of this handle.

Snippets, in particular, are returned in various ways. In the default case, snippets are returned as Java objects. For custom or raw snippets, DOM documents are returned. The forceDOM flag can be set to cause the handle to always return DOM documents, even in the default case.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SearchHandle.Report Represents a report message.
static class	SearchHandle.Warning Represents a warning.

Field Summary

Fields inherited from interface com.marklogic.client.document.ContentDescriptor

UNKNOWN_LENGTH

Constructor Summary

Constructors

Constructor and Description
SearchHandle()

Method Summary

Modifier and Type	Method and Description
<T extends XMLReadHandle> T	getConstraint(String name, T handle) Returns the named constraint used in the search (if requested).
<T extends XMLReadHandle> Iterator<T>	getConstraintIterator(T handle) Returns an iterator over the constraints used in the search (if requested).
String[]	getConstraintNames() Returns the array of constraint names used in the search (if requested).
String[]	getFacetNames() Returns a list of the facet names returned in this search.
FacetResult	getFacetResult(String name) Returns the named facet results.
FacetResult[]	getFacetResults() Returns an array of facet results for this search.
MatchDocumentSummary[]	getMatchResults() Returns an array of summaries for the matched documents.
SearchMetrics	getMetrics() Returns the metrics associated with this search.
int	getPageLength() Returns the page length for this search.
Document	getPlan() Returns the query plan associated with this search.
<T extends XMLReadHandle> T	getPlan(T handle) Returns the plan for the search (if requested).
<T extends XMLReadHandle> T	getQuery(T handle) Returns the cts:query used in the search (if requested).
QueryDefinition	getQueryCriteria() Returns the query definition used for the search represented by this handle.
SearchHandle.Report[]	getReports() Returns an array of any reports associated with this search.
String	getSnippetTransformType() Identifies whether results have default, raw document, customer, or no snippets.
long	getStart() Returns the start page for this search.
String[]	getStringQueries() Returns the list of string queries, if specified by the query options.
long	getTotalResults() Returns the total number of results in this search.
SearchHandle.Warning[]	getWarnings() Returns an array of any warnings associated with this search.
void	setForceDOM(boolean forceDOM) Deprecated.
void	setFormat(Format format) Sets the format associated with this handle.
void	setHandleRegistry(DatabaseClientFactory.HandleFactoryRegistry registry) Makes the handle registry for this database client available to this SearchHandle during processing of the search response.
void	setQueryCriteria(QueryDefinition querydef) Sets the query definition used in the search.
SearchHandle	withFormat(Format format) Fluent setter for the format associated with this handle.

Methods inherited from class com.marklogic.client.io.BaseHandle

getByteLength, getFormat, getMimetype, setByteLength, setMimetype

Methods inherited from class java.lang.Object

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

Constructor Detail

SearchHandle

public SearchHandle()

Method Detail

setFormat

public void setFormat(Format format)

Sets the format associated with this handle. This handle only supports XML.

Specified by:

setFormat in interface ContentDescriptor

Overrides:

setFormat in class BaseHandle<InputStream,OperationNotSupported>

Parameters:

format - The format, which must be Format.XML or an exception will be raised.

withFormat

public SearchHandle withFormat(Format format)

Fluent setter for the format associated with this handle. This handle only supports XML.

Parameters:

format - The format, which must be Format.XML or an exception will be raised.

Returns:

The SearchHandle instance on which this method was called.

setForceDOM

@Deprecated
public void setForceDOM(boolean forceDOM)

Deprecated.

In a previous release, set the force DOM flag. This setter now has no effect and will be removed in a future release.

Parameters:

forceDOM - The flag setting.

setQueryCriteria

public void setQueryCriteria(QueryDefinition querydef)

Sets the query definition used in the search.

Calling this method always deletes any cached search results.

Parameters:

querydef - The new QueryDefinition

getQueryCriteria

public QueryDefinition getQueryCriteria()

Returns the query definition used for the search represented by this handle.

Specified by:

getQueryCriteria in interface SearchResults

Returns:

The query definition.

setHandleRegistry

public final void setHandleRegistry(DatabaseClientFactory.HandleFactoryRegistry registry)

Makes the handle registry for this database client available to this SearchHandle during processing of the search response.

Parameters:

registry - the registry of IO representation classes for this database client

getTotalResults

public long getTotalResults()

Returns the total number of results in this search.

Specified by:

getTotalResults in interface SearchResults

Returns:

The number of results.

getStart

public long getStart()

Returns the start page for this search.

Specified by:

getStart in interface SearchResults

Returns:

The offset to the first result.

getPageLength

public int getPageLength()

Returns the page length for this search.

Specified by:

getPageLength in interface SearchResults

Returns:

The number of results in a page.

getSnippetTransformType

public String getSnippetTransformType()

Identifies whether results have default, raw document, customer, or no snippets.

Specified by:

getSnippetTransformType in interface SearchResults

Returns:

The type of snippets provided by results.

getStringQueries

public String[] getStringQueries()

Returns the list of string queries, if specified by the query options.

Specified by:

getStringQueries in interface SearchResults

Returns:

The string queries.

getQuery

public <T extends XMLReadHandle> T getQuery(T handle)

Description copied from interface: SearchResults

Returns the cts:query used in the search (if requested).

Specified by:

getQuery in interface SearchResults

Type Parameters:

T - the type of XMLReadHandle to return

Parameters:

handle - An XML handle for reading the query.

Returns:

The handle on the query.

getMetrics

public SearchMetrics getMetrics()

Returns the metrics associated with this search.

Specified by:

getMetrics in interface SearchResults

Returns:

The metrics.

getMatchResults

public MatchDocumentSummary[] getMatchResults()

Returns an array of summaries for the matched documents.

Specified by:

getMatchResults in interface SearchResults

Returns:

The summary array.

getFacetNames

public String[] getFacetNames()

Returns a list of the facet names returned in this search.

Specified by:

getFacetNames in interface SearchResults

Returns:

The array of names.

getFacetResult

public FacetResult getFacetResult(String name)

Returns the named facet results.

Specified by:

getFacetResult in interface SearchResults

Parameters:

name - The name of the facet.

Returns:

Returns the results for the named facet or null if no such named facet exists.

getFacetResults

public FacetResult[] getFacetResults()

Returns an array of facet results for this search.

Specified by:

getFacetResults in interface SearchResults

Returns:

The facets array.

getConstraintNames

public String[] getConstraintNames()

Description copied from interface: SearchResults

Returns the array of constraint names used in the search (if requested).

Specified by:

getConstraintNames in interface SearchResults

Returns:

The constraint names.

getConstraint

public <T extends XMLReadHandle> T getConstraint(String name,
                                                 T handle)

Description copied from interface: SearchResults

Returns the named constraint used in the search (if requested).

Specified by:

getConstraint in interface SearchResults

Type Parameters:

T - the type of XMLReadHandle to return

Parameters:

name - The constraint name.

handle - An XML handle for reading the constraint.

Returns:

The handle on the constraint.

getConstraintIterator

public <T extends XMLReadHandle> Iterator<T> getConstraintIterator(T handle)

Description copied from interface: SearchResults

Returns an iterator over the constraints used in the search (if requested).

Specified by:

getConstraintIterator in interface SearchResults

Type Parameters:

T - the type of XMLReadHandle's to return in the Iterator

Parameters:

handle - An XML handle for reading the constraints.

Returns:

An iterator that populates the handle with each constraint.

getPlan

public Document getPlan()

Returns the query plan associated with this search.

Query plans are highly variable.

Specified by:

getPlan in interface SearchResults

Returns:

the plan as a DOM Document

getPlan

public <T extends XMLReadHandle> T getPlan(T handle)

Description copied from interface: SearchResults

Returns the plan for the search (if requested).

Specified by:

getPlan in interface SearchResults

Type Parameters:

T - the type of XMLReadHandle to return

Parameters:

handle - An XML handle for reading the plan.

Returns:

The handle on the plan.

getWarnings

public SearchHandle.Warning[] getWarnings()

Returns an array of any warnings associated with this search.

Specified by:

getWarnings in interface SearchResults

Returns:

The warnings array.

getReports

public SearchHandle.Report[] getReports()

Returns an array of any reports associated with this search.

Specified by:

getReports in interface SearchResults

Returns:

The reports array.