com.iphrase.runtime.query
Class Query

java.lang.Object
  |
  +--com.iphrase.runtime.query.Query

public class Query
extends java.lang.Object

The Query class contains all details of a runtime request to a OneStep server.

Use this class for both initial (fresh) and followup queries. To create an initial query, call Connector.createQuery(). To create a followup query, call Connector.createQuery(String state), with the resolved query state from a previous ResultSet.getResolvedQueryState() call. See the note about query state below.

Then use the set* methods of the Query instance to set any relevant request properties such as query text, additional constraints, number of items per page, page number, etc. If any details are not set, they will fall back to the defaults configured in the server. If nothing is set, the engine's default Query will be answered and returned.

Call the Query instance execute() method to get the engine's response to the Query, a QueryResult instance. This result can then be rendered to the end-user.

There are two special cases to keep in mind.

  1. Setting any properties besides setText(java.lang.String), setTextRemoveTerm(com.iphrase.runtime.query.constraint.Mentions, java.lang.String), or setExpandDrillDownFeature(java.lang.String) will disable the server-side default query (SERVER_INIT_QUERY_CGI).
  2. Only the most recent call to setText(java.lang.String), setTextRemoveTerm(com.iphrase.runtime.query.constraint.Mentions, java.lang.String), or setExpandDrillDownFeature(java.lang.String) will take effect. All other properties are independent of this restriction.

Note that we serialize queries (resolved and otherwise) to CGI query-string format: a sequence of &-separated key=value pairs. This is very compact, and has the additional advantage of adhering to the OneStep CGI Specification - and therefore works as is when given directly to a OneStep server.

It is necessary to URL-encode both the key and the value in each pair to protect the format. We do so during serialization in toString() (and getState()), and expect this encoding during deserialization in construction and setState(java.lang.String), for which we URL-decode both the key and the value.

If the resolved query state is URL-decoded without a previous, corresponding URL-encode, information will be destroyed in subtle ways. The following rules must be obeyed:

Another way of putting this is as follows. If you count +1 for each URL-encode, and -1 for each URL-decode, the running total can never go negative - or information will be destroyed.


Constructor Summary
Query(Connector connector, java.lang.String state)
          This Query ctor is public only for Connector.createQuery().
Query(com.iphrase.www._2003._11.oneStep.encodedTypes.KeyValPair[] pairs)
          This Query ctor is public only for ResultSet.
 
Method Summary
 QueryResult execute()
          Submit this query to an iPhrase server.
 java.lang.String[] getAddColumnFeatures()
          Get the features that are requested as additional columns for the result table.
 int getAutoSummarizeHardLimit()
          Get the hard count limit for summarization.
 int getAutoSummarizeSoftLimit()
          Get the soft limit for summarization.
 java.lang.String getClientIp()
          Get the client IP address that will be sent with this query.
 Conjunction getConstraints()
          Get the constraints to be used when retrieving results.
 java.lang.String getCookie()
          Get the cookie string that will be sent with this query.
 java.lang.String getData(java.lang.String key)
          Get the data value corresponding to "data[key]", where [key] is replaced by its value, resulting from a previous call to setData(java.lang.String, java.lang.String).
 boolean getEnableAutoSummarize()
          Determine whether auto-summarization is enabled.
 boolean getEnableSearchWithin()
          Return whether or not this query will search within the current results.
 java.lang.String getExpandDrillDownFeature()
          Get the drillDown feature to expand (i.e.
 java.lang.String getGroupByFeature()
          Get the group-by (aka view-by) feature, or null if no group-by feature has been set.
 SortFeature getGroupBySortFeature()
          Get the sort feature by which results are sorted within group-by (aka view-by) groups.
 boolean getGroupBySortIsByTally()
          Determine whether group-by (aka view-by) grouped results are sorted by tally count or not (alphabetically is the default).
 java.lang.String getIdentifier()
          Gets the identifier feature.
 int getPageNumber()
          Get the 0-based page number to return in the query result.
 java.lang.Object getParam(java.lang.String key)
          Gets a query parameter by its name
 SortFeature getPrimarySortByFeature()
          Get the primary sort feature.
 java.lang.String getRefererUrl()
          Get the referer URL that will be sent with this query.
 int getRowsPerPage()
          Get the number of rows (results) per page.
 java.lang.String[] getSearchByFeatures()
          Get the features that this query will search.
 java.lang.String[] getSearchFeatures()
          Deprecated. call getSearchByFeatures instead
 SortFeature[] getSortByFeatures()
          Gets the array of SortFeature used to sort results.
 java.lang.String getState()
          Get the state string (serialization) of this query.
 java.lang.String[] getSummarizeByFeatures()
          Get the features used to summarize results.
 java.lang.String getText()
          Get the end-user's query text.
 java.lang.String[] getTextHistory()
          Get the user's query text search within history.
 java.lang.String getTextRemoveTerm(Mentions mentions)
          Get the term to be removed from the end-user's query text.
 int getTruncationCount()
          Get the truncation count.
 java.lang.String getTruncationFeature()
          Get the truncation feature.
 int getTruncationTrigger()
          Get the truncation trigger.
 java.lang.String getUserAgent()
          Get the user agent that will be sent with this query.
 java.lang.String getViewByFeature()
          Get the view-by (aka group-by) feature, or null if no view-by feature has been set.
 void logChange(java.lang.String command, java.lang.String attr1)
          Log a query change as command,attr1,attr2 where attr2 is blank.
 void logChange(java.lang.String command, java.lang.String attr1, java.lang.String attr2)
          Log a query change as command,attr1,attr2.
 void setAddColumnFeatures(java.util.List features)
          Set the features to be requested as additional columns for each row in the result table.
 void setAddColumnFeatures(java.lang.String[] features)
          Set the features to be requested as additional columns for each row in the result table.
 void setAutoSummarizeHardLimit(int limit)
          Set the hard count limit for summarization.
 void setAutoSummarizeSoftLimit(int limit)
          Set the soft limit for summarization.
 void setClientIp(java.lang.String clientIp)
          Set the client IP address that will be sent with this query.
 void setConstraints(Conjunction conjunction)
          Set the constraints to be used when retrieving results.
 void setCookie(java.lang.String cookie)
          Set the cookie string that will be sent with this query.
 void setData(java.lang.String key, java.lang.String value)
          Set an arbitrary data key=value pair that should wind up in the OneStep server logs as "data[key]=[value]", where [key] and [value] are replaced their respective String values and [key] is down-cased.
 void setEnableAutoSummarize(boolean enable)
          Enable or disable auto-summarize, which allows the engine to dynamically summarized based on the summarization limits.
 void setEnableSearchWithin(boolean enable)
          Enable or disable this query to search within the current results.
 void setExpandDrillDownFeature(java.lang.String feature)
          Set the drillDown feature to expand (i.e.
 void setGroupByFeature(java.lang.String feature)
          Set the group-by (aka view-by) feature, by which results are grouped (ordered) in the query result.
 void setGroupBySort(SortFeature sort, boolean isByTally)
          Set the sort parameters by which results are sorted within group-by (aka view-by) groups.
 void setIdentifier(java.lang.String identifier)
          Sets the identifier feature.
 void setLogClickThrough(int nrow, java.lang.String feature, java.lang.String href)
          Set the query to log click-through info before serving a redirect.
 void setPageNumber(int page)
          Set the 0-based page number to return in the query result.
 java.lang.Object setParam(java.lang.String key, java.lang.Object value)
          Maps the specified key to the specified value in the query parameters list
 void setPrimarySortByFeature(SortFeature sort)
          Set the requested feature and direction as the primary sort feature.
 void setRefererUrl(java.lang.String refererUrl)
          Set the referer URL that will be sent with this query.
 void setRowsPerPage(int rows)
          Set the number of rows (results) per page.
 void setSearchByFeatures(java.util.List features)
          Set the features that this query will search.
 void setSearchByFeatures(java.lang.String[] features)
          Set the features that this query will search.
 void setSearchFeatures(java.util.List features)
          Deprecated. call setSearchByFeatures instead
 void setSearchFeatures(java.lang.String[] features)
          Deprecated. call setSearchByFeatures instead
 void setSortByFeatures(SortFeature[] sortFeatures)
          Sets the array of features & directions used to sort results.
 void setState(java.lang.String state)
          Set multiple query properties with a query state string (serialization).
 void setSummarizeByFeatures(java.util.List features)
          Set the features used to summarize results.
 void setSummarizeByFeatures(java.lang.String[] features)
          Set the features used to summarize results.
 void setText(java.lang.String text)
          Set the end-user's query text.
 void setTextHistory(java.lang.String[] textHistory)
          Set the user's query text search within history.
 void setTextRemoveTerm(Mentions mentions, java.lang.String term)
          Set the term to be removed from the end-user's query text.
 void setTruncation(java.lang.String feature, int count)
          Set the truncation feature and count.
 void setTruncation(java.lang.String feature, int count, int trigger)
          Set truncation feature, count, and trigger.
 void setUserAgent(java.lang.String userAgent)
          Set the user agent that will be sent with this query.
 void setViewByFeature(java.lang.String feature)
          Set the view-by (aka group-by) feature, by which results are viewed (ordered) in the query result.
 java.lang.String toString()
          Get the state string (serialization) of this query.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Query

public Query(Connector connector,
             java.lang.String state)
      throws ArgumentError
This Query ctor is public only for Connector.createQuery().
Parameters:
connector - will be used to execute this query
state - initial state string (serialization) or null
Throws:
ArgumentError -  

Query

public Query(com.iphrase.www._2003._11.oneStep.encodedTypes.KeyValPair[] pairs)
      throws WebServiceError
This Query ctor is public only for ResultSet.
Parameters:
pairs - array of proxy class query property key/val pairs
Method Detail

setText

public void setText(java.lang.String text)
Set the end-user's query text.
Parameters:
text - String query text

getText

public java.lang.String getText()
Get the end-user's query text.
Returns:
String query text or null if no text is set

setTextHistory

public void setTextHistory(java.lang.String[] textHistory)
Set the user's query text search within history.
Parameters:
textHistory - array of String query text in historical order

getTextHistory

public java.lang.String[] getTextHistory()
Get the user's query text search within history.
Returns:
array of String query text in historical order

setExpandDrillDownFeature

public void setExpandDrillDownFeature(java.lang.String feature)
Set the drillDown feature to expand (i.e. for which to show all values).
Parameters:
feature - String feature id

getExpandDrillDownFeature

public java.lang.String getExpandDrillDownFeature()
Get the drillDown feature to expand (i.e. for which to show all values).
Returns:
String feature id or null if no feature id is set

setTextRemoveTerm

public void setTextRemoveTerm(Mentions mentions,
                              java.lang.String term)
                       throws ArgumentError
Set the term to be removed from the end-user's query text.
Parameters:
mentions - Mentions constraint from which the term is to be removed
term - String term to remove (not search for) in the constraint
Throws:
com.iphrase.exception.ArgumentError -  

getTextRemoveTerm

public java.lang.String getTextRemoveTerm(Mentions mentions)
                                   throws ArgumentError
Get the term to be removed from the end-user's query text.
Parameters:
mentions - Mentions constraint from which the term is to be removed
Returns:
String term to remove (not search for) in the constraint, or null
Throws:
com.iphrase.exception.ArgumentError -  

setEnableSearchWithin

public void setEnableSearchWithin(boolean enable)
Enable or disable this query to search within the current results.
Parameters:
enable - true if query will search within the current results, else false.

getEnableSearchWithin

public boolean getEnableSearchWithin()
Return whether or not this query will search within the current results.
Returns:
true if search within is enabled, else false

setSearchByFeatures

public void setSearchByFeatures(java.util.List features)
Set the features that this query will search. By default, all features are searched.
Parameters:
features - List of String search feature ids

setSearchFeatures

public void setSearchFeatures(java.util.List features)
Deprecated. call setSearchByFeatures instead


setSearchByFeatures

public void setSearchByFeatures(java.lang.String[] features)
Set the features that this query will search. By default, all features are searched.
Parameters:
features - array of String search feature ids, null or empty array to disable search-by-features (search all features)

setSearchFeatures

public void setSearchFeatures(java.lang.String[] features)
Deprecated. call setSearchByFeatures instead


getSearchByFeatures

public java.lang.String[] getSearchByFeatures()
Get the features that this query will search.
Returns:
array of String search feature ids, or empty array if search-by-features is disabled (all features will be searched)

getSearchFeatures

public java.lang.String[] getSearchFeatures()
Deprecated. call getSearchByFeatures instead


setRowsPerPage

public void setRowsPerPage(int rows)
Set the number of rows (results) per page. A row may correspond to more than one item if the result is summarized.
Parameters:
rows - int number of rows per page.

getRowsPerPage

public int getRowsPerPage()
Get the number of rows (results) per page. A row may correspond to more than one item if the result is summarized.
Returns:
int number of rows per page

setPageNumber

public void setPageNumber(int page)
Set the 0-based page number to return in the query result.
Parameters:
page - int starting at 0 for first page.

getPageNumber

public int getPageNumber()
Get the 0-based page number to return in the query result.
Returns:
int starting at 0 for first page.

setGroupByFeature

public void setGroupByFeature(java.lang.String feature)
Set the group-by (aka view-by) feature, by which results are grouped (ordered) in the query result. Items that have the same value for this feature are grouped together.
Parameters:
feature - String feature id to group by, null or "" to remove

getGroupByFeature

public java.lang.String getGroupByFeature()
Get the group-by (aka view-by) feature, or null if no group-by feature has been set.
Returns:
String feature id to group by, null if not set

setViewByFeature

public void setViewByFeature(java.lang.String feature)
Set the view-by (aka group-by) feature, by which results are viewed (ordered) in the query result. Items that have the same value for this feature are grouped together.
Parameters:
feature - String feature id to view by, null or "" to remove
See Also:
setGroupByFeature(java.lang.String)

getViewByFeature

public java.lang.String getViewByFeature()
Get the view-by (aka group-by) feature, or null if no view-by feature has been set.
Returns:
String feature id to view by, null if not set
See Also:
getGroupByFeature()

setSummarizeByFeatures

public void setSummarizeByFeatures(java.util.List features)
Set the features used to summarize results. If enableAutoSummarize is set for the query then the runtime engine will dynamically pick the appropriate level of summarization based on the summarize limits (@see setSummarizeLimits). Otherwise, summarization will be to the exact level specified here.
Parameters:
features - List of String feature ids

setSummarizeByFeatures

public void setSummarizeByFeatures(java.lang.String[] features)
Set the features used to summarize results. If enableAutoSummarize is set for the query then the runtime engine will dynamically pick the appropriate level of summarization based on the summarize limits (@see setSummarizeLimits). Otherwise, summarization will be to the exact level specified here.
Parameters:
features - array of String feature ids, empty to disable

getSummarizeByFeatures

public java.lang.String[] getSummarizeByFeatures()
Get the features used to summarize results.
Returns:
array of String feature ids, possibly empty

setEnableAutoSummarize

public void setEnableAutoSummarize(boolean enable)
Enable or disable auto-summarize, which allows the engine to dynamically summarized based on the summarization limits.
Parameters:
enable - if true, disable if false
See Also:
setSummarizeByFeatures(java.util.List)

getEnableAutoSummarize

public boolean getEnableAutoSummarize()
Determine whether auto-summarization is enabled.
Returns:
true if auto-summarization is enabled, else false

setAutoSummarizeSoftLimit

public void setAutoSummarizeSoftLimit(int limit)
Set the soft limit for summarization. This operation is currently unsupported.
Parameters:
limit - int summarization soft limit

getAutoSummarizeSoftLimit

public int getAutoSummarizeSoftLimit()
Get the soft limit for summarization. This operation is currently unsupported.
Returns:
int summarization soft limit

setAutoSummarizeHardLimit

public void setAutoSummarizeHardLimit(int limit)
Set the hard count limit for summarization. This operation is currently unsupported.
Parameters:
limit - int summarization hard limit

getAutoSummarizeHardLimit

public int getAutoSummarizeHardLimit()
Get the hard count limit for summarization. This operation is currently unsupported.
Returns:
int summarization hard limit

setAddColumnFeatures

public void setAddColumnFeatures(java.util.List features)
Set the features to be requested as additional columns for each row in the result table. This overwrites any previously requested additional columns.
Parameters:
features - List of String feature ids

setAddColumnFeatures

public void setAddColumnFeatures(java.lang.String[] features)
Set the features to be requested as additional columns for each row in the result table. This overwrites any previously requested additional columns.
Parameters:
features - array of String feature ids

getAddColumnFeatures

public java.lang.String[] getAddColumnFeatures()
Get the features that are requested as additional columns for the result table.
Returns:
array of String feature ids

setSortByFeatures

public void setSortByFeatures(SortFeature[] sortFeatures)
Sets the array of features & directions used to sort results. This operation is currently unsupported. Sorting accepts multiple features to resolve ties. The first feature is the primary sort, the second is secondary, etc.
Parameters:
sortFeatures - array of SortFeature

getSortByFeatures

public SortFeature[] getSortByFeatures()
Gets the array of SortFeature used to sort results. This operation is currently unsupported.
Returns:
array of SortFeature

setPrimarySortByFeature

public void setPrimarySortByFeature(SortFeature sort)
                             throws ArgumentError
Set the requested feature and direction as the primary sort feature. Other sort features are pushed down. This API retains two sortBy features (ie, if there are three, it discards the last one).

NOTE: if the specified primary sort feature has the same feature id as the current primary sort feature, then the specified primary sort feature direction is ignored, and the current primary sort feature direction is toggled from DESCENDING to ASCENDING (or vice-versa). To avoid this (regrettably bad) behavior, do something like this:

 // for some new id and direction...
 SortFeature cur = query.getPrimarySortByFeature();
 if (cur == null || !cur.getId().equals(id) || cur.getDirection() != direction) {
   query.setPrimarySortByFeature(new SortFeature(id, direction));
 }
 
Parameters:
sort - SortFeature instance
Throws:
com.iphrase.exception.ArgumentError -  

getPrimarySortByFeature

public SortFeature getPrimarySortByFeature()
                                    throws ArgumentError
Get the primary sort feature.
Returns:
SortFeature instance
Throws:
com.iphrase.exception.ArgumentError -  

setGroupBySort

public void setGroupBySort(SortFeature sort,
                           boolean isByTally)
Set the sort parameters by which results are sorted within group-by (aka view-by) groups.
Parameters:
sort - SortFeature by which results are sorted
isByTally - true if grouped results are sorted by tally count, else false (sorted alphabetically, the default)

getGroupBySortFeature

public SortFeature getGroupBySortFeature()
Get the sort feature by which results are sorted within group-by (aka view-by) groups.
Returns:
SortFeature by which results are sorted
See Also:
setGroupBySort(com.iphrase.runtime.query.SortFeature, boolean)

getGroupBySortIsByTally

public boolean getGroupBySortIsByTally()
Determine whether group-by (aka view-by) grouped results are sorted by tally count or not (alphabetically is the default).
Returns:
true if grouped results are sorted by tally count, else false (sorted alphabetically, the default)
See Also:
setGroupBySort(com.iphrase.runtime.query.SortFeature, boolean)

setTruncation

public void setTruncation(java.lang.String feature,
                          int count)
Set the truncation feature and count.
Parameters:
feature - String id of feature on which to do truncation
count - int number of truncated items (to show)

setTruncation

public void setTruncation(java.lang.String feature,
                          int count,
                          int trigger)
Set truncation feature, count, and trigger.
Parameters:
feature - String id of feature on which to do truncation
count - int number of truncated items (to show)
trigger - int total number of results necessary for truncation to trigger

getTruncationFeature

public java.lang.String getTruncationFeature()
Get the truncation feature.
Returns:
String truncation feature or null if truncation is not set
See Also:
setTruncation(java.lang.String, int)

getTruncationCount

public int getTruncationCount()
Get the truncation count.
Returns:
int truncation count or 0 if truncation is not set
See Also:
setTruncation(java.lang.String, int)

getTruncationTrigger

public int getTruncationTrigger()
Get the truncation trigger.
Returns:
int truncation trigger or 0 if truncation is not set
See Also:
setTruncation(java.lang.String, int)

setConstraints

public void setConstraints(Conjunction conjunction)
Set the constraints to be used when retrieving results.
Parameters:
conjunction - a Conjunction instance representing the "ANDs of ORs" of all constraints.

getConstraints

public Conjunction getConstraints()
Get the constraints to be used when retrieving results.
Returns:
Conjunction instance representing the "ANDs of ORs" of all constraints.

setClientIp

public void setClientIp(java.lang.String clientIp)
Set the client IP address that will be sent with this query.
Parameters:
clientIp - IP address String in dotted-quad format

getClientIp

public java.lang.String getClientIp()
Get the client IP address that will be sent with this query.
Returns:
IP address String in dotted-quad format, or null if there is no client IP address associated with this query

setCookie

public void setCookie(java.lang.String cookie)
Set the cookie string that will be sent with this query.
Parameters:
cookie - cookie String

getCookie

public java.lang.String getCookie()
Get the cookie string that will be sent with this query.
Returns:
cookie String, or null if there is no cookie associated with this query

setRefererUrl

public void setRefererUrl(java.lang.String refererUrl)
Set the referer URL that will be sent with this query.
Parameters:
refererUrl - referer URL String

getRefererUrl

public java.lang.String getRefererUrl()
Get the referer URL that will be sent with this query.
Returns:
referer URL String, or null if there is no referer URL associated with this query

setUserAgent

public void setUserAgent(java.lang.String userAgent)
Set the user agent that will be sent with this query.
Parameters:
userAgent - user agent String

getUserAgent

public java.lang.String getUserAgent()
Get the user agent that will be sent with this query.
Returns:
user agent String, or null if there is no user agent associated with this query

setData

public void setData(java.lang.String key,
                    java.lang.String value)
Set an arbitrary data key=value pair that should wind up in the OneStep server logs as "data[key]=[value]", where [key] and [value] are replaced their respective String values and [key] is down-cased.
Parameters:
key - String key, prefixed with "data", down-cased, and followed by "=[value]" in the OneStep server logs
value - String value, prefixed with "data[key]=" in the OneStep server logs

getData

public java.lang.String getData(java.lang.String key)
Get the data value corresponding to "data[key]", where [key] is replaced by its value, resulting from a previous call to setData(java.lang.String, java.lang.String).
Parameters:
key - String key, prefixed with "data", down-cased, and followed by "=[value]" in the OneStep server logs
Returns:
String value, prefixed with "data[key]=" in the OneStep server logs

setLogClickThrough

public void setLogClickThrough(int nrow,
                               java.lang.String feature,
                               java.lang.String href)
Set the query to log click-through info before serving a redirect.
Parameters:
nrow - int row number containing the link
feature - String feature id of the link
href - String target URL to which we will redirect

execute

public QueryResult execute()
                    throws WebServiceError
Submit this query to an iPhrase server.
Returns:
new QueryResult object.
Throws:
WebServiceError -  

toString

public java.lang.String toString()
Get the state string (serialization) of this query.
Overrides:
toString in class java.lang.Object
Returns:
query state String
See Also:
getState()

getParam

public java.lang.Object getParam(java.lang.String key)
Gets a query parameter by its name
Returns:
the value to which the specified key is mapped in this hashtable.

setParam

public java.lang.Object setParam(java.lang.String key,
                                 java.lang.Object value)
Maps the specified key to the specified value in the query parameters list
Returns:
previous value of the specified key in the query parameters list

getIdentifier

public java.lang.String getIdentifier()
Gets the identifier feature. That is, it specifies the runtime view for the project to be used for this query.
Returns:
the identifier feature

setIdentifier

public void setIdentifier(java.lang.String identifier)
Sets the identifier feature. That is, it specifies the runtime view for the project to be used for this query.

getState

public java.lang.String getState()
Get the state string (serialization) of this query.
Returns:
query state String

setState

public void setState(java.lang.String state)
              throws ArgumentError
Set multiple query properties with a query state string (serialization).
Parameters:
state - query state String
Throws:
ArgumentError -  

logChange

public void logChange(java.lang.String command,
                      java.lang.String attr1,
                      java.lang.String attr2)
Log a query change as command,attr1,attr2.
Parameters:
command - String OneStep CGI command value
attr1 - String OneStep CGI attr1 value
attr2 - String OneStep CGI attr2 value

logChange

public void logChange(java.lang.String command,
                      java.lang.String attr1)
Log a query change as command,attr1,attr2 where attr2 is blank.
Parameters:
command - String OneStep CGI command value
attr1 - String OneStep CGI attr1 value

© Copyright 2005, 2006. IBM Corporation. All rights reserved.