|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectmckay.utilities.webservices.NetworkSearch
public abstract class NetworkSearch
An abstract class for submitting various types of search queries to arbitrary on-line services using arbitrary types of web service formats. Fields may be set in order to set parameters for all subsequent searches performed by objects of this class.
Field Summary | |
---|---|
static int |
GOOGLE_SOAP_CODE
The code used to identify searches using the GoogleWebSearch class that extends this class. |
protected boolean |
include_similar_but_non_matching
Whether results returned by search queries performed by this object may include hits that do not contain one or more of the specified search string(s) but do contain terms very similar to them (e.g. |
static java.lang.String[] |
included_countries
The countries that may be specified in searches. |
static java.lang.String[] |
included_file_types
The file types that may be specified in searches. |
static java.lang.String[] |
included_languages
The languages that may be specified in searches. |
protected java.lang.String |
limit_to_country
Name of a country that sites must be in in order to be included in search results. |
protected java.lang.String |
limit_to_file_type
A file extension a document must have in order to be returned as a hit in search results. |
protected java.lang.String |
limit_to_language
Name of a language that hits must be in in order to be included in search results. |
protected boolean |
literal_search
Whether all search queries performed by this object should be literal searches (e.g. |
protected boolean |
or_based_search
Whether search queries performed by this object need only contain one of the specified query words in order to result in a hit. |
protected java.lang.String |
region_to_search_from
Name of a country where the search will be performed (i.e. |
protected java.lang.String |
specific_site
Network site that will be exclusively searched in all search queries performed by this object. |
protected java.lang.String[] |
strings_to_exclude
Strings to exclude in all search queries performed by this object (i.e filter strings). |
protected boolean |
suppress_adult_content
Whether to suppress hits that are classified as containing adult content by the search service in question. |
protected boolean |
suppress_similar_hits
Whether to suppress similar hits when reporting results. |
static int |
YAHOO_REST_CODE
The code used to identify searches using the YahooWebSearch class that extends this class. |
Constructor Summary | |
---|---|
NetworkSearch()
Creates a new instance of NetworkSearch with fields set to defaults. |
Method Summary | |
---|---|
protected abstract 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 abstract java.lang.String |
formatSearchString(java.lang.String[] search_strings)
Returns a query formatted based on the settings of this superclass' fields and the formatting conventions of the particular search service used by the implementing subclass' particular search service. |
java.lang.String |
getHTMLFormattedSearchResults(java.lang.String[][] search_results,
int start_rank,
java.lang.String total_hits,
java.lang.String query_used,
java.lang.String service_name)
Takes the results produced by a NetworkSearch subclass search and formats them into an HTML page, which is returned. |
abstract 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. |
long |
getNumberHits(java.lang.String[] search_strings,
java.lang.String[] query_used,
int allowed_attempts)
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. |
long |
getNumberHits(java.lang.String search_string,
java.lang.String[] query_used)
Returns the number of hits for a query containing the given search strings. |
abstract java.lang.String |
getSeachServiceName()
Returns the name of the web services used by the implementing class. |
abstract 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[][] |
getSearchResults(java.lang.String search_string,
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 string. |
abstract 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 abstract java.lang.Object |
prepareSearcher(java.lang.Object searcher)
Returns an object used to perform searches and/or configures an existing search Object, based on the particular web services system in question. |
void |
setCountryResultsMustBeIn(java.lang.String country)
Set a specific country that sites must be in in order to be included in search results. |
void |
setFileTypeResultsMustBelongTo(java.lang.String file_type)
Sets the file extension a document must have in order to be returned as a hit in search results. |
void |
setIncludeSimilarButNonMatchingStrings(boolean include_similar_but_non_matching)
Sets whether results returned by search queries performed by this object may include hits that do not contain one or more of the specified search string(s) but do contain terms very similar to them (e.g. |
void |
setLanguageResultsMustBeIn(java.lang.String language)
Set a specific language that hits must be in in order to be included in search results. |
void |
setLiteralSearch(boolean literal_search)
Sets whether all search queries performed by this object should be literal searches (e.g. |
void |
setOrBasedSearch(boolean or_based_search)
Sets whether search queries performed by this object need only contain one of the specified query words in order to result in a hit. |
void |
setRegionToSearchFrom(java.lang.String country)
Set the name of a country where the search will be performed (i.e. |
void |
setSearchStringsToExclude(java.lang.String[] strings_to_exclude)
Sets strings to exclude in all search queries performed by this object. |
void |
setSpecificSiteToSearch(java.lang.String specific_site)
Set a specific network site that should be exclusively searched in all search queries performed by this object. |
void |
setSuppressAdultContent(boolean suppress_adult_content)
Sets whether to suppress hits that are classified as containing adult content by the search service in question. |
void |
setSuppressSimilarHits(boolean suppress_similar_hits)
Sets whether to suppress similar hits when reporting results. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected boolean literal_search
protected boolean or_based_search
protected boolean include_similar_but_non_matching
protected java.lang.String[] strings_to_exclude
protected java.lang.String specific_site
protected java.lang.String limit_to_language
protected java.lang.String limit_to_country
protected java.lang.String region_to_search_from
protected java.lang.String limit_to_file_type
protected boolean suppress_similar_hits
The default value set by the constructor is false.
protected boolean suppress_adult_content
public static final java.lang.String[] included_languages
public static final java.lang.String[] included_countries
public static final java.lang.String[] included_file_types
public static final int GOOGLE_SOAP_CODE
public static final int YAHOO_REST_CODE
Constructor Detail |
---|
public NetworkSearch()
Method Detail |
---|
public void setLiteralSearch(boolean literal_search)
literal_search
- Whether or not literal searches are to be
performed.public void setOrBasedSearch(boolean or_based_search)
or_based_search
- Value to set field to.public void setIncludeSimilarButNonMatchingStrings(boolean include_similar_but_non_matching)
include_similar_but_non_matching
- Value to set field to.public void setSearchStringsToExclude(java.lang.String[] strings_to_exclude) throws java.lang.Exception
A value of null (the default set by the constructor) means that no strings are excluded. No entries may be null.
strings_to_exclude
- Unformatted strings that will be used to
filter searches.
java.lang.Exception
- Throws an informative exception if
strings_to_exclude is invalid.public void setSpecificSiteToSearch(java.lang.String specific_site)
specific_site
- The network site to search.public void setLanguageResultsMustBeIn(java.lang.String language) throws java.lang.Exception
language
- The language that results must be in, or "No
Limitations".
java.lang.Exception
- Throws an informative exception if the
language is invalid.public void setCountryResultsMustBeIn(java.lang.String country) throws java.lang.Exception
country
- The cournty that results must be in, or "No
Limitations".
java.lang.Exception
- Throws an informative exception if the
country is invalid.public void setRegionToSearchFrom(java.lang.String country) throws java.lang.Exception
country
- The cournty where the search will be
performed, or "No Limitations".
java.lang.Exception
- Throws an informative exception if the
country is invalid.public void setFileTypeResultsMustBelongTo(java.lang.String file_type) throws java.lang.Exception
file_type
- The file type where the search will be
performed, or "No Limitations".
java.lang.Exception
- Throws an informative exception if the
file_type is invalid.public void setSuppressSimilarHits(boolean suppress_similar_hits)
The default value set by the constructor is false.
suppress_similar_hits
- Whether to suppress similar hits.public void setSuppressAdultContent(boolean suppress_adult_content)
suppress_adult_content
- Whether to suppress adult content.public java.lang.String[][] getSearchResults(java.lang.String search_string, int start_index, int max_results, java.lang.String[] number_hits, java.lang.String[] query_used) throws java.lang.Exception
search_string
- The string to base the query on. The query is
subject to the conditions of the NetworkSearch
superclass' field settings. The argument 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
actual search query constructed and used by this
method. Useful for debugging. Ignored if null.
java.lang.Exception
- Throws an informative exception if a problem
occurs.public long getNumberHits(java.lang.String search_string, java.lang.String[] query_used) throws java.lang.Exception
search_string
- The string to base the query on. The query is
subject to the conditions of the NetworkSearch
superclass' field settings. The argument 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.
java.lang.Exception
- Throws an informative exception if a problem
occurs.public java.lang.String getHTMLFormattedSearchResults(java.lang.String[][] search_results, int start_rank, java.lang.String total_hits, java.lang.String query_used, java.lang.String service_name)
search_results
- 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:start_rank
- The numerical ranking corresponding to the first
hit.total_hits
- The approximate total number of hits found by
the search service.query_used
- The query used by the search service. Does not
include directly aspects of the query that were
directly parametrized into the search service's
web services.service_name
- The name of the web service used to perform the
search.
public abstract java.lang.String getSeachServiceName()
public abstract java.lang.String getSearchServiceLimitations()
public abstract 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
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.
java.lang.Exception
- Throws an informative exception if a problem
occurs.public abstract long getNumberHits(java.lang.String[] search_strings, java.lang.String[] query_used) throws java.lang.Exception
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.
java.lang.Exception
- Throws an informative exception if a problem
occurs.public long getNumberHits(java.lang.String[] search_strings, java.lang.String[] query_used, int allowed_attempts) throws java.lang.Exception
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.allowed_attempts
- The number of unsuccesful attempts allowed
before the user is notived.
java.lang.Exception
- Throws an informative exception if a problem
occurs.protected abstract java.lang.String formatSearchString(java.lang.String[] search_strings) throws java.lang.Exception
This method should be called internally be each search method implemented by the subclass before searches are actually performed.
When possible, configurations are implemented by the prepareSearcher method instead in order to restrict query length, which is limited by some web services.
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.
java.lang.Exception
- Throws an informative exception if search_terms
is null or one of its entries is null.protected abstract java.lang.Object prepareSearcher(java.lang.Object searcher) throws java.lang.Exception
This method should be called internally be each search method implemented by the subclass before searches are actually performed.
Some search settings will sometimes be incorporated directly into the query string by the formatSearchString method instead of here, based on the nature of the web services system in question. However, when possible, configurations are implemented here in order to restrict query length, which is limited by some web services.
searcher
- The Object to perform the search with, as
defined by the particular web services system
in question. May be null if it is created by
this method.
java.lang.Exception
- Throws an informative exception if a problem
occursprotected abstract void formatErrorMessage(java.lang.Exception exception, java.lang.String query, int max_results) throws java.lang.Exception
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.
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 applicablemax_results
- The maximum number of hits that searches
are configured to return.
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.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |