1 | /* |
2 | This file is part of the Nepomuk KDE project. |
3 | Copyright (C) 2008-2010 Sebastian Trueg <trueg@kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License version 2 as published by the Free Software Foundation. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef _NEPOMUK_QUERY_RESULT_H_ |
21 | #define _NEPOMUK_QUERY_RESULT_H_ |
22 | |
23 | #include <QtCore/QSharedDataPointer> |
24 | #include <QtCore/QUrl> |
25 | #include <QtCore/QList> |
26 | #include <QtCore/QHash> |
27 | |
28 | #include <Soprano/Statement> |
29 | #include <Soprano/BindingSet> |
30 | |
31 | #include "nepomukquery_export.h" |
32 | |
33 | namespace Nepomuk { |
34 | |
35 | class Resource; |
36 | class Variant; |
37 | namespace Types { |
38 | class Property; |
39 | } |
40 | |
41 | namespace Query { |
42 | /** |
43 | * \class Result result.h Nepomuk/Query/Result |
44 | * |
45 | * \brief A single search result. |
46 | * |
47 | * A search via QueryServiceClient returns a set of Result object. A result consists |
48 | * of a Nepomuk::Resource and an optional score. |
49 | * |
50 | * Additional bindings (variable values) as requested via ComparisonTerm::setVariableName() |
51 | * can be retrieved using additionalBinding(). |
52 | * |
53 | * \author Sebastian Trueg <trueg@kde.org> |
54 | * |
55 | * \since 4.4 |
56 | */ |
57 | class NEPOMUKQUERY_EXPORT Result |
58 | { |
59 | public: |
60 | /** |
61 | * Create an empty result. |
62 | */ |
63 | Result(); |
64 | |
65 | /** |
66 | * Create a new result. |
67 | * |
68 | * \param resource The result resource. |
69 | * \param score The optional result score. |
70 | */ |
71 | Result( const Nepomuk::Resource& resource, double score = 0.0 ); |
72 | |
73 | /** |
74 | * Copy constructor. |
75 | */ |
76 | Result( const Result& ); |
77 | |
78 | /** |
79 | * Destructor |
80 | */ |
81 | ~Result(); |
82 | |
83 | /** |
84 | * Assignment operator |
85 | */ |
86 | Result& operator=( const Result& ); |
87 | |
88 | /** |
89 | * The score of the result. By default the value is 0.0 |
90 | * which means no score. |
91 | * |
92 | * Be aware that scoring needs to be enabled via Query::setFullTextScoringEnabled() |
93 | * in order for this value to be filled. |
94 | * |
95 | * \sa setScore |
96 | */ |
97 | double score() const; |
98 | |
99 | /** |
100 | * The result resource. |
101 | */ |
102 | Resource resource() const; |
103 | |
104 | /** |
105 | * Set the score of the result. |
106 | * |
107 | * Normally there is no need to call this method as the query service |
108 | * does set the bindings. |
109 | * |
110 | * \sa score |
111 | */ |
112 | void setScore( double score ); |
113 | |
114 | /** |
115 | * Add the value of a request property. |
116 | * |
117 | * \sa Query::RequestProperty |
118 | */ |
119 | void addRequestProperty( const Types::Property& property, const Soprano::Node& value ); |
120 | |
121 | /** |
122 | * Retrieve the values of the request properties. |
123 | * |
124 | * \sa Query::RequestProperty |
125 | */ |
126 | QHash<Types::Property, Soprano::Node> requestProperties() const; |
127 | |
128 | /** |
129 | * Retrieve value of request property \p property. |
130 | * |
131 | * \sa requestProperties, addRequestProperty |
132 | */ |
133 | Soprano::Node operator[]( const Types::Property& property ) const; |
134 | |
135 | /** |
136 | * Retrieve value of request property \p property. |
137 | * |
138 | * \sa additionalBinding, requestProperties, addRequestProperty |
139 | */ |
140 | Soprano::Node requestProperty( const Types::Property& property ) const; |
141 | |
142 | /** |
143 | * Set the additional bindings a query returned besides the result |
144 | * itself and the request properties. |
145 | * |
146 | * Normally there is no need to call this method as the query service |
147 | * does set the bindings. |
148 | * |
149 | * \since 4.5 |
150 | */ |
151 | void setAdditionalBindings( const Soprano::BindingSet& bindings ); |
152 | |
153 | /** |
154 | * Retrieve the set of additional bindings as set via setAdditionalBindings(). |
155 | * Normally one would use additionalBinding() instead. |
156 | * |
157 | * \since 4.5 |
158 | */ |
159 | Soprano::BindingSet additionalBindings() const; |
160 | |
161 | /** |
162 | * Retrieve an additional binding as returned by the query. Typically |
163 | * these bindings are created via ComparisonTerm::setVariableName(). |
164 | * But they could also stem from custom SPARQL queries. A simple |
165 | * example would be: |
166 | * |
167 | * \code |
168 | * select ?r ?rating where { ?r nao:numericRating ?rating . } |
169 | * \endcode |
170 | * |
171 | * Here \p ?r would be used as the result's resource while |
172 | * \p ?rating could be accessed via |
173 | * |
174 | * \code |
175 | * additionalBinding( QLatin1String("rating") ); |
176 | * \endcode |
177 | * |
178 | * If for some reason one needs the plain binding values one |
179 | * could use additionalBinding(). |
180 | * |
181 | * \since 4.5 |
182 | */ |
183 | Variant additionalBinding( const QString& name ) const; |
184 | |
185 | /** |
186 | * Set the excerpt from the query. |
187 | * |
188 | * Normally there is no need to call this method as the query service |
189 | * does set the excerpt. |
190 | * |
191 | * \since 4.6 |
192 | */ |
193 | void setExcerpt( const QString& text ); |
194 | |
195 | /** |
196 | * An excerpt of the matched text with highlighted search words |
197 | * in case the query contained a full text matching. |
198 | * |
199 | * \return A rich-text snippet highlighting the search words or |
200 | * and empty string if the query did not contain any full text |
201 | * search terms. |
202 | * |
203 | * \sa LiteralTerm |
204 | * |
205 | * \since 4.6 |
206 | */ |
207 | QString excerpt() const; |
208 | |
209 | /** |
210 | * Comparison operator |
211 | */ |
212 | bool operator==( const Result& ) const; |
213 | |
214 | private: |
215 | class Private; |
216 | QSharedDataPointer<Private> d; |
217 | }; |
218 | } |
219 | } |
220 | |
221 | #endif |
222 | |