mckay.utilities.webservices
Class GoogleWebSearch

java.lang.Object
  extended by mckay.utilities.webservices.NetworkSearch
      extended by mckay.utilities.webservices.GoogleWebSearch

public class GoogleWebSearch
extends NetworkSearch

Allows access to a variety of types of searches using the Google SOAP web services.

Limitations of these web services are specified by the getSearchServiceLimitations method.


Field Summary
 
Fields inherited from class mckay.utilities.webservices.NetworkSearch
GOOGLE_SOAP_CODE, include_similar_but_non_matching, included_countries, included_file_types, included_languages, limit_to_country, limit_to_file_type, limit_to_language, literal_search, or_based_search, region_to_search_from, specific_site, strings_to_exclude, suppress_adult_content, suppress_similar_hits, YAHOO_REST_CODE
 
Constructor Summary
GoogleWebSearch(java.lang.String google_license_key)
          Creates a new instance of GoogleWebSearch, stores the Google licesne key and sets the superclass' fields to their default values.
 
Method Summary
protected  void formatErrorMessage(java.lang.Exception exception, java.lang.String query, int max_results)
          Takes in an exception and then throws a new Exception that identifies the problem that occured in a way that is standardized accross web services.
protected  java.lang.String formatSearchString(java.lang.String[] search_strings)
          Returns a query formatted based on the settings of the NetworkSearch superclass' fields and the Google search formatting conventions.
 long getNumberHits(java.lang.String[] search_strings, java.lang.String[] query_used)
          Returns the number of hits for a query containing the given search strings, where the search is a boolean AND of the strings in the entries of the search_strings parameter.
 java.lang.String getSeachServiceName()
          Returns the name of the web services used by this class.
 java.lang.String[][] getSearchResults(java.lang.String[] search_strings, int start_index, int max_results, java.lang.String[] number_hits, java.lang.String[] query_used)
          Returns the top results for a query containing the given search strings, where the search is a boolean AND of the strings in the entries of the search_strings parameter.
 java.lang.String getSearchServiceLimitations()
          Returns the specific limitations of this web service in the context of all of the search parameters available to the NetworkSearch class and its subclasses.
protected  java.lang.Object prepareSearcher(java.lang.Object searcher)
          Configures and returns the search_client GoogleSearch object based on settings stored in this GoogleWebSearch superclass NetworkSearch object's fields
 
Methods inherited from class mckay.utilities.webservices.NetworkSearch
getHTMLFormattedSearchResults, getNumberHits, getNumberHits, getSearchResults, setCountryResultsMustBeIn, setFileTypeResultsMustBelongTo, setIncludeSimilarButNonMatchingStrings, setLanguageResultsMustBeIn, setLiteralSearch, setOrBasedSearch, setRegionToSearchFrom, setSearchStringsToExclude, setSpecificSiteToSearch, setSuppressAdultContent, setSuppressSimilarHits
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GoogleWebSearch

public GoogleWebSearch(java.lang.String google_license_key)
Creates a new instance of GoogleWebSearch, stores the Google licesne key and sets the superclass' fields to their default values.

Parameters:
google_license_key - The Google license key that is to be used to access the Google SOAP web services.
Method Detail

getSeachServiceName

public java.lang.String getSeachServiceName()
Returns the name of the web services used by this class.

Specified by:
getSeachServiceName in class NetworkSearch
Returns:
The implementing web services called.

getSearchServiceLimitations

public java.lang.String getSearchServiceLimitations()
Returns the specific limitations of this web service in the context of all of the search parameters available to the NetworkSearch class and its subclasses.

Specified by:
getSearchServiceLimitations in class NetworkSearch
Returns:
Limitations of the specific web service. This is formatted as an unnumbered HTML list.

getSearchResults

public java.lang.String[][] getSearchResults(java.lang.String[] search_strings,
                                             int start_index,
                                             int max_results,
                                             java.lang.String[] number_hits,
                                             java.lang.String[] query_used)
                                      throws java.lang.Exception
Returns the top results for a query containing the given search strings, where the search is a boolean AND of the strings in the entries of the search_strings parameter. The search is subject to the NetworkSearch superclass' field settings.

Specified by:
getSearchResults in class NetworkSearch
Parameters:
search_strings - The strings to base the query on. The query consists of a boolean AND or OR of all entries of this array in addition to the conditions of the NetworkSearch superclass' field settings. The arguments passed to this parameter should not contain any special formatting.
start_index - The index of the first hit to be returned. A value of 1 refers to the highest ranked hit (there is no index 0). If this index exceeds the available number of hits then no hits are returned.
max_results - The maximum number of results to return. This imposes an upper maximum on the size of the returned array.
number_hits - A dummy array of size 1 that is filled with the number of hits for the specified query by this method. Ignored if null.
query_used - A dummy array of size 1 that is filled with the search actual query constructed and used by this method. Useful for debugging. Ignored if null.
Returns:
A matrix containing the search results. The first dimension of the matrix corresponds to each hit returned by the search, in the same order as they are returned/ranked. The second dimension specifes different types of information about each corresponding hit, as follows:
  • Entry 0: The document title.
  • Entry 1: The document URL.
  • Entry 2: The document summary.
Throws:
java.lang.Exception - Throws an informative exception if a problem occurs.

getNumberHits

public long getNumberHits(java.lang.String[] search_strings,
                          java.lang.String[] query_used)
                   throws java.lang.Exception
Returns the number of hits for a query containing the given search strings, where the search is a boolean AND of the strings in the entries of the search_strings parameter. The search is subject to the NetworkSearch superclass' field settings.

Specified by:
getNumberHits in class NetworkSearch
Parameters:
search_strings - The strings to base the query on. The query consists of a boolean AND or OR of all entries of this array in addition to the conditions of the NetworkSearch superclass' field settings. The arguments passed to this parameter should not contain any special formatting.
query_used - A dummy array of size 1 that is filled with the search actual query constructed and used by this method. Useful for debugging. Ignored if null.
Returns:
The number of hits for the specified search strings and corresponding field settings of the NetworkSearch superclass.
Throws:
java.lang.Exception - Throws an informative exception if a problem occurs.

formatSearchString

protected java.lang.String formatSearchString(java.lang.String[] search_strings)
                                       throws java.lang.Exception
Returns a query formatted based on the settings of the NetworkSearch superclass' fields and the Google search formatting conventions.

This method should be called internally before each search is performed by objects of this class.

When possible, configurations are implemented by the prepareSearcher method instead in order to restrict query length, which is limited..

Specified by:
formatSearchString in class NetworkSearch
Parameters:
search_strings - Search phrases to include in the search. The search will combine these terms using a boolean AND or OR. The arguments passed to this parameter should not contain any special formatting.
Returns:
A Google-formatted copy of the query. Note that some configurations are performed by the prepareSearcher method instead, and will not be reflected here.
Throws:
java.lang.Exception - Throws an informative exception if search_terms is null or one of its entries is null.

prepareSearcher

protected java.lang.Object prepareSearcher(java.lang.Object searcher)
Configures and returns the search_client GoogleSearch object based on settings stored in this GoogleWebSearch superclass NetworkSearch object's fields

Some search settings are incorporated directly into the query string by the formatSearchString method instead of here. However, when possible, configurations are implemented here in order to restrict query length, which is limited.

Specified by:
prepareSearcher in class NetworkSearch
Parameters:
searcher - The GoogleSearch object that will perform the search.
Returns:
The configured GoogleSearch object.

formatErrorMessage

protected void formatErrorMessage(java.lang.Exception exception,
                                  java.lang.String query,
                                  int max_results)
                           throws java.lang.Exception
Takes in an exception and then throws a new Exception that identifies the problem that occured in a way that is standardized accross web services.

This method can alternatively be calleded with null passed to the exception parameter in order to check the acceptability of the configurations stored in the fields of the NetworkSearch object that will be used to perform searches.

Specified by:
formatErrorMessage in class NetworkSearch
Parameters:
exception - An exception to be formatted. May be null if this method is being used to check field and max_results compatibility.
query - The query that generated the exception. May be "" if not applicable
max_results - The maximum number of hits that searches are configured to return. May be 0 if not applicable.
Throws:
java.lang.Exception - An exception indicating the problem that occured in a descriptive way that is standardized accross web services that implement this method. The message stored in this new exception must identify the search service that generated the Exception and it must be suitable for display in an error dialog box.