Debian Codegraph @

README

raw
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