View Javadoc

1   /*
2    *  XNap - A P2P framework and client.
3    *
4    *  See the file AUTHORS for copyright information.
5    *
6    *  This program is free software; you can redistribute it and/or modify
7    *  it under the terms of the GNU General Public License as published by
8    *  the Free Software Foundation.
9    *
10   *  This program is distributed in the hope that it will be useful,
11   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   *  GNU General Public License for more details.
14   *
15   *  You should have received a copy of the GNU General Public License
16   *  along with this program; if not, write to the Free Software
17   *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18   */
19  
20  package org.xnap.search;
21  
22  import java.util.Iterator;
23  
24  import javax.swing.Action;
25  import javax.swing.Icon;
26  
27  import org.xnap.peer.Peer;
28  import org.xnap.plugin.Plugin;
29  
30  import org.xnap.XNap;
31  
32  /***
33   * Defines the requirements for an object that can be used as result in a 
34   * search (table).
35   */
36  public interface SearchResult {
37  
38      //--- Constant(s) ---
39  
40  	/***
41  	 * If a key is prefixed with the HIDE_PREFIX string, it is not displayed. 
42  	 * This can be used for stuff like checksums.
43  	 */
44  	String HIDE_PREFIX = "_";
45  	
46      /***
47       * The bitrate key. The value should be the bitrate of the song in kbps.
48       */
49      String BITRATE = XNap.tr("Bitrate");
50  
51      /***
52       * The length key. The value should be the frequency of the song in Hz.
53       */
54      String FREQUENCY = XNap.tr("Frequency");
55  
56      /***
57       * The length key. The value should be the length of the song in seconds.
58       */
59      String LENGTH = XNap.tr("Length");
60  
61      /***
62       * SHA1 hash (hidden).
63       */
64      String SHA1 = HIDE_PREFIX + "SHA1";
65  
66      /***
67       * SHA1 hash (hidden).
68       */
69      String MD5 = HIDE_PREFIX + "MD5";
70  
71      /***
72       * URN, see RFC 2141 (hidden).
73       */
74      String URN = HIDE_PREFIX + "URN";
75  
76      //--- Method(s) ---
77  
78      /***
79       * Returns true, if this object and <code>result</code> can be grouped
80       * together.
81       */
82      boolean canGroup(SearchResult result);
83  
84      /***
85       * Creates a group root that has this object's properties.
86       */
87      SearchResultContainer createContainer();
88  
89      /***
90       * Returns the actions for this search result.
91       */
92      Action[] getActions();
93  
94      /***
95       * Returns a score between 1 and 255. Higher number means better 
96       * availability. Return 1 if unsure.
97       *
98       * @return 0, if this makes no sense (i.e. for a local file)
99       */
100     int getAvailability();
101 
102     /***
103      * Returns a value. 
104      *
105      * @param key anything like BITRATE, LENGTH...
106      */
107     Object get(String key);
108 
109     /***
110      * Returns the full filename. Used by <code>SearchFilter</code> for 
111      * matching. 
112      *
113      * @see xnap.search.SearchFilter
114      */
115     String getFilename();
116 
117     /***
118      * Returns the filesize.
119      */
120     long getFilesize();
121 
122 	/***
123 	 * Used for grouping of results.
124 	 */
125 	Object getHash();
126 
127     /***
128      * Returns a 16x16 icon that is displayed next to the filename.
129      */
130     Icon getIcon();
131 
132     /***
133      * Returns the tokenized path without delimeters. Used for the browse tree.
134      * C:\Files\Share would be returned as
135      * <code>new String[] { "C:", "Files", "Share" }</code>
136      *
137      * @return null, if result has no path; the path, otherwise
138      */
139     String[] getPath();
140 
141     /***
142      * Returns the originating plugin.
143      */
144     Plugin getPlugin();
145 
146     /***
147      * Returns the filename presented to the user.
148      */
149     String getShortFilename();
150 
151 	/***
152 	 * Returns the number of sources.
153 	 */
154 	int getSourcesCount();
155 
156     /***
157      * Returns the peer that offer this result for download.
158      */
159     Peer getPeer();    
160 
161     /***
162      * Returns an iterator for all keys that can be retreived by calling
163      * {@link #get(String)}.
164 	 *
165 	 * @return null, if no keys are defined
166      */
167     Iterator keys();
168 
169 }