001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/search/tags/sakai_2-4-1/search-api/api/src/java/org/sakaiproject/search/api/SearchService.java $
003: * $Id: SearchService.java 29315 2007-04-20 14:28:12Z ajpoland@iupui.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.search.api;
021:
022: import java.io.IOException;
023: import java.util.List;
024: import java.util.Map;
025:
026: /**
027: * Provides a search interface
028: *
029: * @author ieb
030: */
031: public interface SearchService extends Diagnosable {
032: public static final String REST_USERID = "u";
033:
034: public static final String REST_TERMS = "q";
035:
036: public static final String REST_CHECKSUM = "cs";
037:
038: public static final String REST_CONTEXTS = "ctx";
039:
040: public static final String REST_START = "s";
041:
042: public static final String REST_END = "e";
043:
044: /**
045: * event to trigger an update of the index sent from Search Service to index
046: * builders
047: */
048: public static final String EVENT_TRIGGER_SEARCH = "search.update";
049:
050: /**
051: * event to trigger a reload of the search index by query nodes
052: */
053: public static final String EVENT_TRIGGER_INDEX_RELOAD = "search.index.reload";
054:
055: public static final String EVENT_SEARCH = "search.query";
056:
057: public static final String EVENT_SEARCH_REF = "/search/query/";
058:
059: /*
060: * The search fields being stored in the index
061: */
062: /**
063: * Search Index Field the site id of the entity ( where is was produced)
064: */
065: public static final String FIELD_SITEID = "siteid";
066:
067: /**
068: * Search Index Field the url to the entity
069: */
070: public static final String FIELD_URL = "url";
071:
072: /**
073: * Search Field The Name of the Tool that owns the entity
074: */
075: public static final String FIELD_TOOL = "tool";
076:
077: /**
078: * Seadch Field The title of the entity
079: */
080: public static final String FIELD_TITLE = "title";
081:
082: /**
083: * Searhc Field (term vector, not full contents) The contents of the Entity
084: */
085: public static final String FIELD_CONTENTS = "contents";
086:
087: /**
088: * Search Field The context of the Entity
089: */
090: public static final String FIELD_CONTEXT = "context";
091:
092: /**
093: * Search Field The tool subtype of the entity
094: */
095: public static final String FIELD_SUBTYPE = "subtype";
096:
097: /**
098: * Search Field The tool type of the entity
099: */
100: public static final String FIELD_TYPE = "type";
101:
102: /**
103: * Search Field The Sakai id of the entity
104: */
105: public static final String FIELD_ID = "id";
106:
107: /**
108: * Search Field the container of the entity
109: */
110: public static final String FIELD_CONTAINER = "container";
111:
112: /**
113: * Search field The reference of the entity
114: */
115: public static final String FIELD_REFERENCE = "reference";
116:
117: public static final String DATE_STAMP = "indexdate";
118:
119: /**
120: * Perform a search, return results in a list.
121: *
122: * @param searchTerms
123: * the search terms
124: * @param contexts
125: * a list of contexts in which to perform the search
126: * @param searchEnd
127: * @param searchStart
128: * @return
129: */
130: SearchList search(String searchTerms, List contexts,
131: int searchStart, int searchEnd);
132:
133: /**
134: * This is the same as standard search, but the caller can specify, by name, the
135: * index Filter and the index Sorter by name
136: * The Sorter and the Filter will be consulted during the search, and hence should not
137: * make massive demands on the framework, otherwise they will cripple the search
138: * performance
139: * @param searchTerms A search string
140: * @param contexts A list of contexts
141: * @param start starting from
142: * @param end ending at
143: * @param filterName a lucene filter
144: * @param sorterName a lucene sorter
145: * @return
146: */
147: public SearchList search(String searchTerms, List contexts,
148: int start, int end, String filterName, String sorterName);
149:
150: /**
151: * Adds a function for the SearchService to respond to and route to the
152: * index builder. EntityProducers that want their content to be searched,
153: * should register the events that indicate new data to this
154: *
155: * @param function
156: */
157: void registerFunction(String function);
158:
159: /**
160: * When reload is called, the index should be reloaded
161: */
162: void reload();
163:
164: /**
165: * Trigger an refresh of the whole index
166: */
167: void refreshInstance();
168:
169: /**
170: * trigger a rebuild of the whole index
171: */
172: void rebuildInstance();
173:
174: /**
175: * Refresh the current site only
176: *
177: * @param currentSiteId
178: */
179: void refreshSite(String currentSiteId);
180:
181: /**
182: * rebuild the current site only
183: *
184: * @param currentSiteId
185: */
186: void rebuildSite(String currentSiteId);
187:
188: /**
189: * get the status of the search service
190: *
191: * @return
192: */
193: String getStatus();
194:
195: /**
196: * get the number of documents in the search index
197: *
198: * @return
199: */
200: int getNDocs();
201:
202: /**
203: * get the number of pending documents in the search index
204: *
205: * @return
206: */
207: int getPendingDocs();
208:
209: /**
210: * get all the search items in the index (must be a lazy load list)
211: *
212: * @return
213: */
214: List getAllSearchItems();
215:
216: /**
217: * get the master itemf to sthe site
218: *
219: * @return
220: */
221: List getSiteMasterSearchItems();
222:
223: /**
224: * get the global master items
225: *
226: * @return
227: */
228: List getGlobalMasterSearchItems();
229:
230: /**
231: * Get the status of the search engine
232: *
233: * @return
234: */
235: SearchStatus getSearchStatus();
236:
237: /**
238: * force the removal of the worker lock
239: *
240: * @return
241: */
242: boolean removeWorkerLock();
243:
244: List getSegmentInfo();
245:
246: /**
247: * Force a reload regardless of if the index has changed
248: *
249: */
250: void forceReload();
251:
252: /**
253: * get the term vector for this document, where document is the
254: * @param doc
255: * @return
256: * @throws IOException
257: */
258: TermFrequency getTerms(int documentId) throws IOException;
259:
260: /**
261: * generates a block of XML representign the search results
262: * @param parameterMap
263: * @return
264: */
265: String searchXML(Map parameterMap);
266:
267: }
|