|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.iphrase.runtime.query.Query
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.
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).
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 |
public Query(Connector connector, java.lang.String state) throws ArgumentError
Connector.createQuery()
.connector
- will be used to execute this querystate
- initial state string (serialization) or nullArgumentError
- public Query(com.iphrase.www._2003._11.oneStep.encodedTypes.KeyValPair[] pairs) throws WebServiceError
ResultSet
.pairs
- array of proxy class query property key/val pairsMethod Detail |
public void setText(java.lang.String text)
text
- String
query textpublic java.lang.String getText()
String
query text or null if no text is setpublic void setTextHistory(java.lang.String[] textHistory)
textHistory
- array of String
query text in historical orderpublic java.lang.String[] getTextHistory()
String
query text in historical orderpublic void setExpandDrillDownFeature(java.lang.String feature)
feature
- String
feature idpublic java.lang.String getExpandDrillDownFeature()
String
feature id or null if no feature id is setpublic void setTextRemoveTerm(Mentions mentions, java.lang.String term) throws ArgumentError
mentions
- Mentions
constraint from which the term is to be removedterm
- String
term to remove (not search for) in the constraintcom.iphrase.exception.ArgumentError
- public java.lang.String getTextRemoveTerm(Mentions mentions) throws ArgumentError
mentions
- Mentions
constraint from which the term is to be removedString
term to remove (not search for) in the constraint, or nullcom.iphrase.exception.ArgumentError
- public void setEnableSearchWithin(boolean enable)
enable
- true
if query will search within the current results, else false.public boolean getEnableSearchWithin()
true
if search within is enabled, else false
public void setSearchByFeatures(java.util.List features)
features
- List
of String
search feature idspublic void setSearchFeatures(java.util.List features)
public void setSearchByFeatures(java.lang.String[] features)
features
- array of String
search feature ids,
null or empty array to disable search-by-features (search all features)public void setSearchFeatures(java.lang.String[] features)
public java.lang.String[] getSearchByFeatures()
String
search feature ids, or empty array if
search-by-features is disabled (all features will be searched)public java.lang.String[] getSearchFeatures()
public void setRowsPerPage(int rows)
rows
- int
number of rows per page.public int getRowsPerPage()
int
number of rows per pagepublic void setPageNumber(int page)
page
- int
starting at 0 for first page.public int getPageNumber()
int
starting at 0 for first page.public void setGroupByFeature(java.lang.String feature)
feature
- String
feature id to group by, null or "" to removepublic java.lang.String getGroupByFeature()
String
feature id to group by, null if not setpublic void setViewByFeature(java.lang.String feature)
feature
- String
feature id to view by, null or "" to removesetGroupByFeature(java.lang.String)
public java.lang.String getViewByFeature()
String
feature id to view by, null if not setgetGroupByFeature()
public void setSummarizeByFeatures(java.util.List features)
features
- List
of String
feature idspublic void setSummarizeByFeatures(java.lang.String[] features)
features
- array of String
feature ids, empty to disablepublic java.lang.String[] getSummarizeByFeatures()
String
feature ids, possibly emptypublic void setEnableAutoSummarize(boolean enable)
enable
- if true
, disable if false
setSummarizeByFeatures(java.util.List)
public boolean getEnableAutoSummarize()
true
if auto-summarization is enabled, else false
public void setAutoSummarizeSoftLimit(int limit)
limit
- int
summarization soft limitpublic int getAutoSummarizeSoftLimit()
int
summarization soft limitpublic void setAutoSummarizeHardLimit(int limit)
limit
- int
summarization hard limitpublic int getAutoSummarizeHardLimit()
int
summarization hard limitpublic void setAddColumnFeatures(java.util.List features)
features
- List
of String
feature idspublic void setAddColumnFeatures(java.lang.String[] features)
features
- array of String
feature idspublic java.lang.String[] getAddColumnFeatures()
String
feature idspublic void setSortByFeatures(SortFeature[] sortFeatures)
sortFeatures
- array of SortFeature
public SortFeature[] getSortByFeatures()
SortFeature
public void setPrimarySortByFeature(SortFeature sort) throws ArgumentError
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)); }
sort
- SortFeature
instancecom.iphrase.exception.ArgumentError
- public SortFeature getPrimarySortByFeature() throws ArgumentError
SortFeature
instancecom.iphrase.exception.ArgumentError
- public void setGroupBySort(SortFeature sort, boolean isByTally)
sort
- SortFeature
by which results are sortedisByTally
- true
if grouped results are sorted by
tally count, else false
(sorted alphabetically, the default)public SortFeature getGroupBySortFeature()
SortFeature
by which results are sortedsetGroupBySort(com.iphrase.runtime.query.SortFeature, boolean)
public boolean getGroupBySortIsByTally()
true
if grouped results are sorted by
tally count, else false
(sorted alphabetically, the default)setGroupBySort(com.iphrase.runtime.query.SortFeature, boolean)
public void setTruncation(java.lang.String feature, int count)
feature
- String
id of feature on which to do truncationcount
- int
number of truncated items (to show)public void setTruncation(java.lang.String feature, int count, int trigger)
feature
- String
id of feature on which to do truncationcount
- int
number of truncated items (to show)trigger
- int
total number of results necessary
for truncation to triggerpublic java.lang.String getTruncationFeature()
String
truncation feature or null if truncation is not setsetTruncation(java.lang.String, int)
public int getTruncationCount()
int
truncation count or 0 if truncation is not setsetTruncation(java.lang.String, int)
public int getTruncationTrigger()
int
truncation trigger or 0 if truncation is not setsetTruncation(java.lang.String, int)
public void setConstraints(Conjunction conjunction)
conjunction
- a Conjunction
instance representing the "ANDs of ORs" of all constraints.public Conjunction getConstraints()
Conjunction
instance representing the "ANDs of ORs" of all constraints.public void setClientIp(java.lang.String clientIp)
clientIp
- IP address String
in dotted-quad formatpublic java.lang.String getClientIp()
String
in dotted-quad format,
or null if there is no client IP address associated with this querypublic void setCookie(java.lang.String cookie)
cookie
- cookie String
public java.lang.String getCookie()
String
,
or null if there is no cookie associated with this querypublic void setRefererUrl(java.lang.String refererUrl)
refererUrl
- referer URL String
public java.lang.String getRefererUrl()
String
,
or null if there is no referer URL associated with this querypublic void setUserAgent(java.lang.String userAgent)
userAgent
- user agent String
public java.lang.String getUserAgent()
String
,
or null if there is no user agent associated with this querypublic void setData(java.lang.String key, java.lang.String value)
key
- String
key, prefixed with "data", down-cased, and
followed by "=[value]" in the OneStep server logsvalue
- String
value, prefixed with "data[key]=" in the
OneStep server logspublic java.lang.String getData(java.lang.String key)
setData(java.lang.String, java.lang.String)
.key
- String
key, prefixed with "data", down-cased, and
followed by "=[value]" in the OneStep server logsString
value, prefixed with "data[key]=" in the
OneStep server logspublic void setLogClickThrough(int nrow, java.lang.String feature, java.lang.String href)
nrow
- int
row number containing the linkfeature
- String
feature id of the linkhref
- String
target URL to which we will redirectpublic QueryResult execute() throws WebServiceError
QueryResult
object.WebServiceError
- public java.lang.String toString()
toString
in class java.lang.Object
String
getState()
public java.lang.Object getParam(java.lang.String key)
public java.lang.Object setParam(java.lang.String key, java.lang.Object value)
public java.lang.String getIdentifier()
public void setIdentifier(java.lang.String identifier)
public java.lang.String getState()
String
public void setState(java.lang.String state) throws ArgumentError
state
- query state String
ArgumentError
- public void logChange(java.lang.String command, java.lang.String attr1, java.lang.String attr2)
command
- String
OneStep CGI command valueattr1
- String
OneStep CGI attr1 valueattr2
- String
OneStep CGI attr2 valuepublic void logChange(java.lang.String command, java.lang.String attr1)
command
- String
OneStep CGI command valueattr1
- String
OneStep CGI attr1 value
|
© Copyright 2005, 2006. IBM Corporation. All rights reserved. | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |