org.jdesktop.swingx.ws.yahoo.search
Class YahooSearch<T>

java.lang.Object
  extended by org.jdesktop.beans.AbstractBean
      extended by org.jdesktop.swingx.ws.yahoo.search.YahooSearch<T>
Direct Known Subclasses:
YahooContextSearch, YahooImageSearch, YahooRelatedSuggestion, YahooSpellingSuggestion, YahooVideoSearch, YahooWebSearch

public abstract class YahooSearch<T>
extends org.jdesktop.beans.AbstractBean

Base class from which other Yahoo! search beans extend. It provides support for constructing the URL in a common manner, as well as a consistent set of "search" methods that may be called by client code.


Constructor Summary
YahooSearch()
           
 
Method Summary
protected  java.net.URL constructUrl(int firstSearchPosition, int resultCount)
          Creates and returns a java.net.URL representing the search.
protected  int getDefaultResultCount()
           
protected abstract  java.lang.String getMethod()
           
protected abstract  java.util.Map getParameters()
           
protected abstract  java.lang.String getServiceName()
           
protected abstract  java.lang.String getVersionNumber()
           
protected abstract  ResultsList<T> readResults(java.io.InputStream in)
           
 ResultsList<T> search()
          Creates and returns a ResultsList populated with the search results.
 ResultsList<T> search(int firstResultPosition, int resultCount)
          Creates and returns a ResultsList populated with the search results.
 
Methods inherited from class org.jdesktop.beans.AbstractBean
addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, clone, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, hasPropertyChangeListeners, hasVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

YahooSearch

public YahooSearch()
Method Detail

readResults

protected abstract ResultsList<T> readResults(java.io.InputStream in)
                                       throws java.lang.Exception
Returns:
a ResultsList containing the results read from the given InputStream.
Throws:
java.lang.Exception

getServiceName

protected abstract java.lang.String getServiceName()
Returns:
the service name for the web service. See the Yahoo documentation for more information about what the service name is for your particular service.

getVersionNumber

protected abstract java.lang.String getVersionNumber()
Returns:
the version number of the web service. See the Yahoo documentation for more information about what the version number is for your particular service.

getDefaultResultCount

protected int getDefaultResultCount()
Returns:
the default number of results returned from the web service. See the Yahoo documentation for more information about your specific web service. Defaults to 10.

getMethod

protected abstract java.lang.String getMethod()
Returns:
the method name for the web service. See the Yahoo documentation for more information about what the method name is for your particular service.

getParameters

protected abstract java.util.Map getParameters()
Returns:
a map of parameters for your web service. See the Yahoo documentation for more information about what parameters are available for your particular service.

Note that the parameters "results" and "start" should be ommitted from this map since they are always included automatically by the constructUrl(int,int) method. Also note that you do not have to worry about url-encoding the values for these params since the constructUrl(int,int) method does this for you.


constructUrl

protected final java.net.URL constructUrl(int firstSearchPosition,
                                          int resultCount)
                                   throws java.net.MalformedURLException

Creates and returns a java.net.URL representing the search. It is constructed by calling the getServiceName(), getVersionNumber(), getMethod(), and getParameters() methods. In addition to combining these returned values into the URL, this method also performs URL escaping of the parameters as necessary. Thus, it is not necessary for the parameters in the map to be URL encoded.

If the firstSearchPosition and/or resultCount params are >= 1, then they are included in the search URL as appropriate to set the number of search results to return (resultCount) and where in the possibly infinite number of search results to start collecting results (firstSearchPosition). For instance:


   constructURL(35, 5);
 
This method call would return 5 search results, starting at the 35th result (1 based number).

Parameters:
firstSearchPosition - 1 based position in the stream of all results from which to collect resultCount number of results. If < 1, then 1 is used.
resultCount - number of results to return. If < 1, then the default result count will be used for the search (differs based on Yahoo search).
Returns:
URL representing the search.
Throws:
java.net.MalformedURLException

search

public final ResultsList<T> search()

Creates and returns a ResultsList populated with the search results. This method blocks on I/O, and should be called from a org.jdesktop.swingx.ws.BackgroundWorker or SwingWorker.

This method calls the search with the default values for resultCount (the number of results to return) and firstResultPosition (the position of the first result in the total set of results to return).

See Also:
search(int, int)

search

public final ResultsList<T> search(int firstResultPosition,
                                   int resultCount)

Creates and returns a ResultsList populated with the search results. This method blocks on I/O, and should be called from a org.jdesktop.swingx.ws.BackgroundWorker or SwingWorker. The criteria used to perform the search is the criteria found in the beans themselves. For instance, YahooWebSearch contains many bean methods to alter the search, such as org.jdesktop.swingx.ws.yahoo.search.websearch, org.jdesktop.swingx.ws.yahoo.search.websearch, and org.jdesktop.swingx.ws.yahoo.search.websearch.

This method calls the search with the given values for resultCount (the number of results to return) and firstResultPosition (the position of the first result in the total set of results to return).

Parameters:
firstSearchPosition - 1 based position in the stream of all results from which to collect resultCount number of results. If < 1, then 1 is used.
resultCount - number of results to return. If < 1, then the default result count will be used for the search (differs based on Yahoo search).
Returns:
the list of results. Each concrete class will define the actual type of these returned results.