--- name: "Metabase::Resource" section: "3pm" platform: "linux" package: "libmetabase-fact-perl" version: "0.025-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Metabase::Resource" --- # Metabase::Resource(3pm) factory class for Metabase resource descriptors ## NAME Metabase::Resource - factory class for Metabase resource descriptors ## VERSION version 0.025 ## 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 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 \ 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 \ - • Ricardo Signes \ - • H.Merijn Brand \ ## COPYRIGHT AND LICENSE This software is Copyright (c) 2016 by David Golden. This is free software, licensed under: ``` The Apache License, Version 2.0, January 2004 ```