Skip navigation links

oracle.search.query.webservice.client
Class OracleSearchService

java.lang.Object
oracle.search.query.webservice.client.OracleSearchService

public class OracleSearchService

extends java.lang.Object

A client proxy class that can be used to access the Oracle Secure Enterprise Search query web service.

Make sure that the Oracle SOAP library (soap.jar) and Oracle SES query web service proxy class library (search_client.jar) are in the Java CLASSPATH when using the Java proxy.

The following is one example of the use of OracleSearchService:

     // Create proxy or stub to access Oracle SES query web service.
    OracleSearchService stub = new OracleSearchService();

    // Set the soap URL (web service endpoint).
    stub.setSoapURL("http://localhost:7777/search/query/OracleSearch");

    // Perform a basic search
    OracleSearchResult result = 
          stub.doOracleSimpleSearch("oracle",        // query string
                                    new Integer(1),  // start index
                                    new Integer(10), // doc requested
                                    Boolean.FALSE,   // duplicate removed
                                    Boolean.FALSE,   // duplicate marked
                                    Boolean.TRUE);   // return estimated hit count
 
    // Get estimated hit count
    int estimatedHitCount = result.getEstimatedHitCount().intValue();
                            
    // Process result
    ResultElement[] resElements = result.getResultElements();
    for(int i = 0; i < resElements.length; i++)
    {
      System.out.println("Title : " + resElements[i].getTitle());
      System.out.println("Snippet : " + resElements[i].getSnippet());
      System.out.println("URL : " + resElements[i].getUrl()());
    }
 

Constructor Summary

OracleSearchService()

Method Summary

OracleSearchResult	doOracleBrowseSearch(java.lang.String query, java.lang.String nodeID, java.lang.String fedID, java.lang.Integer startIndex, java.lang.Integer docsRequested, java.lang.Boolean dupRemoved, java.lang.Boolean dupMarked, java.lang.String queryLang, java.lang.String docLang, java.lang.Boolean returnCount, java.lang.Integer[] fetchAttributes) Invokes Oracle SES search, restricting the search to a particular infosource node and returns search results.
OracleSearchResult	doOracleSearch(java.lang.String query, java.lang.Integer startIndex, java.lang.Integer docsRequested, java.lang.Boolean dupRemoved, java.lang.Boolean dupMarked, DataGroup[] groups, java.lang.String queryLang, java.lang.String docLang, java.lang.Boolean returnCount, java.lang.String filterConnector, Filter[] filters, java.lang.Integer[] fetchAttributes) Invokes Oracle SES advanced search and returns search results.
OracleSearchResult	doOracleSimpleSearch(java.lang.String query, java.lang.Integer startIndex, java.lang.Integer docsRequested, java.lang.Boolean dupRemoved, java.lang.Boolean dupMarked, java.lang.Boolean returnCount) Invokes Oracle SES basic search and returns search results.
Attribute[]	getAllAttributes(java.lang.String locale) Returns all the search attributes available in Oracle SES.
AttributeLOVElement[]	getAttributeLOV(Attribute attribute, java.lang.String locale) Returns a list of value (LOV) for a given search attribute.
Attribute[]	getAttributes(java.lang.String locale, DataGroup[] groups, java.lang.String groupConnector) Returns the list of search attributes that are applied to given source groups.
java.lang.Byte[]	getCachedPage(java.lang.String query, java.lang.Integer docID, java.lang.String fedID) Returns cached HTML version of a document.
DataGroup[]	getDataGroups(java.lang.String locale) Returns an array of all the source groups defined in Oracle SES.
Node[]	getInfoSourceAncestorNodes(java.lang.String nodeID, java.lang.String locale) Returns an array of all the infosource nodes (ancestor nodes) in the full path from the root node to a given infosource node.
Node	getInfoSourceNode(java.lang.String nodeID, java.lang.String fedID, java.lang.String locale) Returns an infosource node for a given node ID.
Node[]	getInfoSourceNodes(java.lang.String parentNodeID, java.lang.String fedID, java.lang.String locale) Returns all the children nodes of an infosource node.
java.lang.String[]	getInLinks(java.lang.Integer docID, java.lang.Integer maxNum, java.lang.String fedID) Returns an array of incoming links for a given document.
Language[]	getLanguages(java.lang.String locale) Returns all the languages supported by Oracle SES.
java.lang.String[]	getOutLinks(java.lang.Integer docID, java.lang.Integer maxNum, java.lang.String fedID) Returns an array of outgoing links for a given document.
java.lang.String	getSoapURL() Gets the URL for the web service endpoint.
SCElement[]	getSuggestedContent(java.lang.String query, java.lang.String returnType) Invokes Oracle SES Suggested Content search only to get the suggested content for the query
Status	login(java.lang.String username, java.lang.String password) Logs in the end user to Oracle SES.
Status	logout() Logs out the end user from Oracle SES.
java.lang.String	logUserClick(java.lang.Integer queryID, java.lang.Integer urlID, java.lang.Integer infoSourceID, java.lang.Integer position, java.lang.String fedID) Logs user's clicks on the search hits.
Status	proxyLogin(java.lang.String username, java.lang.String password, java.lang.String searchUser) Logs in the end user to Oracle SES using proxy authentication.
Status	setSearchUser(java.lang.String username) Sets the search user.
Status	setSessionContext(SessionContextElement[] sessionContext) Sets the session context to be used for query-time filtering.
void	setSoapURL(java.lang.String soapURL) Sets the URL for the web service endpoint.
Status	submitUrl(java.lang.String Url) Submits a URL for Oracle SES to crawl and index.

Methods inherited from class java.lang.Object

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

Constructor Detail

OracleSearchService

public OracleSearchService()

Method Detail

getOutLinks

public java.lang.String[] getOutLinks(java.lang.Integer docID,
                                      java.lang.Integer maxNum,
                                      java.lang.String fedID)
                               throws java.lang.Exception

Returns an array of outgoing links for a given document.

Parameters:

docID - ID of the document for which outgoing links to be returned

maxNum - maximum number of outgoing links to be fetched. The default is 25 if not set explicitly.

fedID - ID of the federated instance to which the document belongs to

Returns:

an array of outgoing links

Throws:

java.lang.Exception - if any error occurs

submitUrl

public Status submitUrl(java.lang.String Url)
                 throws java.lang.Exception

Submits a URL for Oracle SES to crawl and index.

Parameters:

Url - URL to be submitted to Oracle SES to crawl and index. It must a valid URL and it cannot be null.

Returns:

Status of the request. Status code can be either "successful" or "failed". If the status code is "successful", then status message is null; otherwise it consists of an error message.

Throws:

java.lang.Exception - if any error occurs

getCachedPage

public java.lang.Byte[] getCachedPage(java.lang.String query,
                                      java.lang.Integer docID,
                                      java.lang.String fedID)
                               throws java.lang.Exception

Returns cached HTML version of a document. The actual query string would be highlighted in the output.

Note: Only first 200KB of the cached version of the document is returned.

Parameters:

query - query string used for search

docID - ID of the document for which the cached content is to be fetched

fedID - ID of the federated instance to which the document belongs

Returns:

byte array of the cached HTML version of the document

Throws:

java.lang.Exception - if any error occurs

getAttributeLOV

public AttributeLOVElement[] getAttributeLOV(Attribute attribute,
                                             java.lang.String locale)
                                      throws java.lang.Exception

Returns a list of value (LOV) for a given search attribute.

Parameters:

attribute - search attribute for which the LOV is requested

locale - a two letter representation of the locale. The default is English("en") if not set explicitly.

Returns:

an array of AttributeLOV

Throws:

java.lang.Exception - if any error occurs

getInfoSourceAncestorNodes

public Node[] getInfoSourceAncestorNodes(java.lang.String nodeID,
                                         java.lang.String locale)
                                  throws java.lang.Exception

Returns an array of all the infosource nodes (ancestor nodes) in the full path from the root node to a given infosource node.

Parameters:

locale - a two letter representation of the locale. The default is English("en") if not set explicitly.

Returns:

an array of ancestor nodes

Throws:

java.lang.Exception - if any error occurs

getInfoSourceNode

public Node getInfoSourceNode(java.lang.String nodeID,
                              java.lang.String fedID,
                              java.lang.String locale)
                       throws java.lang.Exception

Returns an infosource node for a given node ID.

Parameters:

nodeID - ID of the infosource node to be fetched

fedID - ID of the federated instance to which the infosource node belongs. "-1" for local SES instance. The default is "-1" if not set explicitly.

locale - a two letter representation of the locale The default is English("en") if not set explicitly.

Returns:

an inforsource node.

Throws:

java.lang.Exception - if any error occurs

getInLinks

public java.lang.String[] getInLinks(java.lang.Integer docID,
                                     java.lang.Integer maxNum,
                                     java.lang.String fedID)
                              throws java.lang.Exception

Returns an array of incoming links for a given document.

Parameters:

docID - ID of the document for which incoming links to be returned

maxNum - maximum number of incoming links to be returned. The default is 25 if not set explicitly

fedID - ID of the federated instance to which the document belongs

Returns:

array of incoming links

Throws:

java.lang.Exception - if any error occurs

getDataGroups

public DataGroup[] getDataGroups(java.lang.String locale)
                          throws java.lang.Exception

Returns an array of all the source groups defined in Oracle SES. It can be used by an application to show all the source groups in the search page, such that the end users can restrict their search within one or multiple source groups.

Parameters:

locale - a two letter representation of the locale. The default is English("en") if not set explicitly.

Returns:

an array of data source groups defined in Oracle SES

Throws:

java.lang.Exception - if any error occurs

doOracleSearch

public OracleSearchResult doOracleSearch(java.lang.String query,
                                         java.lang.Integer startIndex,
                                         java.lang.Integer docsRequested,
                                         java.lang.Boolean dupRemoved,
                                         java.lang.Boolean dupMarked,
                                         DataGroup[] groups,
                                         java.lang.String queryLang,
                                         java.lang.String docLang,
                                         java.lang.Boolean returnCount,
                                         java.lang.String filterConnector,
                                         Filter[] filters,
                                         java.lang.Integer[] fetchAttributes)
                                  throws java.lang.Exception

Invokes Oracle SES advanced search and returns search results.

Parameters:

query - query string. The search string should follow Oracle SES query syntax.

startIndex - index of the first document in the hit-list to be returned. The default is 1 if not set explicitly.

docsRequested - maximum number of documents in the hit-list to be returned. The default is 10 if not set explicitly.

dupRemoved - Boolean flag to enable or disable duplicate removal. If turned on, duplicate documents in the hit-list will be removed. The default is false if not set explicitly. Note: The dupMarked switch will have no effect when dupRemoved is turned on.

dupMarked - Boolean flag to enable or disable duplicate detection. The default is false if not set explicitly. Note: The dupMarked switch will have no effect when dupRemoved is turned on.

groups - data source groups that the search will be restricted to. The default is all groups if not set explicitly.

queryLang - language of the query. This is equivalent to Locale. The default is English("en") if not set explicitly. queryLang is used in relevancy boosting.

docLang - language of the documents to restrict the search. If the value is not set explicitly, then search is performed against documents of all the languages.

returnCount - Boolean flag to fetch the total hit count with the result. The default is false if not set explicitly.

filterConnector - connector between all the filters. "and" indicates the documents in the hit-list must satisfy all the filters. "or" indicates the documents in the hit-list must satisfy at least one of the filters. The default is "and" if not set explicitly.

filters - an array of filters. Each filter is a restriction on on the search result. Filters are connected by the filterConnector. The default is null(no filter applies to the search result) if not set explicitly.

fetchAttributes - array of Integers representing the IDs of custom or non-default attributes to be fetched with the search result

Returns:

search results (OracleSearchResult)

Throws:

java.lang.Exception - if any error occurs

getInfoSourceNodes

public Node[] getInfoSourceNodes(java.lang.String parentNodeID,
                                 java.lang.String fedID,
                                 java.lang.String locale)
                          throws java.lang.Exception

Returns all the children nodes of an infosource node.

Parameters:

parentNodeID - ID of the (parent) infosource node for which all the children nodes to be returned

fedID - ID of the federated instance the parent node belongs to. "-1" for local OSES instance. The default is "-1" if not specified explicitly.

locale - a two letter representaion of the locale. The default is English("en") if not set explicitly.

Returns:

array of nodes

Throws:

java.lang.Exception - if any error occurs

doOracleSimpleSearch

public OracleSearchResult doOracleSimpleSearch(java.lang.String query,
                                               java.lang.Integer startIndex,
                                               java.lang.Integer docsRequested,
                                               java.lang.Boolean dupRemoved,
                                               java.lang.Boolean dupMarked,
                                               java.lang.Boolean returnCount)
                                        throws java.lang.Exception

Invokes Oracle SES basic search and returns search results.

Parameters:

query - query string. The search string should follow Oracle SES query syntax.

startIndex - index of the first document in the hit-list to be returned. The default is 1 if not set explicitly.

docsRequested - maximum number of documents in the hit-list to be returned. The default is 10 if not set explicitly.

dupRemoved - Boolean flag to enable or disable duplicate removal. If turned on, duplicate documents in the hit-list will be removed. The default is false if not set explicitly. Note: The dupMarked switch will have no effext when dupRemoved is turned on.

dupMarked - Boolean flag to enable or disable duplicate detection. The default is false if not set explicitly. Note: The dupMarked switch will have no effext when dupRemoved is turned on.

returnCount - Boolean flag indicating whether to fetch the total hit count with the result. The default is false if not set explicitly.

Returns:

search results (OracleSearchResult)

Throws:

java.lang.Exception - if any error occurs

getSuggestedContent

public SCElement[] getSuggestedContent(java.lang.String query,
                                       java.lang.String returnType)
                                throws java.lang.Exception

Invokes Oracle SES Suggested Content search only to get the suggested content for the query

Parameters:

query - query string. The search string should follow Oracle SES query syntax.

returnType - either "html" or "xml".

Returns:

SCElement array. Each of them is one provider result

Throws:

java.lang.Exception

doOracleBrowseSearch

public OracleSearchResult doOracleBrowseSearch(java.lang.String query,
                                               java.lang.String nodeID,
                                               java.lang.String fedID,
                                               java.lang.Integer startIndex,
                                               java.lang.Integer docsRequested,
                                               java.lang.Boolean dupRemoved,
                                               java.lang.Boolean dupMarked,
                                               java.lang.String queryLang,
                                               java.lang.String docLang,
                                               java.lang.Boolean returnCount,
                                               java.lang.Integer[] fetchAttributes)
                                        throws java.lang.Exception

Invokes Oracle SES search, restricting the search to a particular infosource node and returns search results.

Parameters:

query - query string. The search string should follow Oracle SES query syntax.

nodeID - ID of the inforsource node to restrict the search to

fedID - ID of the federated Oracle SES instance the infosource node belongs

startIndex - index of the first document in the hit-list to be returned. The default is 1 if not set explicitly.

docsRequested - maximum number of documents in hit-list to be returned. The default is 10 if not set explicitly.

dupRemoved - Boolean flag to enable or disable duplicate removal. If turned on, duplicate documents in the hit-list will be removed. The default is false if not set explicitly. Note: The dupMarked switch will have no effext when dupRemoved is turned on.

dupMarked - Boolean flag to enable or disable duplicate detection. The default is false if not set explicitly. Note: The dupMarked switch will have no effext when dupRemoved is turned on.

queryLang - language of the query. This is equivalent to Locale. The default is English("en") if not set explicitly. queryLang is used in relevancy boosting.

docLang - language of the documents to restrict the search. If the value is not set explicitly, then search is performed against documents of all the languages.

returnCount - Boolean flag indicating whether to fetch the total hit count with the result. The default is false if not set explicitly.

fetchAttributes - array of Integers representing the IDs of custom or non-default attributes to be fetched with the search result.

Returns:

search results (OracleSearchResult)

Throws:

java.lang.Exception - if any error occurs

getLanguages

public Language[] getLanguages(java.lang.String locale)
                        throws java.lang.Exception

Returns all the languages supported by Oracle SES.

Parameters:

locale - a two letter representation of the locale. The default is English("en") if not set explicitly.

Returns:

array of Language

Throws:

java.lang.Exception - if any error occurs

getAttributes

public Attribute[] getAttributes(java.lang.String locale,
                                 DataGroup[] groups,
                                 java.lang.String groupConnector)
                          throws java.lang.Exception

Returns the list of search attributes that are applied to given source groups.

Parameters:

locale - a two letter representation of the locale. The default is English("en") if not set explicitly.

groups - an array of source groups for which the search attributes are requested

groupConnector - the connector between all groups. "and" indicates that the search attributes to be returned are intersection of attributes from each group. "or" indicates the search attributes to be returned are union of attributes from each group. The default is "or" of not set explicitly.

Returns:

array of Attribute

Throws:

java.lang.Exception - if any error occurs

getAllAttributes

public Attribute[] getAllAttributes(java.lang.String locale)
                             throws java.lang.Exception

Returns all the search attributes available in Oracle SES.

Parameters:

locale - a two letter representation of the locale. The default is English("en") if not set explicitly.

Returns:

array of Attribute

Throws:

java.lang.Exception - if any error occurs

setSearchUser

public Status setSearchUser(java.lang.String username)
                     throws java.lang.Exception

Sets the search user. This method will work only if the proxy user is already set explicitly through the proxyLogin call.

Parameters:

username - canonical representation of authenticated user's credential. For example: GUID in Oracle Internet Directory.

Returns:

Status of the request. Status code can be either "successful" or "failed". If the status code is "successful", then status message is null; otherwise it consists of an error message.

Throws:

java.lang.Exception - if any error occurs

proxyLogin

public Status proxyLogin(java.lang.String username,
                         java.lang.String password,
                         java.lang.String searchUser)
                  throws java.lang.Exception

Logs in the end user to Oracle SES using proxy authentication.

The proxy user must be one of the federation trusted entities created on the Oracle SES instance.

Parameters:

username - user name of the proxy user

password - password of the proxy user

searchUser - user name of the end user

Returns:

Status of the request. Status code can be either "successful" or "failed". If the status code is "successful", then status message is null; otherwise it consists of an error message.

Throws:

java.lang.Exception - if any error occurs

login

public Status login(java.lang.String username,
                    java.lang.String password)
             throws java.lang.Exception

Logs in the end user to Oracle SES.

Parameters:

username - user name of the end user

password - password of the end user

Returns:

Status of the request. Status code can be either "successful" or "failed". If the status code is "successful", then status message is null; otherwise it consists of an error message.

Throws:

java.lang.Exception - if any error occurs

logout

public Status logout()
              throws java.lang.Exception

Logs out the end user from Oracle SES.

Returns:

Status of the request. Status code can be either "successful" or "failed". If the status code is "successful", then status message is null; otherwise it consists of an error message.

Throws:

java.lang.Exception - if any error occurs

logUserClick

public java.lang.String logUserClick(java.lang.Integer queryID,
                                     java.lang.Integer urlID,
                                     java.lang.Integer infoSourceID,
                                     java.lang.Integer position,
                                     java.lang.String fedID)
                              throws java.lang.Exception

Logs user's clicks on the search hits.

Parameters:

queryID - ID of the submitted query

urlID - ID of the document that user clicked on

infoSourceID - ID of the infosource. "-1" is used if not set explicitly.

position - position (rank) of the document in the hit-list

fedID - ID of the federated Oracle SES instance to which the documents belongs

Returns:

URL of the document that user clicked on

Throws:

java.lang.Exception - if any error occurs

setSessionContext

public Status setSessionContext(SessionContextElement[] sessionContext)
                         throws java.lang.Exception

Sets the session context to be used for query-time filtering.

Parameters:

sessionContext - array of SessionContextElement

Returns:

Status of the request. Status code can be either "successful" or "failed". If the status code is "successful", then status message is null; otherwise it consists of an error message.

Throws:

java.lang.Exception - if any error occurs

getSoapURL

public java.lang.String getSoapURL()

Gets the URL for the web service endpoint.

Returns:

web service endpoint URL

setSoapURL

public void setSoapURL(java.lang.String soapURL)

Sets the URL for the web service endpoint.

Parameters:

soapURL - URL for the web service endpoint

Skip navigation links