1/*------------------------------------------------------------------------------
2* Copyright (C) 2003-2006 Ben van Klinken and the CLucene Team
3*
4* Distributable under the terms of either the Apache License (Version 2.0) or
5* the GNU Lesser General Public License, as specified in the COPYING file.
6------------------------------------------------------------------------------*/
7#ifndef _lucene_search_FieldDocSortedHitQueue_
8#define _lucene_search_FieldDocSortedHitQueue_
9
10#if defined(_LUCENE_PRAGMA_ONCE)
11# pragma once
12#endif
13
14#include "Sort.h"
15#include "CLucene/util/PriorityQueue.h"
16
17CL_NS_DEF(search)
18
19/**
20 * Expert: A ScoreDoc which also contains information about
21 * how to sort the referenced document. In addition to the
22 * document number and score, this object contains an array
23 * of values for the document from the field(s) used to sort.
24 * For example, if the sort criteria was to sort by fields
25 * "a", "b" then "c", the <code>fields</code> object array
26 * will have three elements, corresponding respectively to
27 * the term values for the document in fields "a", "b" and "c".
28 * The class of each element in the array will be either
29 * Integer, Float or String depending on the type of values
30 * in the terms of each field.
31 *
32 * @see ScoreDoc
33 * @see TopFieldDocs
34 */
35class FieldDoc: LUCENE_BASE {
36public:
37 //FieldDoc did inherit from ScoreDoc, but now we make the scoredoc a member
38 struct ScoreDoc scoreDoc;
39
40 /** Expert: The values which are used to sort the referenced document.
41 * The order of these will match the original sort criteria given by a
42 * Sort object. Each Object will be either an Integer, Float or String,
43 * depending on the type of values in the terms of the original field.
44 * @see Sort
45 * @see Searchable#search(Query,Filter,int32_t,Sort)
46 */
47 CL_NS(util)::Comparable** fields;
48
49 /** Expert: Creates one of these objects with empty sort information. */
50 FieldDoc (int32_t doc, qreal score);
51 /** Expert: Creates one of these objects with the given sort information. */
52 FieldDoc (int32_t doc, qreal score, CL_NS(util)::Comparable** fields);
53 ~FieldDoc();
54};
55
56/**
57 * Expert: Collects sorted results from Searchable's and collates them.
58 * The elements put into this queue must be of type FieldDoc.
59 */
60class FieldDocSortedHitQueue:
61 public CL_NS(util)::PriorityQueue<FieldDoc*,CL_NS(util)::Deletor::Object<FieldDoc> >
62{
63private:
64 DEFINE_MUTEX(THIS_LOCK)
65
66 // this cannot contain AUTO fields - any AUTO fields should
67 // have been resolved by the time this class is used.
68 SortField** fields;
69 int32_t fieldsLen;
70
71 void _countsize(){
72 fieldsLen=0;
73 while(fields[fieldsLen]!=NULL)
74 fieldsLen++;
75 }
76
77 // used in the case where the fields are sorted by locale
78 // based strings
79 //todo: not implemented in clucene because locales has not been implemented
80 //Collator[] collators; //volatile
81
82public:
83 /**
84 * Creates a hit queue sorted by the given list of fields.
85 * @param fields Field names, in priority order (highest priority first).
86 * @param size The number of hits to retain. Must be greater than zero.
87 */
88 FieldDocSortedHitQueue (SortField** fields, int32_t size);
89 ~FieldDocSortedHitQueue();
90
91
92 /**
93 * Allows redefinition of sort fields if they are <code>NULL</code>.
94 * This is to handle the case using ParallelMultiSearcher where the
95 * original list contains AUTO and we don't know the actual sort
96 * type until the values come back. The fields can only be set once.
97 * This method is thread safe.
98 * @param fields
99 */
100 void setFields (SortField** fields);
101
102 /** Returns the fields being used to sort. */
103 SortField** getFields() {
104 return fields;
105 }
106
107 /** Returns an array of collators, possibly <code>NULL</code>. The collators
108 * correspond to any SortFields which were given a specific locale.
109 * @param fields Array of sort fields.
110 * @return Array, possibly <code>NULL</code>.
111
112 private Collator[] hasCollators (SortField[] fields) {
113 if (fields == NULL) return NULL;
114 Collator[] ret = new Collator[fields.length];
115 for (int32_t i=0; i<fields.length; ++i) {
116 Locale locale = fields[i].getLocale();
117 if (locale != NULL)
118 ret[i] = Collator.getInstance (locale);
119 }
120 return ret;
121 }*/
122
123protected:
124 /**
125 * Returns whether <code>a</code> is less relevant than <code>b</code>.
126 * @param a FieldDoc
127 * @param b FieldDoc
128 * @return <code>true</code> if document <code>a</code> should be sorted after document <code>b</code>.
129 */
130 bool lessThan (FieldDoc* docA, FieldDoc* docB);
131};
132
133
134/**
135* Expert: Returned by low-level sorted search implementations.
136*
137* @see Searchable#search(Query,Filter,int32_t,Sort)
138*/
139class TopFieldDocs: public TopDocs {
140public:
141 /// The fields which were used to sort results by.
142 SortField** fields;
143
144 FieldDoc** fieldDocs;
145
146 /** Creates one of these objects.
147 * @param totalHits Total number of hits for the query.
148 * @param fieldDocs The top hits for the query.
149 * @param scoreDocs The top hits for the query.
150 * @param scoreDocsLen Length of fieldDocs and scoreDocs
151 * @param fields The sort criteria used to find the top hits.
152 */
153 TopFieldDocs (int32_t totalHits, FieldDoc** fieldDocs, int32_t scoreDocsLen, SortField** fields);
154 ~TopFieldDocs();
155};
156
157CL_NS_END
158#endif
159
160