MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

The QSparqlResult class provides an abstract interface for accessing the results of an executed QSparqlQuery. More...

Inheritance diagram for QSparqlResult:
QObject

List of all members.

Public Types

enum   Feature { QuerySize, ForwardOnly, Sync }

Signals

void  dataReady (int totalCount)
void  finished ()

Public Member Functions

virtual  ~QSparqlResult ()
int  pos () const
virtual bool  setPos (int pos)
virtual bool  next ()
virtual bool  previous ()
virtual bool  first ()
virtual bool  last ()
virtual int  size () const
bool  isValid () const
virtual QSparqlResultRow  current () const =0
virtual QSparqlBinding  binding (int i) const =0
virtual QVariant  value (int i) const =0
virtual QString  stringValue (int i) const
bool  boolValue () const
virtual void  waitForFinished ()
virtual bool  isFinished () const
bool  hasError () const
QSparqlError  lastError () const
QString  query () const
QSparqlQuery::StatementType  statementType () const
  Returns the statement type of this QSparqlResult object.
bool  isTable () const
bool  isGraph () const
bool  isBool () const
virtual bool  hasFeature (QSparqlResult::Feature feature) const

Protected Member Functions

  QSparqlResult ()
void  setQuery (const QString &query)
void  setStatementType (QSparqlQuery::StatementType type)
  Sets the statement type of this QSparqlResult object.
void  setLastError (const QSparqlError &e)
void  setBoolValue (bool v)
void  updatePos (int pos)

Friends

class  QSparqlResultPrivate
class  QSparqlConnection
class  QSparqlConnectionPrivate

Detailed Description

The QSparqlResult class provides an abstract interface for accessing the results of an executed QSparqlQuery.

When QSparqlConnection::exec() is called, it asynchronously begins the execution of the given query. The returned result is in an unfinished state so that isFinished() returns false. When the execution finished, QSparqlResult emits the finished() signal and sets itself to finished state.

Initially, QSparqlResult is positioned on an invalid position. It must be navigated to a valid position (so that isValid() returns true) before values can be retrieved.

Navigating the result is performed with the following functions:

Retrieving the data is performed with the following functions:


Member Enumeration Documentation

This enum contains a list of features a QSparqlResult might support. Use hasFeature() to query whether a feature is supported or not. The supported features depend on the driver and whether the result was obtained via QSparqlConnection::exec() or QSparqlConnection::syncExec().

Enumerator:
QuerySize 

Whether the QSparqlResult can report the number of results of the query.

ForwardOnly 

Whether the result can only be navigated forward (i.e., using QSparqlResult::next()).

Sync 

Whether the result is natively synchronous (was retrieved via QSparqlConnection::syncExec() of natively synchronous connection). In this case, QSparqlResult::next() will fetch the next result synchronously.

See also:
hasFeature()

Constructor & Destructor Documentation

QSparqlResult::~QSparqlResult (  )  [virtual]

Destroys the object and frees any allocated resources.

QSparqlResult::QSparqlResult (  )  [protected]

Creates a QSparqlResult. The result is empty, positioned at "before first row" and unfinished.


Member Function Documentation

QSparqlBinding QSparqlResult::binding ( int  index  )  const [pure virtual]

Returns the binding index in the current result row.

The bindings are numbered from left to right using the text of the SELECT statement. The indexes start from 0.

An invalid QSparqlBinding is returned if binding index does not exist, if the query is inactive, or if the query is positioned on an invalid result row.

See also:
value() previous() next() first() last() setPos() isValid()
bool QSparqlResult::boolValue (  )  const

Returns the boolean result of an ASK query.

Note that this should only be used when isFinished() is true.

See also:
isBool() setBoolValue()
QSparqlResultRow QSparqlResult::current (  )  const [pure virtual]

Returns a QSparqlResultRow containing the binding values for the current row. If the result points to a valid row (isValid() returns true), the result row is populated. An empty result row is returned when there is no result at the current position.

To retrieve just the values from a query, value() should be used since its index-based lookup is faster. Use QSparqlResultRow::binding() to retrieve the value along with meta data, such as the data type URI or language tag for literals.

See also:
value() binding() pos() setPos()
void QSparqlResult::dataReady ( int  totalRows  )  [signal]

This signal is emitted when a query has fetched data. The totalRows is the row count of the data set after the new data has arrived.

void QSparqlResult::finished (  )  [signal]

This signal is emitted when the QSparqlResult has finished retrieving its data or when there was an error.

bool QSparqlResult::first (  )  [virtual]

Retrieves the first row in the result, if available, and positions the query on the retrieved row. Returns true if successful. If unsuccessful the query position is set to an invalid position and false is returned.

See also:
next() previous() last() setPos() pos() isFinished() isValid()
bool QSparqlResult::hasError (  )  const

Returns true if the query has finished and there is an error associated with the result.

See also:
setLastError() lastError() isFinished()
bool QSparqlResult::hasFeature ( QSparqlResult::Feature  feature  )  const [virtual]

Returns true if the QSparqlResult supports feature feature; otherwise returns false.

bool QSparqlResult::isBool (  )  const

Returns true if the statement is an ASK query returning a boolean value

See also:
isTable() isGraph() boolValue()
bool QSparqlResult::isFinished (  )  const [virtual]

Returns true if the pending query has finished processing and the result has been received. If this function returns true, the hasError() and lastError() methods should return valid information.

The usage of this function differs depending on the driver, and method of execution used. For asynchronous queries the results will be available once the finished() signal has been emitted, or waitForFinished() has been called. For synchronous execution, where the driver supports QSparqlConnection::SyncExec, the value of isFinished() will be false until all the results have been retrieved using next().

E.g For a synchronous result

        QSparqlResult *result = connection.syncExec(query);
        // result->isFinished() will be false
        while(result->next())
            do something
        // result->isFinished() will now be true 

And for asynchronous execution

        QSparqlResult *result = connection.exec(query);
        result->waitForFinished();
        result->isFinished(); // will be true 

Note that this function only changes state if you call waitForFinished(), or if an external event happens, which in general only happens if you return to the event loop execution.

See also:
waitForFinished() lastError() error()
bool QSparqlResult::isGraph (  )  const

Returns true if the statement is a CONSTRUCT or DESCRIBE query returning a graph. Each QSparqlResultRow in a graph result hasError three QSParqlBinding values, named 's', 'p' and 'o' corresponding to triples with Subject, Predicate and Object values

See also:
isTable() isBool()
bool QSparqlResult::isTable (  )  const

Returns true if this QSparqlResult object represents results that are in the tabular format, e.g., the results of a SELECT query.

bool QSparqlResult::isValid (  )  const

Returns true if the result is positioned on a valid row (that is, the result is not positioned before the first or after the last row); otherwise returns false.

See also:
pos()
bool QSparqlResult::last (  )  [virtual]

Retrieves the last row in the result, if available, and positions the query on the retrieved row. Note that the result must be in the finished state before calling this function or it will do nothing and return false. Returns true if successful. If unsuccessful the query position is set to an invalid position and false is returned.

See also:
next() previous() first() setPos() pos() isFinished() isValid()
QSparqlError QSparqlResult::lastError (  )  const

Once the query has finished, returns the last error associated with the result

See also:
setLastError() hasError() isFinished()
bool QSparqlResult::next (  )  [virtual]

Retrieves the next row in the result, if available, and positions the query on the retrieved row. Note that the isTable() or isGraph() must return true before calling this function or it will do nothing and return false.

The following rules apply:

  • If the result is currently located before the first row, e.g. immediately after a query is executed, an attempt is made to retrieve the first row.
  • If the result is currently located after the last row, there is no change and false is returned.
  • If the result is located somewhere in the middle, an attempt is made to retrieve the next row.

If the row could not be retrieved, the result is positioned after the last row and false is returned. If the row is successfully retrieved, true is returned.

See also:
previous() first() last() setPos() pos() isFinished() isValid()
int QSparqlResult::pos (  )  const

Returns the current internal position of the query. The first row is at position zero. If the position is invalid, the function returns QSparql::BeforeFirstRow or QSparql::AfterLastRow, which are special negative values.

See also:
previous() next() first() last()
bool QSparqlResult::previous (  )  [virtual]

Retrieves the previous row in the result, if available, and positions the query on the retrieved row.

The following rules apply:

  • If the result is currently located before the first row, there is no change and false is returned.
  • If the result is currently located after the last row, an attempt is made to retrieve the last row.
  • If the result is somewhere in the middle, an attempt is made to retrieve the previous row.

If the row could not be retrieved, the result is positioned before the first row and false is returned. If the row is successfully retrieved, true is returned.

See also:
next() first() last() setPos() pos() isFinished() isValid()
QString QSparqlResult::query (  )  const

Returns the query which was executed for creating this QSparqlResult. Useful for debugging purposes.

void QSparqlResult::setBoolValue ( bool  v  )  [protected]

Set the boolean result of an ASK query

See also:
isBool() boolValue()
void QSparqlResult::setLastError ( const QSparqlError error  )  [protected]

This function is provided for derived classes to set the last error to error.

See also:
lastError() hasError()
bool QSparqlResult::setPos ( int  pos  )  [virtual]

This function is provided to set the internal (zero-based) row position to index. If the index is within the range of result rows retrieved the function returns true, otherwise false.

See also:
pos()
void QSparqlResult::setQuery ( const QString query  )  [protected]

Sets the information about the query whose results this QSparqlResult object represents.

int QSparqlResult::size (  )  const [virtual]

Returns the size of the result (number of rows returned).

A return value of -1 is used if the result does not support QuerySize information, or if the query has not yet finished (isFinished() returns false)

See also:
isFinished() QSparqlResult::hasFeature()
QString QSparqlResult::stringValue ( int  i  )  const [virtual]

Returns the value on column column on the current result row as a string. This function ignores the type of the data.

An empty QString is returned if column column does not exist, or if the result is positioned on an invalid result row.

See also:
binding() value() current()
void QSparqlResult::updatePos ( int  index  )  [protected]

This function is provided for derived classes which handle position tracking themselves, allowing them to record the current position in the results

QVariant QSparqlResult::value ( int  index  )  const [pure virtual]

Returns the value of binding index in the current result row.

The binding values are numbered from left to right using the text of the SELECT statement. The indexes start from 0.

An invalid QVariant is returned if binding value index does not exist, if the query is inactive, or if the query is positioned on an invalid result row.

See also:
binding() previous() next() first() last() setPos() isValid()
void QSparqlResult::waitForFinished (  )  [virtual]

Suspends the execution of the calling thread until all the query results have arrived. After this function returns, isFinished() should return true, indicating the result's contents are ready to be processed.

Warning:
Calling this function from the main thread (the thread that calls QApplication::exec()) may cause your user interface to freeze.
Calling this function may cause the events in your event queue to be processed.
See also:
isFinished()

Copyright (C) 2010-2011 Nokia Corporation and/or its subsidiary(-ies).
Commercial Qt/LGPL 2.1 with Nokia exception/GPL 3.0
MeeGo 1.2 Harmattan API