NAME

Keystone::Resolver::OpenURL - an OpenURL that can be resolved

SYNOPSIS

 %args = (genre => "article",
          issn => "0141-1926",
          volume => 29,
          issue => 4,
          spage => 471);
 $openURL = $resolver->openURL(\%args, "http://my.domain.com/resolve");
 @results = $openURL->resolve_to_results();
 $xml = $openURL->resolve_to_xml();
 $html = $openURL->resolve_to_html($stylesheetName);
 ($type, $content) = $openURL->resolve();

 print $openURL->resolve();

DESCRIPTION

This class represents an OpenURL, which may be resolved.

METHODS

new()

 $openURL = new Keystone::Resolver::OpenURL($resolver, \%args,
                                            "http://my.domain.com/resolve");
 # Or the more usual shorthand:
 $openURL = $resolver->openURL(\%args, "http://my.domain.com/resolve");

Creates a new OpenURL object, which can subsequently be resolved. The first argument is a reference to a hash of the arguments making up the OpenURL data packet that specifies the ContextObject. The second is the base URL of the resolver, which is used for generating equivalent URLs as required. The third is the referer URL, which may be used for some primitive authentication schemes.

newFromCGI()

 $openURL = newFromCGI Keystone::Resolver::OpenURL($resolver, $cgi,
        $ENV{HTTP_REFERER});
 $openURL = newFromCGI Keystone::Resolver::OpenURL($resolver, $cgi,
        $ENV{HTTP_REFERER}, { xml => 1, loglevel => 7 });

This convenience method creates an OpenURL object from a set of CGI parameters, for the common case that the transport is HTTP-based. it behaves the same as the general constructor, new(), except that that a CGI object is passed in place of the $argsref and $baseURL arguments.

Additionally, a set of options may be passed in: unless overridden by options in the CGI parameters, these are applied to the $resovler. Parameters in $cgi whose keys are prefixed with opt_ are interpreted as resolver options, like this:

        opt_loglevel=7&opt_logprefix=ERROR

All other keys in the CGI object are assumed to be part of the OpenURL context object.

(### The option handling is arguably a mistake: the options should apply to the OpenURL object, not the resolver that it uses -- but at present, OpenURL objects do not have their own options at all.)

die(), warn()

 $openURL->die("no service available: ", $errmsg, "(", $details, ")");
 $openURL->warn("multiple genres with same ID");

die() reports failure to resolve this OpenURL. A nicely formatted message may be displayed for the user, a message may be generated in a log file, an email may be sent to the administrator or some combination of these actions may be taken. In any case, the arguments are concatenated to form a string used in these messages.

warn() is the same, except that it indicates a non-fatal condition.

arg1()

 $scalar = $openurl->arg1($hashref, $key, $delete, $allowUndef);

This simple utility method extracts the first element (i.e. element 0) from the specified element of the specified hash and returns it, throwing an error if that element doesn't exist, isn't an array reference or has no elements, and warning if it has more than one.

 $openurl->arg1($hashref, "name")

is precisely equivalent to

 $hashref->{name}->[0]

except for the extra checking.

If the optional third argument, $delete is provided and non-zero, then $hashref-[$key]> is deleted as a side-effect.

If the optional fourth argument, $allowUndef is provided and non-zero, then no error is raised if $hashref-[$key]> is undefined: instead, an undefined value is returned.

resolve_to_results(), resolve_to_xml(), resolve_to_html(), resolve()

 @results = $openURL->resolve_to_results();
 $xml = $openURL->resolve_to_xml();
 $html1 = $openURL->resolve_to_html();
 $html2 = $openURL->resolve_to_html($stylesheetName);

The various resolve_to_*() methods all resolve a Keystone::Resolver::OpenURL object into a list of candidate objects that satisfy the link. They differ only in the form in which they return the information.

resolve_to_results()

Returns an array of zero or more Keystone::Resolver::Result objects, from which the type and text of results can readily be extracted.

resolve_to_xml()

Returns the text of an ultra-simple XML document that contains all the results. There is a DTD for this XML format in etc/constraint/results-1.0.dtd, but informally:

• The document consists of a top-level <results> element containing zero or more <result> elements.

• Each result has mandatory type, tag and service attributes and optional mimetype and priority attributes

• Each <result> element contains text which is typically but not always a URI.

resolve_to_html()

Returns the text of an HTML document made by processing the XML described above by a stylesheet. If an argument is given, then this is taken as the basename of the stylesheet to use, to be found in the the XSLT directory of the resolver (as specified by its xsltdir option). If this is omitted, the stylesheet named by the xslt option, from this directory, is used.

resolve()

Returns an array of two elements from which an entire HTTP response can be built: the Content-type and the actual content. The response is XML, as returned from resolve_to_xml(), if the xml option is set and non-zero; or HTML otherwise, as returned from resolve_to_html(), otherwise.

v10url()

 $url = $openurl->v10url("svc_dat", "rft_id");

Returns a string containing a version 1.0 OpenURL representing the Context Object described by $openurl. If arguments are provided, they are the names of keys to be omitted from the returned OpenURL.

cpanm Keystone::Resolver

perl -MCPAN -e shell
install Keystone::Resolver