SMWSparqlDatabase Class Reference
[SWMSparql]

Basic database connector for exchanging data via SPARQL. More...

Inherited by SMWSparqlDatabase4Store, and SMWSparqlDatabaseVirtuoso.

List of all members.

Public Member Functions

__construct ($graph, $queryEndpoint, $updateEndpoint= '', $dataEndpoint= '')

Constructor.

getDefaultGraph ()

Get the URI of the default graph that this database connector is using, or the empty string if none is used (no graph related statements in queries/updates).

ping ($endpointType=self::EP_TYPE_QUERY)

Check if the database can be contacted.

select ($vars, $where, $options=array(), $extraNamespaces=array())

SELECT wrapper.

getSparqlForSelect ($vars, $where, $options=array(), $extraNamespaces=array())

Build the SPARQL query that is used by SMWSparqlDatabase::select().

ask ($where, $extraNamespaces=array())

ASK wrapper.

getSparqlForAsk ($where, $extraNamespaces=array())

Build the SPARQL query that is used by SMWSparqlDatabase::ask().

selectCount ($variable, $where, $options=array(), $extraNamespaces=array())

SELECT wrapper for counting results.

delete ($deletePattern, $where, $extraNamespaces=array())

DELETE wrapper.

deleteContentByValue ($propertyName, $objectName, $extraNamespaces=array())

Convenience method for deleting all triples that have a subject that occurs in a triple with the given property and object.

insertDelete ($insertPattern, $deletePattern, $where, $extraNamespaces=array())

INSERT DELETE wrapper.

insertData ($triples, $extraNamespaces=array())

INSERT DATA wrapper.

deleteData ($triples, $extraNamespaces=array())

DELETE DATA wrapper.

doQuery ($sparql)

Execute a SPARQL query and return an SMWSparqlResultWrapper object that contains the results.

doUpdate ($sparql)

Execute a SPARQL update and return a boolean to indicate if the operations was successful.

doHttpPost ($payload)

Execute a HTTP-based SPARQL POST request according to http://www.w3.org/2009/sparql/docs/http-rdf-update/.

Static Public Member Functions

static getPrefixString ($extraNamespaces=array(), $forSparql=true)

Create the standard PREFIX declarations for SPARQL or Turtle, possibly with additional namespaces involved.

Public Attributes

const EP_TYPE_QUERY = 1

Flag denoting endpoints being capable of querying.

const EP_TYPE_UPDATE = 2

Flag denoting endpoints being capable of updating.

const EP_TYPE_DATA = 4

Flag denoting endpoints being capable of SPARQL HTTP graph management.

Protected Member Functions

throwSparqlErrors ($endpoint, $sparql)

Decide what to make of the errors reported by the Curl handler.

Protected Attributes

$m_queryEndpoint

$m_updateEndpoint

$m_dataEndpoint

$m_defaultGraph

$m_curlhandle

Detailed Description

Basic database connector for exchanging data via SPARQL.

Author:: Markus Krötzsch

Definition at line 103 of file SMW_SparqlDatabase.php.

Constructor & Destructor Documentation

SMWSparqlDatabase::__construct	(	$	graph,
		$	queryEndpoint,
		$	updateEndpoint = `''`,
		$	dataEndpoint = `''`
	)

Constructor.

Normally, you should call smwfGetSparqlDatabase() to obtain a suitable instance of a SPARQL database handler rather than constructing one directly.

Parameters:

	$graph	string of URI of the default graph to store data to; can be the empty string to omit this information in all requests (not supported by all stores)
	$queryEndpoint	string of URL of query service (reading)
	$updateEndpoint	string of URL of update service (writing)
	$dataEndpoint	string of URL of POST service (writing, optional)

Definition at line 166 of file SMW_SparqlDatabase.php.

Member Function Documentation

SMWSparqlDatabase::getDefaultGraph ( )

Get the URI of the default graph that this database connector is using, or the empty string if none is used (no graph related statements in queries/updates).

Returns:: string graph UIR or empty

Definition at line 186 of file SMW_SparqlDatabase.php.

SMWSparqlDatabase::ping ( $ endpointType = self::EP_TYPE_QUERY )

Check if the database can be contacted.

Parameters:

$pingQueryEndpoint

boolean true if the query endpoint should be pinged, false if the update enpoint should be pinged

Returns:: boolean to indicate success

Todo:: SPARQL endpoints sometimes return errors if no (valid) query is posted. The current implementation tries to catch this, but this might not be entirely correct. Especially, the SPARQL 1.1 HTTP error codes for Update are not defined yet (April 15 2011).

Definition at line 201 of file SMW_SparqlDatabase.php.

References doHttpPost().

SMWSparqlDatabase::select	(	$	vars,
		$	where,
		$	options = `array()`,
		$	extraNamespaces = `array()`
	)

SELECT wrapper.

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$vars	mixed array or string, field name(s) to be retrieved, can be '*'
	$where	string WHERE part of the query, without surrounding { }
	$options	array (associative) of options, e.g. array( 'LIMIT' => '10' )
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: SMWSparqlResultWrapper

Definition at line 241 of file SMW_SparqlDatabase.php.

References doQuery(), and getSparqlForSelect().

Referenced by SMWSparqlDatabase4Store::deleteContentByValue().

SMWSparqlDatabase::getSparqlForSelect	(	$	vars,
		$	where,
		$	options = `array()`,
		$	extraNamespaces = `array()`
	)

Build the SPARQL query that is used by SMWSparqlDatabase::select().

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$where	string WHERE part of the query, without surrounding { }
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: string SPARQL query

Definition at line 256 of file SMW_SparqlDatabase.php.

Referenced by select().

SMWSparqlDatabase::ask	(	$	where,
		$	extraNamespaces = `array()`
	)

ASK wrapper.

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$where	string WHERE part of the query, without surrounding { }
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: SMWSparqlResultWrapper

Definition at line 289 of file SMW_SparqlDatabase.php.

References doQuery(), and getSparqlForAsk().

SMWSparqlDatabase::getSparqlForAsk	(	$	where,
		$	extraNamespaces = `array()`
	)

Build the SPARQL query that is used by SMWSparqlDatabase::ask().

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$where	string WHERE part of the query, without surrounding { }
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: string SPARQL query

Definition at line 304 of file SMW_SparqlDatabase.php.

Referenced by ask().

SMWSparqlDatabase::selectCount	(	$	variable,
		$	where,
		$	options = `array()`,
		$	extraNamespaces = `array()`
	)

SELECT wrapper for counting results.

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$variable	string variable name or '*'
	$where	string WHERE part of the query, without surrounding { }
	$options	array (associative) of options, e.g. array('LIMIT' => '10')
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: SMWSparqlResultWrapper

Definition at line 320 of file SMW_SparqlDatabase.php.

References doQuery().

SMWSparqlDatabase::delete	(	$	deletePattern,
		$	where,
		$	extraNamespaces = `array()`
	)

DELETE wrapper.

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$deletePattern	string CONSTRUCT pattern of tripples to delete
	$where	string condition for data to delete
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: boolean stating whether the operations succeeded

Reimplemented in SMWSparqlDatabaseVirtuoso.

Definition at line 347 of file SMW_SparqlDatabase.php.

References doUpdate().

SMWSparqlDatabase::deleteContentByValue	(	$	propertyName,
		$	objectName,
		$	extraNamespaces = `array()`
	)

Convenience method for deleting all triples that have a subject that occurs in a triple with the given property and object.

This is used in SMW to delete subobjects with all their data. Some RDF stores fail on complex delete queries, hence a wrapper function is provided to allow more pedestrian implementations.

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$propertyName	string Turtle name of marking property
	$objectName	string Turtle name of marking object/value
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: boolean stating whether the operations succeeded

Reimplemented in SMWSparqlDatabase4Store.

Definition at line 370 of file SMW_SparqlDatabase.php.

References smwfGetSparqlDatabase().

SMWSparqlDatabase::insertDelete	(	$	insertPattern,
		$	deletePattern,
		$	where,
		$	extraNamespaces = `array()`
	)

INSERT DELETE wrapper.

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$insertPattern	string CONSTRUCT pattern of tripples to insert
	$deletePattern	string CONSTRUCT pattern of tripples to delete
	$where	string condition for data to delete
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: boolean stating whether the operations succeeded

Reimplemented in SMWSparqlDatabaseVirtuoso.

Definition at line 386 of file SMW_SparqlDatabase.php.

References doUpdate().

SMWSparqlDatabase::insertData	(	$	triples,
		$	extraNamespaces = `array()`
	)

INSERT DATA wrapper.

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$triples	string of triples to insert
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: boolean stating whether the operations succeeded

Reimplemented in SMWSparqlDatabaseVirtuoso.

Definition at line 403 of file SMW_SparqlDatabase.php.

References doHttpPost(), and doUpdate().

SMWSparqlDatabase::deleteData	(	$	triples,
		$	extraNamespaces = `array()`
	)

DELETE DATA wrapper.

The function declares the standard namespaces wiki, swivt, rdf, owl, rdfs, property, xsd, so these do not have to be included in $extraNamespaces.

Parameters:

	$triples	string of triples to delete
	$extraNamespaces	array (associative) of namespaceId => namespaceUri

Returns:: boolean stating whether the operations succeeded

Reimplemented in SMWSparqlDatabaseVirtuoso.

Definition at line 426 of file SMW_SparqlDatabase.php.

References doUpdate().

SMWSparqlDatabase::doQuery ( $ sparql )

Execute a SPARQL query and return an SMWSparqlResultWrapper object that contains the results.

The method throws exceptions based on SMWSparqlDatabase::throwSparqlErrors(). If errors occur and this method does not throw anything, then an empty result with an error code is returned.

Note:: This function sets the graph that is to be used as part of the request. Queries should not include additional graph information.

Parameters:

$sparql

string with the complete SPARQL query (SELECT or ASK)

Returns:: SMWSparqlResultWrapper

Reimplemented in SMWSparqlDatabase4Store.

Definition at line 448 of file SMW_SparqlDatabase.php.

References SMWSparqlResultWrapper::ERROR_UNREACHABLE, and throwSparqlErrors().

Referenced by ask(), select(), and selectCount().

SMWSparqlDatabase::doUpdate ( $ sparql )

Execute a SPARQL update and return a boolean to indicate if the operations was successful.

The method throws exceptions based on SMWSparqlDatabase::throwSparqlErrors(). If errors occur and this method does not throw anything, then false is returned.

Note:: When this is written, it is not clear if the update protocol supports a default-graph-uri parameter. Hence the target graph for all updates is generally encoded in the query string and not fixed when sending the query. Direct callers to this function must include the graph information in the queries that they build.

Parameters:

$sparql

string with the complete SPARQL update query (INSERT or DELETE)

Returns:: boolean

Reimplemented in SMWSparqlDatabaseVirtuoso.

Definition at line 483 of file SMW_SparqlDatabase.php.

References SMWSparqlDatabaseError::ERROR_NOSERVICE, and throwSparqlErrors().

Referenced by delete(), deleteData(), insertData(), and insertDelete().

SMWSparqlDatabase::doHttpPost ( $ payload )

Execute a HTTP-based SPARQL POST request according to http://www.w3.org/2009/sparql/docs/http-rdf-update/.

The method throws exceptions based on SMWSparqlDatabase::throwSparqlErrors(). If errors occur and this method does not throw anything, then an empty result with an error code is returned.

Note:: This protocol is not part of the SPARQL standard and may not be supported by all stores. To avoid using it, simply do not provide a data endpoint URL when configuring the SPARQL database. If used, the protocol might lead to a better performance since there is less parsing required to fetch the data from the request.
Some stores (e.g. 4Store) support another mode of posting data that may be implemented in a special database handler.

Parameters:

$payload

string Turtle serialization of data to send

Returns:: SMWSparqlResultWrapper

TODO The error reporting based on SPARQL (Update) is not adequate for the HTTP POST protocol

Reimplemented in SMWSparqlDatabase4Store.

Definition at line 521 of file SMW_SparqlDatabase.php.

References SMWSparqlDatabaseError::ERROR_NOSERVICE, and throwSparqlErrors().

Referenced by SMWSparqlDatabaseVirtuoso::insertData(), insertData(), and ping().

static SMWSparqlDatabase::getPrefixString	(	$	extraNamespaces = `array()`,
		$	forSparql = `true`
	)			`[static]`

Create the standard PREFIX declarations for SPARQL or Turtle, possibly with additional namespaces involved.

Parameters:

	$extraNamespaces	array (associative) of namespaceId => namespaceUri
	$forSparql	boolean true to use SPARQL prefix syntax, false to use Turtle prefix syntax

Definition at line 554 of file SMW_SparqlDatabase.php.

References SMWExporter::getNamespaceUri().

SMWSparqlDatabase::throwSparqlErrors	(	$	endpoint,
		$	sparql
	)			`[protected]`

Decide what to make of the errors reported by the Curl handler.

Either throw a suitable exception or fall through if the error should be handled gracefully. It is attempted to throw exceptions for all errors that can generally be prevented by proper coding or configuration (e.g. query syntax errors), and to be silent on all errors that might be caused by network issues or temporary overloading of the server. In this case, calling methods rather return something that helps to make the best out of the situation.

Parameters:

	$endpoint	string URL of endpoint that was used
	$sparql	string query that caused the problem

TODO We are guessing the meaning of HTTP codes here -- the SPARQL 1.1 spec does not yet provide this information for updates (April 15 2011)

Definition at line 581 of file SMW_SparqlDatabase.php.

References SMWSparqlDatabaseError::ERROR_MALFORMED, SMWSparqlDatabaseError::ERROR_OTHER, and SMWSparqlDatabaseError::ERROR_REFUSED.

Referenced by SMWSparqlDatabase4Store::doHttpPost(), doHttpPost(), SMWSparqlDatabase4Store::doQuery(), doQuery(), SMWSparqlDatabaseVirtuoso::doUpdate(), and doUpdate().

Member Data Documentation

const SMWSparqlDatabase::EP_TYPE_QUERY = 1

Flag denoting endpoints being capable of querying.

Definition at line 106 of file SMW_SparqlDatabase.php.

const SMWSparqlDatabase::EP_TYPE_UPDATE = 2

Flag denoting endpoints being capable of updating.

Definition at line 108 of file SMW_SparqlDatabase.php.

const SMWSparqlDatabase::EP_TYPE_DATA = 4

Flag denoting endpoints being capable of SPARQL HTTP graph management.

Definition at line 110 of file SMW_SparqlDatabase.php.

SMWSparqlDatabase::$m_queryEndpoint [protected]

Definition at line 117 of file SMW_SparqlDatabase.php.

SMWSparqlDatabase::$m_updateEndpoint [protected]

Definition at line 125 of file SMW_SparqlDatabase.php.

SMWSparqlDatabase::$m_dataEndpoint [protected]

Definition at line 133 of file SMW_SparqlDatabase.php.

SMWSparqlDatabase::$m_defaultGraph [protected]

Definition at line 142 of file SMW_SparqlDatabase.php.

SMWSparqlDatabase::$m_curlhandle [protected]

Definition at line 150 of file SMW_SparqlDatabase.php.

The documentation for this class was generated from the following file:

SemanticMediaWiki/includes/sparql/SMW_SparqlDatabase.php


Public Member Functions
	__construct ($graph, $queryEndpoint, $updateEndpoint= '', $dataEndpoint= '')
	Constructor.
	getDefaultGraph ()
	Get the URI of the default graph that this database connector is using, or the empty string if none is used (no graph related statements in queries/updates).
	ping ($endpointType=self::EP_TYPE_QUERY)
	Check if the database can be contacted.
	select ($vars, $where, $options=array(), $extraNamespaces=array())
	SELECT wrapper.
	getSparqlForSelect ($vars, $where, $options=array(), $extraNamespaces=array())
	Build the SPARQL query that is used by SMWSparqlDatabase::select().
	ask ($where, $extraNamespaces=array())
	ASK wrapper.
	getSparqlForAsk ($where, $extraNamespaces=array())
	Build the SPARQL query that is used by SMWSparqlDatabase::ask().
	selectCount ($variable, $where, $options=array(), $extraNamespaces=array())
	SELECT wrapper for counting results.
	delete ($deletePattern, $where, $extraNamespaces=array())
	DELETE wrapper.
	deleteContentByValue ($propertyName, $objectName, $extraNamespaces=array())
	Convenience method for deleting all triples that have a subject that occurs in a triple with the given property and object.
	insertDelete ($insertPattern, $deletePattern, $where, $extraNamespaces=array())
	INSERT DELETE wrapper.
	insertData ($triples, $extraNamespaces=array())
	INSERT DATA wrapper.
	deleteData ($triples, $extraNamespaces=array())
	DELETE DATA wrapper.
	doQuery ($sparql)
	Execute a SPARQL query and return an SMWSparqlResultWrapper object that contains the results.
	doUpdate ($sparql)
	Execute a SPARQL update and return a boolean to indicate if the operations was successful.
	doHttpPost ($payload)
	Execute a HTTP-based SPARQL POST request according to http://www.w3.org/2009/sparql/docs/http-rdf-update/.
Static Public Member Functions
static	getPrefixString ($extraNamespaces=array(), $forSparql=true)
	Create the standard PREFIX declarations for SPARQL or Turtle, possibly with additional namespaces involved.
Public Attributes
const	EP_TYPE_QUERY = 1
	Flag denoting endpoints being capable of querying.
const	EP_TYPE_UPDATE = 2
	Flag denoting endpoints being capable of updating.
const	EP_TYPE_DATA = 4
	Flag denoting endpoints being capable of SPARQL HTTP graph management.
Protected Member Functions
	throwSparqlErrors ($endpoint, $sparql)
	Decide what to make of the errors reported by the Curl handler.
Protected Attributes
	$m_queryEndpoint
	$m_updateEndpoint
	$m_dataEndpoint
	$m_defaultGraph
	$m_curlhandle

SMWSparqlDatabase Class Reference [SWMSparql]

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

SMWSparqlDatabase Class Reference
[SWMSparql]