001/*
002 * Copyright (c) 2004-2010 The Regents of the University of California.
003 * All rights reserved.
004 *
005 * '$Author: barseghian $'
006 * '$Date: 2011-01-27 01:54:56 +0000 (Thu, 27 Jan 2011) $' 
007 * '$Revision: 26850 $'
008 * 
009 * Permission is hereby granted, without written agreement and without
010 * license or royalty fees, to use, copy, modify, and distribute this
011 * software and its documentation for any purpose, provided that the above
012 * copyright notice and the following two paragraphs appear in all copies
013 * of this software.
014 *
015 * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
016 * FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
017 * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
018 * THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
019 * SUCH DAMAGE.
020 *
021 * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
022 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
023 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
024 * PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
025 * CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
026 * ENHANCEMENTS, OR MODIFICATIONS.
027 *
028 */
029
030package org.kepler.gui;
031
032import java.util.Hashtable;
033
034import javax.swing.JTree;
035
036import org.kepler.authentication.AuthenticationException;
037import org.kepler.objectmanager.repository.RepositoryException;
038
039import ptolemy.kernel.util.IllegalActionException;
040
041/**
042 * this abstract class is should be extended by all classes that provide a
043 * search engine for the actory library. Any local variables in the extending
044 * classes should be initialized in the init method because it is called from
045 * the constructor of this class.
046 * 
047 *@author berkley
048 *@since February 17, 2005
049 */
050public abstract class LibrarySearcher {
051        /**
052         * the library to search
053         */
054        protected JTree _library;
055        /**
056         * Description of the Field
057         */
058        protected LibrarySearchResults _results;
059        /**
060         * Description of the Field
061         */
062        protected LibrarySearchPane _searchPane;
063        /**
064         * a user setable properties hash
065         */
066        protected Hashtable<String,Object> _properties;
067
068        /**
069         * constructor
070         * 
071         *@param library
072         *            Description of the Parameter
073         *@param searchPane
074         *            Description of the Parameter
075         */
076        public LibrarySearcher(JTree library, LibrarySearchPane searchPane) {
077                _library = library;
078                _searchPane = searchPane;
079                _results = new LibrarySearchResults();
080                _properties = new Hashtable<String,Object>();
081                init();
082        }
083
084        /**
085         * set a user setable property
086         */
087        public void setProperty(String name, Object value) {
088                _properties.put(name, value);
089        }
090
091        /**
092         * returns a user set property
093         */
094        public Object getProperty(String name) {
095                return _properties.get(name);
096        }
097
098        /**
099         * search for value in the library
100         * 
101         *@param value
102         *            the value to search for
103         *@param searchRemotely
104         *            true if a remote search should take place.
105         *@param authenticate
106         *                        true will prompt user to login if necessary.
107         *@return LibrarySearchResults the results of the search
108         * @throws RepositoryException 
109         * @throws AuthenticationException 
110         */
111        public abstract LibrarySearchResults search(String value, 
112                        boolean authenticate) throws IllegalActionException, RepositoryException, AuthenticationException;
113
114        /**
115         * provides any initialization needed prior to searching. It is called when
116         * the class is constructed. Note that any local variables of extending
117         * classes should be initialized in init since it is called be the
118         * constructor of the super class (LibrarySearcher).
119         */
120        protected abstract void init();
121}