The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Whelk-1.00
River stage zero No dependents
/ Whelk::Formatter

NAME

Whelk::Formatter - Base class for formatters

SYNOPSIS

        package Whelk::Formatter::MyFormatter;

        use Kelp::Base 'Whelk::Formatter';

        # at the very least, this attribute must be given a default
        attr response_format => 'json';

DESCRIPTION

Whelk::Formatter is a base class for formatters. Formatter's job is to implement logic necessary decode content from requests and encode content for responses. Whelk assumes that while a range of content types can be supported from the request, endpoints will always have just one response format, for example JSON.

Whelk implements two basic formatters which can be used out of the box: Whelk::Formatter::JSON (the default) and Whelk::Formatter::YAML. All they do is have different "response_format" values.

The base implementation uses Kelp modules Kelp::Module::JSON and Kelp::Module::YAML to get the encoders for each of those formats. If one of these modules is not loaded, the application will not support that format.

ATTRIBUTES

This class defines a couple attributes, which generally are loaded once and then reused as long as the app is running.

response_format

A response format in short form, for example 'json'.

full_response_format

A full response format in content type form, for example application/json. It will be loaded from "response_format" using "supported_format" method.

supported_formats

A cache of all formats supported by this formatter. It is created by a call to "load_formats".

It is in form of a hash reference, where keys are short format names like json and values are full format content types like application/json.

METHODS

load_formats

        $formatter->load_formats($app);

Called by the constructor to load formats into "supported_formats". Uses the application instance to see if the formats are actually supported by Kelp.

supported_format

        my $full_format = $formatter->supported_format($short_format);

Checks if the format is supported by the formatter according to "supported_formats" and returns the long form of the format. If it is not supported then an exception is raised.

match_format

        my $short_format = $formatter->match_format($app);

Tries to match the application's current request's content type and returns one of the formats in the short form if request content type is supported. Throws Whelk::Exception with code 400 if request's content type is unsupported.

get_request_body

        my $decoded = $formatter->get_request_body($app);

Tries to decode the request body and returns a perl structure containing decoded data. May return undef if the request data isn't well formed. Uses "match_format" to decide the format, so may also throw an exception.

format_response

        my $maybe_encoded = $formatter->format_response($app, $data, $special_encoder = undef);

Encodes $data to "response_format" and sets the proper content type on the response (unless it was set manually). Will only do the actual encoding if $special_encoder was specified (a name of the encoder to use, see "get_encoder" in Kelp. Otherwise, will return the structure unchanged to let Kelp handle it internally.