javax.help.search.SearchQuery Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of javahelp Show documentation
Show all versions of javahelp Show documentation
The JavaHelp API provides a platform-independent help framework.
The newest version!
/*
* @(#)SearchQuery.java 1.9 06/10/30
*
* Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package javax.help.search;
import javax.help.event.EventListenerList;
import javax.help.search.SearchEvent;
import javax.help.search.SearchListener;
import java.net.URL;
import java.util.Vector;
import java.util.Locale;
import java.util.Enumeration;
/**
* The instance of a query on a search database. It is
* instantiated by SearchEngine.startQuery.
*
* Subclasses of SearchQuery can perform the search or negotiate the search
* results with an outside agent as setup in the SearchEngine class. A server
* search engine is an an example of an outside agent.
*
* Search results are returned through SearchEvents to listeners that
* register with a SearchEngine instance.
*
* @author Roger D. Brinkley
* @version 1.22 09/16/98
*
* @see javax.help.search.SearchEvent
* @see javax.help.search.SearchListener
*/
public abstract class SearchQuery {
protected EventListenerList listenerList = new EventListenerList();
protected SearchEngine hs;
protected String searchparams;
protected Locale l;
/**
* Creates a SearchQuery.
*/
public SearchQuery(SearchEngine hs) {
this.hs = hs;
}
/**
* Adds a listener for the SearchEngine posted after the search has
* started, stopped, or search parameters have been defined.
*
* @param l The listener to add.
* @see java.javahelp.SearchEngine#removeSearchListener
*/
public void addSearchListener(SearchListener l) {
listenerList.add(SearchListener.class, l);
}
/**
* Removes a listener previously added with addSearchListener.
*
* @param l The listener to remove.
* @see java.javahelp.SearchEngine#addSearchListener
*/
public void removeSearchListener(SearchListener l) {
listenerList.remove(SearchListener.class, l);
}
/**
* Starts the search. This method invokes searchStarted on
* SearchListeners and stores the searchparams. Extensions
* of SearchQuery should fully implement this method according
* to the needs of the SearchQuery and its corresponding SearchEngine.
*
*
* @param searchparams The search string.
* @param locale The locale of the search string.
* @exception IllegalArgumentException The parameters are not
* understood by this engine.
* @exception IllegalStateException There is an active search in
* progress in this instance.
*/
public void start(String searchparams, Locale l)
throws IllegalArgumentException, IllegalStateException
{
this.searchparams = searchparams;
this.l = l;
fireSearchStarted();
}
/**
* Stops the search. This method invokes searchStopped on
* SearchListeners. Extensions of
* SearchQuery should fully implement this method according to needs
* of the SearchQuery and its corresponding SearchEngine.
*
* @exception IllegalStateException The search engine is not in a state in which it can be started.
*/
public void stop() throws IllegalStateException {
fireSearchFinished();
}
/**
* Returns the SearchEngine associated with this SearchQuery.
*/
public SearchEngine getSearchEngine() {
return hs;
}
/**
* Determines if this SearchQuery is active.
*
* @returns True if active, false otherwise
*/
public abstract boolean isActive();
/**
* Notifies that query of items is found in the search.
*
* @param docs A vector of SearchItem.
* @param inSearch Is the search completed?
*/
public void itemsFound(boolean inSearch, Vector docs) {
fireItemsFound(inSearch, docs);
}
/**
* Notifies that a SearchItem has been found.
*
* @param params The parameters to the search.
* @param inSearch Is the search completed?
* @param docs A vector of SearchItem.
* @see javax.help.search.SearchItem
*/
protected void fireItemsFound(boolean inSearch, Vector docs) {
debug("fireItemsFound");
debug(" params: " + searchparams);
debug(" insearch: " + inSearch);
debug(" docs: " + docs);
Object[] listeners = listenerList.getListenerList();
SearchEvent e = null;
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i] == SearchListener.class) {
if (e == null) {
e = new SearchEvent(this, searchparams,
inSearch, docs);
}
((SearchListener)listeners[i+1]).itemsFound(e);
}
}
}
/**
* Passs through that a SearchEvent has happened.
* This is useful for SearchEngine engines that encapsulate others.
*
* @param e The SearchEvent to pass through.
*/
protected void fireItemsFound(SearchEvent e) {
Object[] listeners = listenerList.getListenerList();
Vector newItems = new Vector();
for (Enumeration enum1 = e.getSearchItems();
enum1.hasMoreElements(); ) {
newItems.addElement((SearchItem) enum1.nextElement());
}
SearchEvent e2 = new SearchEvent(this, e.getParams(),
e.isSearchCompleted(),
newItems);
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i] == SearchListener.class) {
((SearchListener)listeners[i+1]).itemsFound(e2);
}
}
}
/**
* Notifies that a search has started.
*
* @param params The parameters to the search.
*/
protected void fireSearchStarted() {
debug("fireSearchStarted");
Object[] listeners = listenerList.getListenerList();
SearchEvent e = null;
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i] == SearchListener.class) {
if (e == null) {
e = new SearchEvent(this, searchparams, true);
}
((SearchListener)listeners[i+1]).searchStarted(e);
}
}
}
/**
* Notifies that a search has completed.
*
* @param params The parameters to the search.
*/
protected void fireSearchFinished() {
debug("fireSearchFinished");
Object[] listeners = listenerList.getListenerList();
SearchEvent e = null;
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i] == SearchListener.class) {
if (e == null) {
e = new SearchEvent(this, searchparams, false);
}
((SearchListener)listeners[i+1]).searchFinished(e);
}
}
}
private static final boolean debug = false;
private static void debug(String msg) {
if (debug) {
System.err.println("SearchQuery: "+msg);
}
}
}