| 1 |
NAME |
| 2 |
RDF::Query::Client - get data from W3C SPARQL Protocol 1.0 servers |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use RDF::Query::Client; |
| 6 |
|
| 7 |
my $query = RDF::Query::Client |
| 8 |
->new('SELECT DISTINCT ?s WHERE { ?s ?p ?o . }'); |
| 9 |
|
| 10 |
my $iterator = $query->execute('http://example.com/sparql'); |
| 11 |
|
| 12 |
while (my $row = $iterator->next) { |
| 13 |
print $row->{s}->as_string; |
| 14 |
} |
| 15 |
|
| 16 |
DESCRIPTION |
| 17 |
Constructor |
| 18 |
`new ( $sparql, \%opts )` |
| 19 |
Returns a new RDF::Query::Client object for the specified $sparql. The |
| 20 |
object's interface is designed to be roughly compatible with |
| 21 |
RDF::Query objects, though RDF::Query is not required by this module. |
| 22 |
|
| 23 |
Options include: |
| 24 |
|
| 25 |
UserAgent - an LWP::UserAgent to handle HTTP requests. |
| 26 |
|
| 27 |
Unlike RDF::Query, where you get a choice of query language, the query |
| 28 |
language for RDF::Query::Client is always 'sparql'. |
| 29 |
RDF::TrineShortcuts offers a way to perform RDQL queries on remote |
| 30 |
SPARQL stores though (by transforming RDQL to SPARQL). |
| 31 |
|
| 32 |
Public Methods |
| 33 |
`execute ( $endpoint, \%opts )` |
| 34 |
$endpoint is a URI object or string containing the endpoint URI to be |
| 35 |
queried. |
| 36 |
|
| 37 |
Options include: |
| 38 |
|
| 39 |
* UserAgent - an LWP::UserAgent to handle HTTP requests. |
| 40 |
|
| 41 |
* QueryMethod - 'GET', 'POST', 'PATCH' or undef (automatic). |
| 42 |
|
| 43 |
* QueryParameter - defaults to 'query'. |
| 44 |
|
| 45 |
* AuthUsername - HTTP Basic authorization. |
| 46 |
|
| 47 |
* AuthPassword - HTTP Basic authorization. |
| 48 |
|
| 49 |
* Headers - additional headers to include (hashref). |
| 50 |
|
| 51 |
* Parameters - additional GET/POST fields to include (hashref). |
| 52 |
|
| 53 |
* ContentType - 'application/sparql-query', |
| 54 |
'application/sparql-update' or 'application/x-www-form-urlencoded' |
| 55 |
(default). |
| 56 |
|
| 57 |
Returns undef on error; an RDF::Trine::Iterator if called in a scalar |
| 58 |
context; an array obtained by calling `get_all` on the iterator if |
| 59 |
called in list context. |
| 60 |
|
| 61 |
`discover_execute( $resource_uri, \%opts )` |
| 62 |
Experimental feature. Discovers a SPARQL endpoint relevant to |
| 63 |
$resource_uri and then calls `$query->execute` against that. Uses an |
| 64 |
LRDD-like method to discover the endpoint. If you're publishing data |
| 65 |
and want people to be able to find your SPARQL endpoint automatically, |
| 66 |
the easiest way is to include an Link header in HTTP responses: |
| 67 |
|
| 68 |
Link: </my/endpoint>; rel="http://ontologi.es/sparql#endpoint" |
| 69 |
|
| 70 |
Change the URL in the angled brackets, but not the URL in the rel |
| 71 |
string. |
| 72 |
|
| 73 |
This feature requires the HTTP::LRDD package to be installed. |
| 74 |
|
| 75 |
`get ( $endpoint, \%opts )` |
| 76 |
Executes the query using the specified endpoint, and returns the first |
| 77 |
matching row as a LIST of values. Takes the same arguments as |
| 78 |
`execute`. |
| 79 |
|
| 80 |
`as_sparql` |
| 81 |
Returns the query as a string in the SPARQL syntax. |
| 82 |
|
| 83 |
`useragent` |
| 84 |
Returns the LWP::UserAgent object used for retrieving web content. |
| 85 |
|
| 86 |
`http_response` |
| 87 |
Returns the last HTTP Response the client experienced. |
| 88 |
|
| 89 |
`error` |
| 90 |
Returns the last error the client experienced. |
| 91 |
|
| 92 |
Security |
| 93 |
The `execute` and `get` methods allow AuthUsername and AuthPassword |
| 94 |
options to be passed to them for HTTP Basic authentication. For more |
| 95 |
complicated authentication (Digest, OAuth, Windows, etc), it is also |
| 96 |
possible to pass these methods a customised LWP::UserAgent. |
| 97 |
|
| 98 |
If you have the Crypt::SSLeay package installed, requests to HTTPS |
| 99 |
endpoints should work. It's possible to specify a client X.509 certificate |
| 100 |
(e.g. for WebID authentication) by setting particular environment |
| 101 |
variables. See Crypt::SSLeay documentation for details. |
| 102 |
|
| 103 |
BUGS |
| 104 |
Probably. |
| 105 |
|
| 106 |
Please report any you find here: |
| 107 |
<https://rt.cpan.org/Dist/Display.html?Queue=RDF-Query-Client>. |
| 108 |
|
| 109 |
SEE ALSO |
| 110 |
* RDF::Trine, RDF::Trine::Iterator |
| 111 |
|
| 112 |
* RDF::Query |
| 113 |
|
| 114 |
* LWP::UserAgent |
| 115 |
|
| 116 |
* <http://www.w3.org/TR/rdf-sparql-protocol/> |
| 117 |
|
| 118 |
* <http://www.w3.org/TR/rdf-sparql-query/> |
| 119 |
|
| 120 |
* <http://www.perlrdf.org/> |
| 121 |
|
| 122 |
AUTHOR |
| 123 |
Toby Inkster, <[email protected]> |
| 124 |
|
| 125 |
COPYRIGHT AND LICENSE |
| 126 |
Copyright (C) 2009-2013 by Toby Inkster |
| 127 |
|
| 128 |
This library is free software; you can redistribute it and/or modify it |
| 129 |
under the same terms as Perl itself. |
| 130 |
|
| 131 |
DISCLAIMER OF WARRANTIES |
| 132 |
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED |
| 133 |
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| 134 |
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 135 |
|