Metabase::Resource(3) User Contributed Perl DocumentationMetabase::Resource(3)NAME
Metabase::Resource - factory class for Metabase resource descriptors
VERSION
version 0.021
SYNOPSIS
my $resource = Metabase::Resource->new(
'cpan:///distfile/RJBS/Metabase-Fact-0.001.tar.gz',
);
my $resource_meta = $resource->metadata;
my $typemap = $resource->metadata_types;
DESCRIPTION
Metabase is a framework for associating metadata with arbitrary
resources. A Metabase can be used to store test reports, reviews,
coverage analysis reports, reports on static analysis of coding style,
or anything else for which Metabase::Fact types are constructed.
Resources in Metabase are URI's that consist of a scheme and scheme
specific information. For example, a standard URI framework for a CPAN
distribution is defined by the URI::cpan class.
cpan:///distfile/RJBS/URI-cpan-1.000.tar.gz
Metabase::Resource is a factory class for resource descriptors. It
provide a common interface to extract scheme-specific indexing metadata
from a scheme-specific resource subclass.
For example, the Metabase::Resource::cpan class will deconstruct the
example above this into a Metabase resource metadata structure with the
following elements:
type => Metabase-Resource-cpan-distfile
dist_file => RJBS/URI-cpan-1.000.tar.gz
cpan_id => RJBS
dist_name => URI-cpan
dist_version => 1.000
Only the "type" field is mandatory for all resources. The other fields
are all specific to Metabase::Resource::cpan.
COMMON METHODS
new
my $resource = Metabase::Resource->new(
'cpan:///distfile/RJBS/Metabase-Fact-0.001.tar.gz',
);
Takes a single resource string argument and constructs a new Resource
object from a resource subtype determined by the URI scheme. Throws an
error if the required resource subclass is not available.
resource
Returns the string used to initialize the resource object.
scheme
Returns a string containing the scheme.
_cache (private)
Returns a hash reference for subclasses to use to store data derived
from the "content" string.
OVERLOADING
Resources have stringification overloaded to call "content". Equality
(==) and inequality (!=) are overloaded to perform string comparison
instead.
SUBCLASSING AND SUBCLASS METHODS
Metabase::Resource relies on subclasses to implement scheme-specific
parsing of the URI into relevant index metadata.
Subclasses SHOULD NOT implement a "new" constructor, as the
Metabase::Resource constructor will load the subclass, construct the
object, bless the object into the subclass, and and then call
"validate" on the object. Subclasses MAY store structured data derived
from the content string during validation.
Subclasses SHOULD use the "content" method to access the resource
string and the "scheme" method to access the scheme. Subclasses MAY
use the "_cache" accessor to store derived metadata data. Subclasses
MUST provide a "metadata_types" method to return data types for all
elements stored in "_cache".
All subclasses MUST implement the "validate", "metadata" and
"metadata_types" methods, as described below.
All methods MUST throw an exception if an error occurs.
validate
$resource->validate
This method is called by the constructor. It SHOULD return true if the
resource string is valid according to scheme-specific rules. It MUST
die if the resource string is invalid.
metadata
$meta = $resource->metadata;
This method MUST return a hash reference with resource-specific
indexing metadata for the Resource. The key MUST be the name of the
field for indexing. The "scheme" key MUST be present and the "scheme"
value MUST be identical to the string from the "scheme" accessor.
Other keys SHOULD provide dimensions to differentiate one resource from
another in the context of "scheme". If a scheme has subcategories, the
key "type" SHOULD be used for the subcategory. Values MUST be simple
scalars, not references.
Here is a hypothetical example of a "metadata" function for a metabase
user resource like
'metabase:user:ec2726a4-070c-11df-a2e0-0018f34ec37c':
sub metadata {
my $self = shift;
my ($uuid) = $self =~ m{\Ametabase:user:(.+)\z};
return {
scheme => 'metabase',
type => 'user',
user => $uuid,
}
}
Field names should be valid perl identifiers, consisting of
alphanumeric characters or underscores. Hyphens and periods are
allowed, but are not recommended.
metadata_types
my $typemap = $resource->metadata_types;
This method is used to identify the datatypes of keys in the data
structure provided by "metadata". It MUST return a hash reference. It
SHOULD contain a key for every key that could appear in the data
structure generated by "metadata" and provide a value corresponding to
a datatype for each key. It MAY contain keys that do not always appear
in the result of "metadata".
Data types are loosely based on Data::RX. Type SHOULD be one of the
following:
'//str' -- indicates a value that should be compared stringwise
'//num' -- indicates a value that should be compared numerically
Here is a hypothetical example of a "metadata_types" function for a
metabase user resource like
'metabase:user:ec2726a4-070c-11df-a2e0-0018f34ec37c':
sub metadata_types {
return {
scheme => '//str',
type => '//str',
user => '//str',
}
}
Consumers of "metadata_types" SHOULD assume that any "metadata" key not
found in the result of "metadata_types" is a '//str' resource.
BUGS
Please report any bugs or feature using the CPAN Request Tracker. Bugs
can be submitted through the web interface at
http://rt.cpan.org/Dist/Display.html?Queue=Metabase-Fact
<http://rt.cpan.org/Dist/Display.html?Queue=Metabase-Fact>
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.
AUTHORS
· David Golden <dagolden@cpan.org>
· Ricardo Signes <rjbs@cpan.org>
· H.Merijn Brand <hmbrand@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2012 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
perl v5.14.2 2012-02-14 Metabase::Resource(3)
