Debian Codegraph @

README

raw ◀ ▶
1 Debian patch touch this file
1 NAME
2
3 Catmandu::FedoraCommons - Low level Catmandu interface to the Fedora
4 Commons REST API
5
6 SYNOPSIS
7
8 # Use the command line tools
9 $ fedora_admin.pl
10
11 # Or the low-level API-s
12 use Catmandu::FedoraCommons;
13
14 my $fedora = Catmandu::FedoraCommons->new('http://localhost:8080/fedora','fedoraAdmin','fedoraAdmin');
15
16 my $result = $fedora->findObjects(terms=>'*');
17
18 die $result->error unless $result->is_ok;
19
20 my $hits = $result->parse_content();
21
22 for my $hit (@{ $hits->{results} }) {
23 printf "%s\n" , $hit->{pid};
24 }
25
26 # Or using the higher level Catmandu::Store codes you can do things like
27
28 use Catmandu::Store::FedoraCommons;
29
30 my $store = Catmandu::Store::FedoraCommons->new(
31 baseurl => 'http://localhost:8080/fedora',
32 username => 'fedoraAdmin',
33 password => 'fedoraAdmin',
34 model => 'Catmandu::Store::FedoraCommons::DC' # default
35 );
36
37 $store->bag->each(sub {
38 my $model = shift;
39 printf "title: %s\n" , join("" , @{ $model->{title} });
40 printf "creator: %s\n" , join("" , @{ $model->{creator} });
41
42 my $pid = $model->{_id};
43 my $ds = $store->fedora->listDatastreams(pid => $pid)->parse_content;
44 });
45
46 my $obj = $store->bag->add({
47 title => ['The Master and Margarita'] ,
48 creator => ['Bulgakov, Mikhail'] }
49 );
50
51 $store->fedora->addDatastream(pid => $obj->{_id} , url => "http://myurl/rabbit.jpg");
52
53 # Add your own perl version of a descriptive metadata model by implementing your own
54 # model that can do a serialize and deserialize.
55
56 DESCRIPTION
57
58 Catmandu::FedoraCommons is an Perl API to the Fedora Commons REST API
59 (http://www.fedora.info/). Supported versions are Fedora Commons 3.6 or
60 better.
61
62 ACCESS METHODS
63
64 new($base_url,$username,$password)
65
66 Create a new Catmandu::FedoraCommons connecting to the baseurl of the
67 Fedora Commons installation.
68
69 findObjects(query => $query, maxResults => $maxResults)
70
71 findObjects(terms => $terms , maxResults => $maxResults)
72
73 Execute a search query on the Fedora Commons server. One of 'query' or
74 'terms' is required. Query contains a phrase optionally including '*'
75 and '?' wildcards. Terms contain one or more conditions separated by
76 space. A condition is a field followed by an operator, followed by a
77 value. The = operator will match if the field's entire value matches
78 the value given. The ~ operator will match on phrases within fields,
79 and accepts the ? and * wildcards. The <, >, <=, and >= operators can
80 be used with numeric values, such as dates.
81
82 Examples:
83
84 query => "*o*"
85
86 query => "?edora"
87
88 terms => "pid~demo:* description~fedora"
89
90 terms => "cDate>=1976-03-04 creator~*n*"
91
92 terms => "mDate>2002-10-2 mDate<2002-10-2T12:00:00"
93
94 Optionally a maxResults parameter may be specified limiting the number
95 of search results (default is 20). This method returns a
96 Catmandu::FedoraCommons::Response object with a
97 Catmandu::FedoraCommons::Model::findObjects model.
98
99 resumeFindObjects(sessionToken => $token)
100
101 This method returns the next batch of search results. This method
102 returns a Catmandu::FedoraCommons::Response object with a
103 Catmandu::FedoraCommons::Model::findObjects model.
104
105 Example:
106
107 my $result = $fedora->findObjects(terms=>'*');
108
109 die $result->error unless $result->is_ok;
110
111 my $hits = $result->parse_content();
112
113 for my $hit (@{ $hits->{results} }) {
114 printf "%s\n" , $hit->{pid};
115 }
116
117 my $result = $fedora->resumeFindObjects(sessionToken => $hits->{token});
118
119 my $hits = $result->parse_content();
120
121 ...
122
123 getDatastreamDissemination(pid => $pid, dsID=> $dsID, asOfDateTime =>
124 $date, callback => \&callback)
125
126 This method returns a datastream from the Fedora Commons repository.
127 Required parameters are the identifier of the object $pid and the
128 identifier of the datastream $dsID. Optionally a datestamp
129 $asOfDateTime can be provided. This method returns a
130 Catmandu::FedoraCommons::Response object with a
131 Catmandu::FedoraCommons::Model::getDatastreamDissemination model.
132
133 To stream the contents of the datastream a callback function can be
134 provided.
135
136 Example:
137
138 $fedora->getDatastreamDissemination(pid => 'demo:5', dsID => 'VERYHIGHRES', callback => \&process);
139
140 sub process {
141 my ($data, $response, $protocol) = @_;
142 print $data;
143 }
144
145 getDissemination(pid => $pid , sdefPid => $sdefPid , method => $method ,
146 %method_parameters , callback => \&callback)
147
148 This method execute a dissemination method on the Fedora Commons
•149 server. Required parameters are the object $pid, the service definition
150 $sdefPid and the name of the method $method. Optionally further method
151 parameters can be provided and a callback function to stream the
152 results (see getDatastreamDissemination). This method returns a
153 Catmandu::FedoraCommons::Response object with a
154 Catmandu::FedoraCommons::Model::getDatastreamDissemination model.
155
156 Example:
157
158 $fedora->getDissemination(pid => 'demo:29', sdefPid => 'demo:27' , method => 'resizeImage' , width => 100, callback => \&process);
159
160 getObjectHistory(pid => $pid)
161
162 This method returns the version history of an object. Required is the
163 object $pid. This method returns a Catmandu::FedoraCommons::Response
164 object with a Catmandu::FedoraCommons::Model::getObjectHistory model.
165
166 Example:
167
168 my $obj = $fedora->getObjectHistory(pid => 'demo:29')->parse_content;
169
170 for @{$obj->{objectChangeDate}} {}
171 print "$_\n;
172 }
173
174 getObjectProfile(pid => $pid, asOfDateTime => $date)
175
176 This method returns a detailed description of an object. Required is
177 the object $pid. Optionally a version date asOfDateTime can be
178 provided. This method returns a Catmandu::FedoraCommons::Response
179 object with a Catmandu::FedoraCommons::Model::getObjectProfile model.
180
181 Example:
182
183 my $obj = $fedora->getObjectProfile(pid => 'demo:29')->parse_content;
184
185 printf "Label: %s\n" , $obj->{objLabel};
186
187 listDatastreams(pid => $pid, asOfDateTime => $date)
188
189 This method returns a list of datastreams provided in the object.
190 Required is the object $pid. Optionally a version date asOfDateTime can
191 be provided. This method returns a Catmandu::FedoraCommons::Response
192 object with a Catmandu::FedoraCommons::Model::listDatastreams model.
193
194 Example:
195
196 my $obj = $fedora->listDatastreams(pid => 'demo:29')->parse_content;
197
198 for (@{ $obj->{datastream}} ) {
199 printf "Label: %s\n" , $_->{label};
200 }
201
202 listMethods(pid => $pid , sdefPid => $sdefPid , asOfDateTime => $date)
203
204 This method return a list of methods that can be executed on an object.
205 Required is the object $pid and the object $sdefPid. Optionally a
206 version date asOfDateTime can be provided. This method returns a
207 Catmandu::FedoraCommons::Response object with a
208 Catmandu::FedoraCommons::Model::listMethods model.
209
210 Example:
211
212 my $obj = $fedora->listMethods(pid => 'demo:29')->parse_content;
213
214 for ( @{ $obj->{sDef} }) {
215 printf "[%s]\n" , $_->{$pid};
216
217 for my $m ( @{ $_->{method} } ) {
218 printf "\t%s\n" , $m->{name};
219 }
220 }
221
222 describeRepository
223
224 This method returns information about the fedora repository. No
225 arguments required. This method returns a
226 Catmandu::FedoraCommons::Response object with a
227 Catmandu::FedoraCommons::Model::describeRepository model.
228
229 Example:
230
231 my $desc = $fedora->describeRepository()->parse_content();
232
233 MODIFY METHODS
234
235 addDatastream(pid => $pid , dsID => $dsID, url => $remote_location, %args)
236
237 addDatastream(pid => $pid , dsID => $dsID, file => $filename , %args)
238
239 addDatastream(pid => $pid , dsID => $dsID, xml => $xml , %args)
240
241 This method adds a data stream to the object. Required parameters are
242 the object $pid, a new datastream $dsID and a remote $url, a local
243 $file or an $xml string which contains the content. Optionally any of
244 these datastream modifiers may be provided: controlGroup, altIDs,
245 dsLabel, versionable, dsState, formatURI, checksumType, checksum,
246 mimeType, logMessage. See:
247 https://wiki.duraspace.org/display/FEDORA36/REST+API for more
248 information. This method returns a Catmandu::FedoraCommons::Response
249 object with a Catmandu::FedoraCommons::Model::datastreamProfile model.
250
251 Example:
252
253 my $obj = $fedora->addDatastream(pid => 'demo:29', dsID => 'TEST' , file => 'README', mimeType => 'text/plain')->parse_content;
254
255 print "Uploaded at: %s\n" , $obj->{dateTime};
256
257 addRelationship(pid => $pid, relation => [ $subject, $predicate, $object]
258 [, dataType => $dataType])
259
260 This methods adds a triple to the 'RELS-EXT' data stream of the object.
261 Requires parameters are the object $pid and a relation as a triple
262 ARRAY reference. Optionally the $datatype of the literal may be
263 provided. This method returns a Catmandu::FedoraCommons::Response
264 object with a Catmandu::FedoraCommons::Model::addRelationship model.
265
266 Example:
267
268 $fedora->addRelationship(pid => 'demo:29' , relation => [ 'info:fedora/demo:29' , 'http://my.org/name' , 'Peter']);
269
270 export(pid => $pid [, format => $format , context => $context , encoding
271 => $encoding])
272
273 This method exports the data model of the object in FOXML,METS or ATOM.
274 Required is $pid of the object. Optionally a $context may be provided
275 and the $format of the export. See:
276 https://wiki.duraspace.org/display/FEDORA36/REST+API for more
277 information. This method returns a Catmandu::FedoraCommons::Response
278 object with a Catmandu::FedoraCommons::Model::export model.
279
280 Example:
281
282 my $res = $fedora->export(pid => 'demo:29');
283
284 print $res->raw;
285
286 print "%s\n" , $res->parse_content->{objectProperties}->{label};
287
288 getDatastream(pid => $pid, dsID => $dsID , %args)
289
290 This method return metadata about a data stream. Required is the object
291 $pid and the $dsID of the data stream. Optionally a version
292 'asOfDateTime' can be provided and a 'validateChecksum' check. See:
293 https://wiki.duraspace.org/display/FEDORA36/REST+API for more
294 information. This method returns a Catmandu::FedoraCommons::Response
295 object with a Catmandu::FedoraCommons::Model::datastreamProfile model.
296
297 Example:
298
299 my $obj = $fedora->getDatastream(pid => 'demo:29', dsID => 'DC')->parse_content;
300
301 printf "Label: %s\n" , $obj->{profile}->{dsLabel};
302
303 getDatastreamHistory(pid => $pid , dsID => $dsID , %args)
304
305 This method returns the version history of a data stream. Required
•306 parameters is the $pid of the object and the $dsID of the data stream.
307 This method returns a Catmandu::FedoraCommons::Response object with a
308 Catmandu::FedoraCommons::Model::datastreamHistory model.
309
310 Example:
311
312 my $obj = $fedora->getDatastreamHistory(pid => 'demo:29', dsID => 'DC')->parse_content;
313
314 for (@{ $obj->{profile} }) {
315 printf "Version: %s\n" , $_->{dsCreateDate};
316 }
317
318 getNextPID(namespace => $namespace, numPIDs => $numPIDs)
319
320 This method generates a new pid. Optionally a 'namespace' can be
321 provided and the required 'numPIDs' you need. This method returns a
322 Catmandu::FedoraCommons::Response object with a
323 Catmandu::FedoraCommons::Model::pidList model.
324
325 Example:
326
327 my $pid = $fedora->getNextPID()->parse_content->[0];
328
329 getObjectXML(pid => $pid)
330
331 This method exports the data model of the object in FOXML format.
332 Required is $pid of the object. This method returns a
333 Catmandu::FedoraCommons::Response object .
334
335 Example:
336
337 my $res = $fedora->getObjectXML(pid => 'demo:29');
338
339 print $res->raw;
340
341 getRelationships(pid => $pid [, relation => [$subject, $predicate, undef]
342 , format => $format ])
343
344 This method returns all RELS-EXT triples for an object. Required
345 parameter is the $pid of the object. Optionally the triples may be
346 filetered using the 'relation' parameter. Format defines the returned
347 format. See: https://wiki.duraspace.org/display/FEDORA36/REST+API for
348 more information. This method returns a
349 Catmandu::FedoraCommons::Response object with a
350 Catmandu::FedoraCommons::Model::getRelationships model.
351
352 Example:
353
354 my $obj = $fedora->getRelationships(pid => 'demo:29')->parse_content;
355
356 my $iter = $obj->get_statements();
357
358 print "Names of things:\n";
359 while (my $st = $iter->next) {
360 my $s = $st->subject;
361 my $name = $st->object;
362 print "The name of $s is $name\n";
363 }
364
365 ingest(pid => $pid , file => $filename , xml => $xml , format => $format ,
366 %args)
367
368 ingest(pid => 'new' , file => $filename , xml => $xml , format => $format
369 , %args)
370
371 This method ingest an object into Fedora Commons. Required is the $pid
372 of the new object (which can be the string 'new' when Fedora has to
•373 generate a new pid), and the $filename or $xml to upload written as
374 $format. Optionally the following parameters can be provided: label,
375 encoding, namespace, ownerId, logMessage. See:
376 https://wiki.duraspace.org/display/FEDORA36/REST+API for more
377 information. This method returns a Catmandu::FedoraCommons::Response
378 object with a Catmandu::FedoraCommons::Model::ingest model.
379
380 Example:
381
382 my $obj = $fedora->ingest(pid => 'new', file => 't/obj_demo_40.zip', format => 'info:fedora/fedora-system:ATOMZip-1.1')->parse_content;
383
384 printf "created: %s\n" , $obj->{pid};
385
386 modifyDatastream(pid => $pid , dsID => $dsID, url => $remote_location,
387 %args)
388
389 modifyDatastream(pid => $pid , dsID => $dsID, file => $filename , %args)
390
391 modifyDatastream(pid => $pid , dsID => $dsID, xml => $xml , %args)
392
393 This method updated a data stream in the object. Required parameters
394 are the object $pid, a new datastream $dsID and a remote $url, a local
395 $file or an $xml string which contains the content. Optionally any of
396 these datastream modifiers may be provided: controlGroup, altIDs,
397 dsLabel, versionable, dsState, formatURI, checksumType, checksum,
398 mimeType, logMessage. See:
399 https://wiki.duraspace.org/display/FEDORA36/REST+API for more
400 information. This method returns a Catmandu::FedoraCommons::Response
401 object with a Catmandu::FedoraCommons::Model::datastreamProfile model.
402
403 Example:
404
405 my $obj = $fedora->modifyDatastream(pid => 'demo:29', dsID => 'TEST' , file => 'README', mimeType => 'text/plain')->parse_content;
406
407 print "Uploaded at: %s\n" , $obj->{dateTime};
408
409 modifyObject(pid => $pid, label => $label , ownerId => ownerId , state =>
410 $state , logMessage => $logMessage , lastModifiedDate =>
411 $lastModifiedDate)
412
413 This method updated the metadata of an object. Required parameter is
414 the $pid of the object. Optionally one or more of label, ownerId,
415 state, logMessage and lastModifiedDate can be provided. This method
416 returns a Catmandu::FedoraCommons::Response object with a
417 Catmandu::FedoraCommons::Model::modifyObject model.
418
419 Example:
420
421 $fedora->modifyObject(pid => 'demo:29' , state => 'I');
422
423 purgeDatastream(pid => $pid , dsID => $dsID , startDT => $startDT , endDT
424 => $endDT , logMessage => $logMessage)
425
426 This method purges a data stream from an object. Required parameters is
427 the $pid of the object and the $dsID of the data stream. Optionally a
428 range $startDT to $endDT versions can be provided to be deleted. See:
429 https://wiki.duraspace.org/display/FEDORA36/REST+API for more
430 information. This method returns a Catmandu::FedoraCommons::Response
431 object with a Catmandu::FedoraCommons::Model::purgeDatastream model.
432
433 Example:
434
435 $fedora->purgeDatastream(pid => 'demo:29', dsID => 'TEST')->parse_content;
436
437 purgeObject(pid => $pid, logMessage => $logMessage)
438
439 This method purges an object from Fedora Commons. Required parameter is
440 the $pid of the object. Optionally a $logMessage can be provided. This
441 method returns a Catmandu::FedoraCommons::Response object with a
442 Catmandu::FedoraCommons::Model::purgeObject model.
443
444 Example:
445
446 $fedora->purgeObject(pid => 'demo:29');
447
448 purgeRelationship(pid => $pid, relation => [ $subject, $predicate,
449 $object] [, dataType => $dataType])
450
451 This method removes a triple from the RELS-EXT data stream of an
452 object. Required parameters are the $pid of the object and the relation
453 to be deleted. Optionally the $dataType of the literal can be provided.
454 This method returns a Catmandu::FedoraCommons::Response object with a
455 Catmandu::FedoraCommons::Model::purgeRelationship model.
456
457 Example:
458
459 $fedora->purgeRelationship(pid => 'demo:29' , relation => [ 'info:fedora/demo:29' , 'http://my.org/name' , 'Peter'])
460
461 setDatastreamState(pid => $pid, dsID => $dsID, dsState => $dsState)
462
463 This method can be used to put a data stream on/offline. Required
464 parameters are the $pid of the object , the $dsID of the data stream
465 and the required new $dsState ((A)ctive, (I)nactive, (D)eleted). This
466 method returns a Catmandu::FedoraCommons::Response object with a
467 Catmandu::FedoraCommons::Model::datastreamProfile model.
468
469 Example:
470
471 $fedora->setDatastreamState(pid => 'demo:29' , dsID => 'url' , dsState => 'I');
472
473 setDatastreamVersionable(pid => $pid, dsID => $dsID, versionable =>
474 $versionable)
475
476 This method updates the versionable state of a data stream. Required
477 parameters are the $pid of the object, the $dsID of the data stream and
478 the new $versionable (true|false) state. This method returns a
479 Catmandu::FedoraCommons::Response object with a
480 Catmandu::FedoraCommons::Model::datastreamProfile model.
481
482 Example:
483
484 $fedora->setDatastreamVersionable(pid => 'demo:29' , dsID => 'url' , versionable => 'false');
485
486 validate(pid => $pid)
487
488 This method can be used to validate the content of an object. Required
489 parameter is the $pid of the object. This method returns a
490 Catmandu::FedoraCommons::Response object with a
491 Catmandu::FedoraCommons::Model::validate model.
492
493 Example:
494
495 my $obj = $fedora->validate(pid => 'demo:29')->parse_content;
496
497 print "Is valid: %s\n" , $obj->{valid};
498
499 upload(file => $file)
500
501 This method uploads a file to the Fedora Server. Required parameter is
502 the $file name. This method returns a Catmandu::FedoraCommons::Response
503 object with a Catmandu::FedoraCommons::Model::upload- model.
504
505 Example:
506
507 my $obj = $fedora->upload(file => 't/marc.xml')->parse_content;
508
509 print "Upload id: %s\n" , $obj->{id};
510
511 SEE ALSO
512
513 Catmandu::FedoraCommons::Response, Catmandu::Model::findObjects,
514 Catmandu::Model::getObjectHistory, Catmandu::Model::getObjectProfile,
515 Catmandu::Model::listDatastreams, Catmandu::Model::listMethods
516
517 AUTHOR
518
519 * Patrick Hochstenbach, <patrick.hochstenbach at ugent.be>
520
521 LICENSE AND COPYRIGHT
522
523 This program is free software; you can redistribute it and/or modify it
524 under the terms of either: the GNU General Public License as published
525 by the Free Software Foundation; or the Artistic License.
526
527 See http://dev.perl.org/licenses/ for more information.
528