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
33namespace 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