net.sf.gsaapi
Class GSAQuery

java.lang.Object
  net.sf.gsaapi.GSAQuery

public class GSAQuery

extends java.lang.Object

Encapsulates the query parameters to be sent to the GSA. A typical use of this class would be:

   ...
   GSAQuery query = new GSAQuery();
   GSAQueryTerm term = new GSAQuery.GSAQueryTerm("instrumental music");
   term.setInTitle(new String[]{"music"}); // search for music in page title
   term.setIncludeFileType(new String[]{"pdf","html"}); // restrict to pdf and html file types
   query.setQueryTerm(term);
   query.setCollections(sites); // set the collection ofadmin-configured sites to restrict search to
   ...
 

Author:

Amol S Deshmukh adeshmuk .at inxight .dot com

See Also:

GSAClient

Nested Class Summary

static class

GSAQuery.GSAQueryTerm This class is required because the GSA query term supports a "special term" syntax.

Field Summary

static int	MAX_RESULTS the absolute maximum number of results that a query can generate.
static int	MAX_RESULTS_PER_QUERY The maximum number of results to be fetched in one invokation of a query.

Constructor Summary

GSAQuery()
create an instance of GSAQuery.

Method Summary

java.lang.String	getQueryString() This method is mainly to facilicate automated testing.
java.lang.String	getValue() return the HTTP GET query string.
void	setAccess(Access access) restrict results to public or secure (or do not restrict) based on the value of the Access parameter.
void	setAndQueryTerms(java.lang.String[] andTerms) restrict search to documents containing all of the specified terms.
void	setExactPhraseQueryTerm(java.lang.String phrase) search for the documents containing the exact specified phrase.
void	setFetchMetaFields(java.lang.String[] fields) Fetch specified META tags if they exist in the document.
void	setFilter(Filter filter) Set the filter char code that indicates type of filtering to be performed.
void	setFrontend(java.lang.String frontend) A string representing any valid frontend.
void	setInputEncoding(java.lang.String inputEncoding) Set input encoding (advanced use only)
void	setLanguage(java.lang.String language) Restrict search to pages in specified languages only.
void	setMaxResults(int maxResults) Restrict search results to these many at most.
void	setNumKeyMatches(byte keyMatches) Number of keymatches in a document (max value accepted by GSA is 5).
void	setOrQueryTerms(java.lang.String[] orTerms) search documents containing any or all of specified terms.
void	setOutputEncoding(java.lang.String outputEncoding) Set output encoding (advanced use only)
void	setOutputFormat(OutputFormat of)
void	setPartialMetaFields(java.util.Properties partialFields) Calls setPartialMetaFields(Properties, boolean) with the boolean argument set to true.
void	setPartialMetaFields(java.util.Properties partialFields, boolean orIfTrueAndIfFalse) Set the meta fields based filtering criteria.
void	setProxycustom(java.lang.String proxycustom) sets the proxycustom url param.
void	setProxyReload(boolean force) Setting this to true forces reloading of the proxystylesheet by the GSA server.
void	setProxystylesheet(java.lang.String proxystylesheet) set the value for proxystylesheet.
void	setQueryTerm(GSAQuery.GSAQueryTerm queryTerm)
void	setRequiredMetaFields(java.util.Properties requiredFields) Calls setRequiredMetaFields(Properties, boolean) with the boolean argument set to true.
void	setRequiredMetaFields(java.util.Properties requiredFields, boolean orIfTrueAndIfFalse) Set the meta fields based filtering criteria.
void	setScrollAhead(int n) scroll ahead to display (n+1)th result as the first result.
void	setSearchScope(SearchScope searchScope) Indicate part of page to which the search is to be restricted.
void	setSiteCollections(java.lang.String[] siteCollections) Restrict search to exclude documents from specified "siteCollections".
void	setSortByDate(boolean asc, char mode) sort by date (default sorted by "relevance") and in the specified sort-direction and mode If this method is invoked, the returned results also contain a custom field named "date" with the date value specified in YYYY-MM-DD formatted string.
void	unsetSortByDate() This method removes any sort-value set by previous calls to setSortByDate.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_RESULTS

public static final int MAX_RESULTS

the absolute maximum number of results that a query can generate. Thus, setStart+setMaxResults can't exceed this value.

See Also:

Constant Field Values

MAX_RESULTS_PER_QUERY

public static final int MAX_RESULTS_PER_QUERY

The maximum number of results to be fetched in one invokation of a query. This is the upperbound for the call to setMaxResults(int).

See Also:

Constant Field Values

Constructor Detail

GSAQuery

public GSAQuery()

create an instance of GSAQuery.

Method Detail

setSiteCollections

public void setSiteCollections(java.lang.String[] siteCollections)

Restrict search to exclude documents from specified "siteCollections". A siteCollection is a set of domains that is configured by the GSA admin.
For exampl, a particular search site may have a collection named "support" for all domains served by the Support department and another named "engineering" for all domains served by the Engineering department.
Note: siteCollection is not the same as an internet domain name - generally a siteCollection is mapped to a set of domain names.

Parameters:

siteCollections -

setFrontend

public void setFrontend(java.lang.String frontend)

A string representing any valid frontend.

Parameters:

frontend -

setOutputFormat

public void setOutputFormat(OutputFormat of)

Parameters:

of - The OutputFormat enum value

See Also:

OutputFormat

setMaxResults

public void setMaxResults(int maxResults)

Restrict search results to these many at most.

Parameters:

maxResults - maximum results desired. Large values will be limited to MAX_RESULTS

setNumKeyMatches

public void setNumKeyMatches(byte keyMatches)

Number of keymatches in a document (max value accepted by GSA is 5).

Parameters:

keyMatches - number of keyMatches desired

setSearchScope

public void setSearchScope(SearchScope searchScope)

Indicate part of page to which the search is to be restricted.

Parameters:

searchScope - A SearchScope enum value.

setFilter

public void setFilter(Filter filter)

Set the filter char code that indicates type of filtering to be performed.

Parameters:

filter - A Filter enum value

setQueryTerm

public void setQueryTerm(GSAQuery.GSAQueryTerm queryTerm)

Parameters:

queryTerm - The GSAQuery.GSAQueryTerm instance encapsulating the query string.

setOrQueryTerms

public void setOrQueryTerms(java.lang.String[] orTerms)

search documents containing any or all of specified terms.

Parameters:

orTerms - Terms that will be used to match the results documents. Documents matching any of the terms in the String array will be returned. Note that the terms will be further tokenized on spaces.

 String[] str1 = new String[] { "this", "that" };
 
 String[] str2 = new String[] { "this that" };
 

Using either of the above String arrays as an argument will yield same results.

setAndQueryTerms

public void setAndQueryTerms(java.lang.String[] andTerms)

restrict search to documents containing all of the specified terms.

Parameters:

andTerms - Terms that will be used to match the results documents. Only documents matching all of the terms in the String array will be returned. Note that the terms will be further tokenized on spaces.

 String[] str1 = new String[] { "this", "that" };
 
 String[] str2 = new String[] { "this that" };
 

Using either of the above String arrays as an argument will yield same results.

setExactPhraseQueryTerm

public void setExactPhraseQueryTerm(java.lang.String phrase)

search for the documents containing the exact specified phrase.

Parameters:

phrase - The exact phrase to search for.

setInputEncoding

public void setInputEncoding(java.lang.String inputEncoding)

Set input encoding (advanced use only)

Parameters:

inputEncoding - The input encoding.

setOutputEncoding

public void setOutputEncoding(java.lang.String outputEncoding)

Set output encoding (advanced use only)

Parameters:

outputEncoding - The output encoding.

setLanguage

public void setLanguage(java.lang.String language)

Restrict search to pages in specified languages only. For example, "lang_en" for english. For details refer to the XML protocol reference.

Parameters:

language - The language.

setFetchMetaFields

public void setFetchMetaFields(java.lang.String[] fields)

Fetch specified META tags if they exist in the document. (mainly useful for html documents).

Parameters:

fields - The meta fields associated with a result to fetch.

setRequiredMetaFields

public void setRequiredMetaFields(java.util.Properties requiredFields)

Calls setRequiredMetaFields(Properties, boolean) with the boolean argument set to true.

Parameters:

requiredFields - The Properties object encapsulating the required field names and values.

setRequiredMetaFields

public void setRequiredMetaFields(java.util.Properties requiredFields,
                                  boolean orIfTrueAndIfFalse)

Set the meta fields based filtering criteria. The argument is a Properties object containing key-value pairs of the form <meta-field-name>, <meta-field-value> The specified value is used to perform an exact match on the documents meta field.

   Note: The name and value strings must be url encoded.
 

For further details refer to: http://code.google.com/gsa_apis/xml_reference.html#request_meta_filter

Parameters:

requiredFields - The Properties instance specifying the required fields filter. All keys and values in the properties instance must be url encoded.

orIfTrueAndIfFalse - If true, the required field constraints are ORed -- ie. results containing any of the required fields are retrieved. If false, the required field contraints are ANDed ie. only results containing all the results are returned.

setPartialMetaFields

public void setPartialMetaFields(java.util.Properties partialFields)

Calls setPartialMetaFields(Properties, boolean) with the boolean argument set to true.

Parameters:

partialFields -

setPartialMetaFields

public void setPartialMetaFields(java.util.Properties partialFields,
                                 boolean orIfTrueAndIfFalse)

Set the meta fields based filtering criteria. The argument is a Properties object containing key-value pairs of the form <meta-field-name>, <meta-field-value>
The specified value is used to perform a subphrase match on the documents meta field. For further details refer to: http://code.google.com/gsa_apis/xml_reference.html#request_meta_filter

Parameters:

partialFields - The Properties instance specifying the partial fields filter.

orIfTrueAndIfFalse - If true, the required field constraints are ORed -- ie. results containing any of the required fields are retrieved. If false, the required field contraints are ANDed ie. only results containing all the results are returned.

setSortByDate

public void setSortByDate(boolean asc,
                          char mode)

sort by date (default sorted by "relevance") and in the specified sort-direction and mode If this method is invoked, the returned results also contain a custom field named "date" with the date value specified in YYYY-MM-DD formatted string. This value can be retrieved from the GSAResult object using the

Parameters:

asc - true if desired sort-direction is ascending. false otherwise.

mode - mode can be one of 'S' 'R' 'L' to mean "Sort relevant results", "Sort all results", "Dont sort, fetch date for each result " respectively.

unsetSortByDate

public void unsetSortByDate()

This method removes any sort-value set by previous calls to setSortByDate.

setScrollAhead

public void setScrollAhead(int n)

scroll ahead to display (n+1)th result as the first result. Useful for paginating through the results.

Parameters:

n - the starting index (0-based). ie. The (n+1)th result will be the first result to be displayed.

setAccess

public void setAccess(Access access)

restrict results to public or secure (or do not restrict) based on the value of the Access parameter.

Parameters:

access - The Access enum value.

See Also:

Access

setProxycustom

public void setProxycustom(java.lang.String proxycustom)

sets the proxycustom url param.

Parameters:

proxycustom - proxycustom string value.

setProxystylesheet

public void setProxystylesheet(java.lang.String proxystylesheet)

set the value for proxystylesheet. NOTE: It is not advisable to set this param if you intend to use the XML parsing capabilities of this API.

Parameters:

proxystylesheet - proxystylesheet String value.

setProxyReload

public void setProxyReload(boolean force)

Setting this to true forces reloading of the proxystylesheet by the GSA server. By default, GSA refreshes the stylesheet every 15 mins or so. (refer to documentation of your target GSA to determine the default proxystylsheet reload time).

Parameters:

force - true forces reloading the proxystylesheet for the results of this search.

getValue

public java.lang.String getValue()

return the HTTP GET query string.

Returns:

returns the complete query string generated as a result of all current options set in this instance of GSAQuery class.

getQueryString

public java.lang.String getQueryString()

This method is mainly to facilicate automated testing. Should not be required except to test the query string built internally.

Returns:

returns the query string generated as a result of all current options set in the GSAQueryTerm instance associated with this GSAQuery instance.