NAME

SemanticWeb::OAI::ORE::ReM - Module implementing OAI-ORE Resource Map object

SYNPOSIS

This class is designed to provide convenient ways to interact with OAI-ORE resource maps from Perl code. It as based around a data model class SemanticWeb::OAI::ORE::Model which is the RDF model and may be accessed directly via $rem->model. The access methods here are intended to hide the RDF and instead work more naturally with the constraints and language of OAI-ORE.

Written against the v1.0 OAI-ORE specification (http://www.openarchives.org/ore/1.0/toc).

DESCRIPTION

An ORE Resource Map is comprised of two things:

1) a URI indicating its location

2) an RDF graph expressing the relationship between an aggregation and aggreted resources

This class encapsulates these two things ($rem->uri and $rem->model), some other useful informatino about paring and serialization methods, and provides routines to create/read, update, and write the resource map.

CREATION OF A RESOURCE MAP

For simple case where we have simply a set of aggregated resources and minimal metadata is required:

use SemanticWeb::OAI::ORE::ReM;

my $rem=SemanticWeb::OAI::ORE::ReM->new('ar'=>['uri:1','uri:2']);
print $rem->serialize('rdfxml');

PARSING A RESOURCE MAP

use SemanticWeb::OAI::ORE::ReM;
my $rem=SemanticWeb::OAI::ORE::ReM->new;
$rem->parse('rdfxml',$rdfxml_string);

METHODS

SemanticWeb::OAI::ORE::ReM->new(%args)

Create a new Resource Map (ReM) object. The resource map is comprised of a URI (URI-R) and a set of triples, the model.

Any %args supplied are used to set the object variables. As a shorthand for construction argument C{ar} may be used to provide an arrayref of aggregated resources which are added using $rem-aggregated_resources($args{ar})>.

$rem->uri()

Set or access the identity of the ReM (URI-R). This should be the first thing set when building a Resource Map. The validity of the URI is checked with check_valid_uri(..).

$rem->model()

Set or access the model (see SemanticWeb::OAI::ORE::Model) of this Resource Map. It is usually expected that ORE specific accessor methods such as aggregated_resources, creator and such will be used to add data to the model when building a resource map.

See SemanticWeb::OAI::ORE::Model for details of how the model may be accessed and manipulated, and also methods that follow for convenient accessors to ORE elements.

Will always return the reference to the model object so one can do things such as:

$rem->model->add($ref_statement);

$rem->aggregation()

Set or access the URI of the Aggregation described by this ReM (URI-A). Must be set after the URI of the Resource Map (URI-R) and would usually be the second thing set when building a resource map from scratch.

WARNING - this routine does not have the facility to update all occurrences in the model if changed when other statements (e.g. aggregated resources or metadata) have been added that reference the aggregation.

$rem->creators()

Set or access the creator of the ReM. Returns If there is more than one creator then the first will be returned. Returns nothing if there is no creator set.

See http://www.openarchives.org/ore/1.0/datamodel#Metadata_about_the_ReM:

The identity of the authoring authority (human, organization, or agent) of 
the Resource Map, using the dcterms:creator predicate, with an object that MUST 
be a reference to a Resource of type L<http://purl.org/dc/terms/Agent>. This MAY 
then be the subject of the following triples:

* A triple with the predicate foaf:name and an object that is a text string 
  containing some descriptive name of the authoring authority.

* A triple with the predicate foaf:mbox and an object that is a URI that is 
  the email address of the authoring authority.

$rem->creator()

Assumes one creator. Wrapper around $rem->creators() that does the same thing except in the case where there are multiple creators it will return just the first.

$rem->creator_name()

Set or access the creator as a URI of the ReM.

$rem->timestamp_as_unix($type,$timestamp)

Set or access the option creation timestamp of the ReM. Returns now if not set. Type should be either CREATED or MODIFIED constant. Usually called via created_as_unix() or modified_as_unix() wrappers.

Will set if timestamp if $timestamp is defined.

$rem->created_as_unix($timestamp)

Set or access the creation timestamp of the ReM as a Unix timestamp.

Will set timestamp if $timestamp is defined.

$rem->modified_as_unix($timestamp)

Set or access the modification timestamp of the ReM as a Unix timestamp.

Will set timestamp if $timestamp is defined.

$rem->timestamp_as_iso8601($type,$timestamp)

Set or access the timestamp of the rem as an ISO8601 string. Type should be either CREATED or MODIFIED constant. Usually called via created_as_iso8601() or modified_as_iso8601() wrappers.

Will set timetstamp if $timestamp is defined.

$rem->now_as_iso8601()

Returns the current system time as an iso8601 string

$rem->created_as_iso8601($timestamp)

Set or access the creation timestamp of the ReM as a ISO8601 timestamp.

Will set timestamp if $timestamp is defined.

$rem->modified_as_iso8601($timestamp)

Set or access the creation timestamp of the ReM as a ISO8601 timestamp.

Will set timestamp if $timestamp is defined.

$rem->aggregation_metadata($predicate,$only)

If $only is not specified then the objects matching will be returned.

If $only is RESOURCE then only resource labels will be included, if LITERAL then only literal labels will be returned.

$rem->aggregation_metadata_literal($predicate)

Wrapper for $rem-aggregation_metadata> that will take just the first matching literal, or return undef if there a no matches.

$rem->aggregated_resources()

Set or access the aggregated resources list.

$rem->aggregated_resources('uri:3');

This method will never remove an aggregated resource from this ReM. Use delete_aggregated_resources to remove or clear the set of aggregated resources for this ReM. Returns a list of all the aggregated resources.

$rem->rights()

Set of access the rights for this resource map. Permits only one rights statement to be associated with the resource map. Returns undef if no rights value is set.

$rem->is_valid

Run validation checks on the resource map model. Returns true (1) on succes, false (nothing) on failures. Errors set in errstr.

INPUT AND OUTPUT METHODS

$rem->parse($format,$src,$uri_rem)

Parse resource $uri_rem. Get it from $src, where $src may be either a string containing the representation to be parsed, or an open filehandle. If $src is not set then attempt to download from $uri_rem using parseuri().

To parse a file directly, use the parsefile() wrapper. To parse a URI directly, use the parseuri() wrapper.

Will run validation checks on the resource map model obtained. Set $rem-die_level(RECKLESS)> to ignore errors.

Will return true (1) on success, false (undef) on failure. Will have set errstr on failure.

$rem->parsefile($format,$file,$uri_rem)

Wrapper for parse($format,$uri_rem,$src)> which does nothing with $format and $uri_rem but opens $file and passes the reulting filehandle on to $rem-parse(...)>. Returns undef if the file cannot be opened, otherwise return values as for $rem-parse(...)>.

$rem->parseuri($format,$uri_rem)

Simple wrapper for parse($format,$uri_rem,$src)> that downloads $uri_rem with LWP::Simple before passing it on. Returns undef if $uri_rem cannot be downloaded, otherwise return values as for $rem-parse(...)>.

$rem->serialize()

Serialize in default format which has accessor $rem-default_format>.

$rem->serialize($format)

Serialize in $format. This will use and call the appropriate writer class.

$rem->errstr($str) or $rem->errstr

Resets the error string to $str if $str provided.

Returns a string, either the error string if set, else ''.

$rem->add_errstr($str)

Add to the error string. Will append \n if not present in $str.

$rem->err($level,$msg)

Log and/or report an error $msg at level $level. Intended mainly for internal use and use by particular format classes.

$rem->check_valid_uri($uri,$description)

Check that the supplied $uri is valid and create $rem-err> if not. Returns true if valid, false otherwise.

AUTHOR

Simeon Warner, <simeon at cpan.org>

BUGS

Support for Atom format output is not yet provided, this should be SemanticWeb::OAI::ORE::Atom.

Please report any bugs or feature requests to bug-net-oai-ore at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-OAI-ORE. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc SemanticWeb::OAI::ORE

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Net-OAI-ORE
CPAN Ratings

http://cpanratings.perl.org/d/Net-OAI-ORE
RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-OAI-ORE
Search CPAN

http://search.cpan.org/dist/Net-OAI-ORE

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install SemanticWeb::OAI::ORE, copy and paste the appropriate command in to your terminal.

cpanm

cpanm SemanticWeb::OAI::ORE

CPAN shell

perl -MCPAN -e shell
install SemanticWeb::OAI::ORE

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNPOSIS

DESCRIPTION

CREATION OF A RESOURCE MAP

PARSING A RESOURCE MAP

METHODS

SemanticWeb::OAI::ORE::ReM->new(%args)

$rem->uri()

$rem->model()

$rem->aggregation()

$rem->creators()

$rem->creator()

$rem->creator_name()

$rem->timestamp_as_unix($type,$timestamp)

$rem->created_as_unix($timestamp)

$rem->modified_as_unix($timestamp)

$rem->timestamp_as_iso8601($type,$timestamp)

$rem->now_as_iso8601()

$rem->created_as_iso8601($timestamp)

$rem->modified_as_iso8601($timestamp)

$rem->aggregation_metadata($predicate,$only)

$rem->aggregation_metadata_literal($predicate)

$rem->aggregated_resources()

$rem->rights()

$rem->is_valid

INPUT AND OUTPUT METHODS

$rem->parse($format,$src,$uri_rem)

$rem->parsefile($format,$file,$uri_rem)

$rem->parseuri($format,$uri_rem)

$rem->serialize()

$rem->serialize($format)

$rem->errstr($str) or $rem->errstr

$rem->add_errstr($str)

$rem->err($level,$msg)

$rem->check_valid_uri($uri,$description)

SEE ALSO

AUTHOR

BUGS

SUPPORT

COPYRIGHT & LICENSE

Module Install Instructions