NAME

Mojo::UserAgent::Mockable::Serializer - A class that serializes Mojo transactions created by Mojo::UserAgent::Mockable.

VERSION

version 1.59

SYNOPSIS

    # This module is not intended to be used directly. Synopsis here is given to show how 
    # Mojo::UserAgent::Mockable uses the module to record transactions.
    
    use Mojo::UserAgent::Mockable::Serializer;
    use Mojo::UserAgent;
    use File::Slurper qw(read_text write_text);
    my $ua = Mojo::UserAgent->new;
    my $serializer = Mojo::UserAgent::Mockable::Serializer->new;
    
    my @transactions;
    push @transactions, $ua->get('http://example.com');
    push @transactions, $ua->get('http://example.com/object/123');
    push @transactions, $ua->get('http://example.com/subobject/456');
    my $json = $serializer->serialize(@transactions);
    write_text('/path/to/file/json', $json);
    # OR
    $serializer->store('/path/to/file.json', @transactions);
    # Later...
    my $json = read_text('/path/to/file.json');
    my @reconstituted_transactions = $serializer->deserialize($json);
    # OR
    #
    my @reconstituted_transactions = Mojo::UserAgent::Mockable::Serializer->retrieve('/path/to/file.json');

METHODS

serialize

Serialize or freeze one or more instances of Mojo::Transaction. Takes an array of transactions to be serialized as the single argument. This method will generate a warning if the instance has any subscribers (see "on" in Mojo::EventEmitter). Suppress this warning with (e.g.):

  no warnings 'Mojo::UserAgent::Mock::Serializer';
  $serializer->serialize(@transactions);
  use warnings 'Mojo::UserAgent::Mock::Serializer';

deserialize

Deserialize or thaw a previously serialized array of <Mojo:Transaction>. Arguments:

$data: JSON containing the serialized objects.

store

Serialize an instance of Mojo::Transaction and write it to the given file or file handle. Takes two arguments:

$file: File or handle to write serialized object to.
@transactions: Array of Mojo::Transaction to serialize

retrieve

Read from the specified file or file handle and deserialize one or more instances of Mojo::Transaction from the data read. If a file handle is passed, data will be read until an EOF is received. Arguments:

$file: File containing serialized object

EVENTS

This module emits the following events:

pre_thaw

    $serializer->on( pre_thaw => sub {
        my ($serializer, $slush) = @_;
        ...
    });

Emitted immediately before transactions are deserialized. See "DATA STRUCTURE" below for details of the format of $slush.

post_thaw

    # Note that $transactions is an arrayref here.
    $serializer->on( post_thaw => sub {
        my ($serializer, $transactions, $slush) = @_;
        ...
    }

Emitted immediately after transactions are deserialized. See "DATA STRUCTURE" below for details of the format of $slush.

In addition, each transaction, as well as each message therein, serialized using this module will emit the following events:

pre_freeze

    $transaction->on(freeze => sub {
        my $tx = shift;
        ...
    });

Emitted immediately before the transaction is serialized.

post_freeze

Emitted immediately after the transaction is serialized. See "Messages" for details of the frozen format.

    $transaction->on(post_freeze => sub {
        my $tx = shift;
        my $frozen = shift;
        ...
    });

DATA STRUCTURE

serialize produces, and deserialize expects, JSON data. Transactions are stored as an array of JSON objects (i.e. hashes). Each transaction object has the keys:

'class': The original class of the transaction.
'request': The request portion of the transaction (e.g. "GET /foo/bar ..."). See "Messages" below for encoding details.
'response': The response portion of the transaction (e.g. "200 OK ..."). See "Messages" below for encoding details.

Messages

Individual messages are stored as JSON objects (i.e. hashes) with the keys:

'class': The class name of the serialized object. This should be a subclass of Mojo::Message
'events': Array of events with subscribers in the serialized object. These events will be re-emitted after the "thaw" event is emitted, but any subscribers present in the original object will be lost.
'body': The raw HTTP message body.

CAVEATS

This module does not serialize any event listeners. This is unlikely to change in future releases.

AUTHOR

Kit Peters <popefelix@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.