NAME

Metabase::Fact - base class for Metabase Facts

SYNOPSIS

  # defining the fact class
  package MyFact;
  use base 'Metabase::Fact::Hash';

  # using the fact class
  my $fact = TestReport->new(
    resource   => 'RJBS/Metabase-Fact-0.001.tar.gz',
    content    => {
      status => 'FAIL',
      time   => 3029,
    },
  );

  $client->send_fact($fact);

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 datatypes are constructed.

Metabase::Fact is a base class for facts (really opinions or analyses) that can be sent to or retrieved from a Metabase system.

ATTRIBUTES

Unless otherwise noted, all attributes are read-only and are either provided as arguments to the constructor or are generated during construction.

Arguments provided to new

resource

required

The canonical resource (URI) the Fact relates to. For CPAN distributions, this would be a cpan:///distfile/ URL. (See URI::cpan.)

content

required

A reference to the actual information associated with the fact. The exact form of the content is up to each Fact class to determine.

creator_id

optional

A Metabase::User::Profile URI that indicates the creator of the Fact. This is normally set by the Metabase when a Fact is submitted based on the submitter's Profile, but can be set during construction if the creator and submitter are not the same person. The set_creator_id mutator may be called to set creator_id, but only if it is not previously set.

Generated during construction

These attributes are generated automatically during the call to new.

guid

The Fact object's Globally Unique IDentifier.

schema_version

The schema_version of the Fact subclass that created the object. This may or may not be the same as the current schema_version of the class if newer versions of the class have been released since the object was created.

created_at

Fact creation time in epoch seconds.

METHODS

new

  $fact = MyFact->new(
    resource => 'AUTHORID/Foo-Bar-1.23.tar.gz',
    content => $content_structure,
  );

Constructs a new Fact. The resource and content attributes are required. No other attributes may be provided to new except creator_id.

CLASS METHODS

default_schema_version

  $version = MyFact->default_schema_version;

Defaults to 1. Subclasses should override this method if they make a backwards-incompatible change to the internals of the content attribute. Schema version numbers should be monotonically-increasing integers. The default schema version is used to set an objects schema_version attribution on creation.

type

  $type = MyFact->type;

The class name, with double-colons converted to dashes to be more URI-friendly. e.g. Metabase::Fact would be Metabase-Fact.

class_from_type

  $class = MyFact->class_from_type( $type );

A utility function to invert the operation of the type method.

OBJECT METHODS

as_struct

This returns a simple data structure that represents the fact and can be used for transmission over the wire. It serializes the content and core metadata, but not other metadata, which should be recomputed by the receiving end.

from_struct

This takes the output of the as_struct method and reconstitutes a Fact object.

core_metadata

This returns a hashref containing the fact's core metadata. This includes things like the guid, creation time, described resource, and so on.

Values are arrayrefs with two entries, in the form:

  [ type => value ]

The type will be either //num or //str.

resource_metadata

This method returns metadata describing the resource.

Unimplemented: In general, this is likely to be an empty hashref. Resource metadata is not yet implemented (much?).

set_creator_id

  $fact->set_creator_id($profile_guid);

This method sets the creator_id core metadata for the core metadata for the fact. If the fact's creator_id is already set, an exception will be thrown.

upgrade_fact

This method will be called when initializing a fact from a data structure that claims to be of a schema version other than the schema version reported by the loaded class's default_schema_version method. It will be passed the hashref of args being used to initialized the fact object, and should alter that hash in place.

ABSTRACT METHODS

Methods marked as required must be implemented by a Fact subclass. (The version in Metabase::Fact will die with an error if called.)

In the documentation below, the terms must, must not, should, etc. have their usual RFC 2119 meanings.

These methods MUST throw an exception if an error occurs.

content_as_bytes

required

  $string = $fact->content_as_bytes;

This method MUST serialize a Fact's content as bytes in a scalar and return it. The method for serialization is up to the individual fact class to determine. Some common subclasses are available to handle serialization for common data types. See Metabase::Fact::Hash and Metabase::Fact::String.

content_from_bytes

required

  $content = $fact->content_from_bytes( $string );
  $content = $fact->content_from_bytes( \$string );

Given a scalar, this method MUST regenerate and return the original content data structure. It MUST accept either a string or string reference as an argument. It MUST NOT overwrite the Fact's content attribute directly.

content_metadata

optional

  $content_meta = $fact->content_metadata;

If defined in a subclass, this method MUST return a hash reference with content-specific indexing metadata for the Fact. The key MUST be the name of the field for indexing.

Hash values MUST be an array_ref containing a type and the value for the either be simple scalars (strings or numbers) or array references. Type MUST be one of:

  //str
  //num

Here is a hypothetical example of content metadata for an image fact:

  sub content_metdata {
    my $self = shift;
    return {
      width   => [ '//num' => _compute_width  ( $self->content ) ],
      height  => [ '//num' => _compute_height ( $self->content ) ],
      comment => [ '//str' => _extract_comment( $self->content ) ],
    }
  }

It MUST return undef if no content-specific metadata is available.

validate_content

required

 eval { $fact->validate_content };

This method SHOULD check for the validity of content within the Fact. It MUST throw an exception if the fact content is invalid. (The return value is ignored.)

Classes SHOULD call validate_content in their superclass:

  sub validate_content {
    my $self = shift;
    $self->SUPER::validate_content;
    my $error = _check_content( $self );
    die $error if $error;
  }

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

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.

AUTHOR

• David A. Golden (DAGOLDEN)

• Ricardo J. B. Signes (RJBS)

COPYRIGHT AND LICENSE

  Portions copyright (c) 2008-2009 by David A. Golden
  Portions copyright (c) 2008-2009 by Ricardo J. B. Signes

Licensed under the same terms as Perl itself (the "License"). You may not use this file except in compliance with the License. A copy of the License was distributed with this file or you may obtain a copy of the License from http://dev.perl.org/licenses/

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

cpanm Metabase::Fact

perl -MCPAN -e shell
install Metabase::Fact