NAME

URI::OpenURL - Parse and construct OpenURL's (NISO Z39.88-2004)

DESCRIPTION

This module provides an implementation of OpenURLs encoded as URIs (Key/Encoded-Value (KEV) Format), this forms only a part of the OpenURL spec. It does not check that OpenURLs constructed are sane according to the OpenURL specification (to a large extent sanity will depend on the community of use).

From the implementation guidelines:

The description of a referenced resource, and the descriptions of the associated resources that comprise the context of the reference, bundled together are called a ContextObject. It is a ContextObject that is transported when a user makes a request by clicking a link. A KEV OpenURL may contain only one ContextObject.

The ContextObject may contain up to six Entities. One of these, the Referent, conveys information about the referenced item. It must always be included in a ContextObject. The other five entities - ReferringEntity, Requester, Resolver, ServiceType and Referrer - hold information about the context of the reference and are optional.

= OpenURL

http://library.caltech.edu/openurl/

From the implementation guidelines:

The OpenURL Framework for Context-Sensitive Services Standard provides a means of describing a referenced resource along with a description of the context of the reference. Additionally it defines methods of transporting these descriptions between networked systems. It is anticipated that it will be used to request services pertaining to the referenced resource and appropriate for the requester.

The OpenURL Framework is very general and has the potential to be used in many application domains and by many communities. Concrete instantiations of the various core components within the framework are defined within the OpenURL Registry. The OpenURL Framework is currently a .draft standard for ballot.. During the ballot and public review period, the content of the Registry will be static and has been pre-defined by the NISO AX Committee. There is also an experimental registry where components under development are held. In the future it will be possible to register further items.

There are currently two formats for ContextObjects defined in the OpenURL Framework, Key/Encoded-Value and XML. This document provides implementation guidelines for the Key/Encoded-Value Format, concentrating mainly, but not exclusively, on components from the San Antonio Level 1 Community Profile (SAP1).

SYNOPSIS

        use URI::OpenURL;

        # Construct an OpenURL
        # This is the first example from the implementation specs,
        # with additional resolver and serviceType entities.
        print URI::OpenURL->new('http://other.service/cgi/openURL'
                )->referrer(
                        id => 'info:sid/my.service',
                )->requester(
                        id => 'mailto:john@invalid.domain',
                )->resolver(
                        id => 'info:sid/other.service',
                )->serviceType()->scholarlyService(
                        fulltext => 'yes',
                )->referringEntity(id => 'info:doi/10.1045/march2001-vandesompel')->journal(
                        genre => 'article',
                        aulast => 'Van de Sompel',
                        aufirst => 'Herbert',
                        issn => '1082-9873',
                        volume => '7',
                        issue => '3',
                        date => '2001',
                        atitle => 'Open Linking in the Scholarly Information Environment using the OpenURL Framework',
                )->referent(id => 'info:doi/10.1045/july99-caplan')->journal(
                        genre => 'article',
                        aulast => 'Caplan',
                        aufirst => 'Priscilla',
                        issn => '1082-9873',
                        volume => '5',
                        issue => '7/8',
                        date => '1999',
                        atitle => 'Reference Linking for Journal Articles',
                )->as_string();

        # Parsing (wrappers for $uri->query_form())
        my $uri = URI::OpenURL->new('http://a.openurl/?url_ver=Z39.88-2004&...');
        my @referent = $uri->referent->metadata();
        print join(',',@referent), "\n";
        # This could lose data if there is more than one id
        my %ds = $uri->referent->descriptors();
        if( !exists($ds{val_fmt}) ) {
                warn "No by-value metadata for referent in OpenURL";
        } elsif($ds{val_fmt} eq 'info:ofi/fmt:kev:mtx:journal') {
                my %md = $uri->referent->metadata();
                print ($md{genre} || 'Unknown journal article genre'), "\n";
        }

METHODS

$uri = URI::openurl->new([$url])

Create a new URI::openurl object and optionally initialize with $url. If $url does not contain a query component (...?key=value) the object will be initialized to a valid contextobject, but without any entities.

$uri = $uri->referent()

Every ContextObject must have a Referent, the referenced resource for which the ContextObject is created. Within the scholarly information community the Referent will probably be a document-like object, for instance: a book or part of a book; a journal publication or part of a journal; a report; etc.

$uri->referringEntity()

The ReferringEntity is the Entity that references the Referent. It is optional in the ContextObject. Within the scholarly information community the ReferringEntity could be a journal article that cites the Referent. Or it could be a record within an abstracting and indexing database.

$uri = $uri->requester()

The Requester is the Entity that requests services pertaining to the Referent. It is optional in the ContextObject. Within the scholarly information community the Requester is generally a human end-user who clicks a link within a digital library application.

$uri = $uri->serviceType()

The ServiceType is the Entity that defines the type of service requested. It is optional in the ContextObject. Within the scholarly information community the ServiceType could be a request for; the full text of an article; the abstract of an article; an inter-library loan request, etc.

$uri = $uri->resolver()

The Resolver is the Entity at which a request for services is targeted. It is optional in the ContextObject. This need not be the same Resolver as that specified as the base URL for an OpenURL Transport and does not replace that base URL.

$uri = $uri->referrer()

The Referrer is the Entity that generated the ContextObject. It is optional in the ContextObject, but its inclusion is strongly encouraged. Within the scholarly information community the Referrer will be an information provider such as an electronic journal application or an 'abstracting and indexing' service.

$uri = $uri->referent->dublinCore(key => value)

$uri = $uri->referent->book(key => value)

$uri = $uri->referent->dissertation(key => value)

$uri = $uri->referent->journal(key => value)

$uri = $uri->referent->patent(key => value)

$uri = $uri->serviceType->scholarlyService(key => value)

Add metadata to the current entity (referent is given only as an example). Dublin Core is an experimental format.

@descs = $uri->referent->descriptors([$key=>$value[, $key=>$value]])

Return the descriptors as a list of key-value pairs for the current entity (referent is given as an example).

Optionally add descriptors (functionally equivalent to $uri->referent($key=>$value)).

@metadata = $uri->referent->metadata([$schema_url, $key=>$value[, $key=>$value]])

Returns by-value metadata as a list of key-value pairs for the current entity (referent is given as an example).

Optionally, if you wish to add metadata that does not use one of the standard schemas (journal, book etc.) then you can add them using metadata.

ABOUT

This module should be considered BETA, not least because the OpenURL standard is (as of 2004-05-12) "submitted to NISO for Ballot". However it is not intended to change the interface.

TODO

"Easy" access to descriptors and metadata, e.g. $uri->referent->descriptor->id().

NOTES

This module works a little differently to the other URI modules in that structured data is added by calling methods that return an object. Whenever an entity method is called the object gets casted into a class encapsulating that entity, allowing further method calls to add metadata. The net result of this is that the URI object will change type as you add data to the object.

The reason for doing this is URI only allows one value to be stored (the URI string), so to keep the context of which entity the user is adding data to the only thing I could think of was to change the class. The downside of this is you can't use URI::openurl as a superclass.

You will also notice that if you try creating an URI object with an OpenURL (which is actually http:) the http module will be called rather than openurl. You can either call openurl directly as given in the synopsis, or by changing 'http' to 'openurl', in which case URI will call the correct module.

COPYRIGHT

Quotes from the OpenURL implementation guidelines are from: http://library.caltech.edu/openurl/

Copyright 2004 Tim Brody.

This module is released under the same terms as the main Perl distribution.

AUTHOR

Tim Brody <tdb01r@ecs.soton.ac.uk> Intelligence, Agents, Multimedia Group University of Southampton, UK

cpanm URI::OpenURL

perl -MCPAN -e shell
install URI::OpenURL