View Javadoc

1   
2   package net.obsearch.index;
3   import net.obsearch.Index;
4   import net.obsearch.ob.OBLong;
5   import net.obsearch.result.OBPriorityQueueLong;
6   import net.obsearch.exception.IllegalIdException;
7   import net.obsearch.exception.NotFrozenException;
8   import net.obsearch.exception.OBException;
9   import net.obsearch.exception.OutOfRangeException;
10  import java.util.Iterator;
11  import net.obsearch.filter.Filter;
12  
13  
14  /*
15      OBSearch: a distributed similarity search engine
16      This project is to similarity search what 'bit-torrent' is to downloads.
17      Copyright (C)  2007 Arnoldo Jose Muller Molina
18  
19    	This program is free software: you can redistribute it and/or modify
20      it under the terms of the GNU General Public License as published by
21      the Free Software Foundation, either version 3 of the License, or
22      (at your option) any later version.
23  
24      This program is distributed in the hope that it will be useful,
25      but WITHOUT ANY WARRANTY; without even the implied warranty of
26      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
27      GNU General Public License for more details.
28  
29      You should have received a copy of the GNU General Public License
30      along with this program.  If not, see <http://www.gnu.org/licenses/>.
31  */
32  
33  /**
34   * An Index interface for distance functions that return Longs.
35   * @param <O>
36   *            An object of type OBLong that will be stored in the index.
37   * @author Arnoldo Jose Muller Molina
38   * @since 0.7
39   */
40  public interface IndexLong<O extends OBLong> extends Index<O> {
41  	     /**
42           * Searches the Index and returns OBResult (ID, OB and distance)
43           * elements that are closer to "object". The closest element is at the
44           * beginning of the list and the farthest elements is at the end of the
45           * list. You can control the size of the resulting set when you create
46           * the object "result". This becomes the k parameter of the search.
47           * @param object
48           *            The object that has to be searched
49           * @param r
50           *            The range to be used
51           * @param result
52           *            A priority queue that will hold the result
53           * @throws NotFrozenException
54           *             if the index has not been frozen.
55           * @throws OBException
56           *             User generated exception
57           * @throws IllegalAccessException
58           *             If there is a problem when instantiating objects O
59           * @throws InstantiationException
60           *             If there is a problem when instantiating objects O
61           * @throws IllegalIdException
62           *             This exception is left as a Debug flag. If you receive
63           *             this exception please report the problem to:
64           *             http://code.google.com/p/obsearch/issues/list
65           * @throws OutOfRangeException
66           *             If the distance of any object to any other object exceeds
67           *             the range defined by the user.
68           */
69      
70      void searchOB(O object, long r, OBPriorityQueueLong<O> result)
71              throws NotFrozenException,
72              InstantiationException, IllegalIdException, IllegalAccessException, OutOfRangeException, OBException;
73  
74  
75  		 /**
76           * Searches the Index and returns OBResult (ID, OB and distance)
77           * elements that are closer to "object". The closest element is at the
78           * beginning of the list and the farthest elements is at the end of the
79           * list. You can control the size of the resulting set when you create
80           * the object "result". This becomes the k parameter of the search.
81  				 * The parameter "filter" is used to remove unwanted objects from 
82           * the result (a select where clause). Users are responsible to
83           * implement at least one filter that can be used with their O.
84           * @param object
85           *            The object that has to be searched
86           * @param r
87           *            The range to be used
88           * @param result
89           *            A priority queue that will hold the result
90           * @throws NotFrozenException
91           *             if the index has not been frozen.
92           * @throws OBException
93           *             User generated exception
94           * @throws IllegalAccessException
95           *             If there is a problem when instantiating objects O
96           * @throws InstantiationException
97           *             If there is a problem when instantiating objects O
98           * @throws IllegalIdException
99           *             This exception is left as a Debug flag. If you receive
100          *             this exception please report the problem to:
101          *             http://code.google.com/p/obsearch/issues/list
102          * @throws OutOfRangeException
103          *             If the distance of any object to any other object exceeds
104          *             the range defined by the user.
105          */
106     
107     void searchOB(O object, long r, Filter<O> filter, OBPriorityQueueLong<O> result)
108             throws NotFrozenException,
109             InstantiationException, IllegalIdException, IllegalAccessException, OutOfRangeException, OBException;
110 
111 		    
112 /**
113 	 * This method returns a list of all the distances of the query against  the DB.
114 	 * This helps to calculate EP values in a cheaper way. results that are equal to the original object are added or skipped based on "filterSame"
115 	 * as Float.MAX_VALUE
116 	 * @param query
117 	 * @param filterSame if True we do not return objects o such that query.equals(o)
118 	 * @return
119 	 * @throws OBException 
120 	 * @throws InstantiationException 
121 	 * @throws IllegalAccessException 
122 	 */
123 		public long[] fullMatchLite(O query, boolean filterSame) throws OBException, IllegalAccessException, InstantiationException;
124 		
125 }
126