/ 
Protocol-Tus-0.001
/ Protocol::Tus::AbstractModel

NAME

Protocol::Tus::AbstractModel

SYNOPSIS

use Protocol::Tus::AbstractModel;

DESCRIPTION

Base class for Protocol::Tus backends.

This class sets the shape of a backend (a.k.a. model) class for Protocol::Tus. While it's not mandatory to derive your class from this, you surely have to implement all its methods with the same semantics.

INTERFACE

All methods in the interface have to be present; some belong to the abstract interface, some are pre-implemented because they leverage on the other ones.

Failures MUST be signalled by throwing an exception.

In the rest of this section, we can refer to model or backend interchangeably.

cleanup

Abstract method, must be implemented in a derived class.

$model->cleanup($id);

Takes the identifier of an upload and is supposed to dispose all resources related to it.

create_upload

Abstract method, must be implemented in a derived class.

my $id = $model->create_upload($length, $metadata);

Kickstart a new upload. Both $length and $metadata might be undef and the model class has to deal with it, e.g. in case extension creation-defer-length is not supported.

In case of success it's supposed to return the identifier of the upload in a way that's meaningful for the model, keeping in mind that this identifier will probably be used (directly or not) to shape the exposed API.

extensions

Abstract method, must be implemented in a derived class.

my @list = $model->extensions;

Returns the list of strings, each naming one extension supported by the model.

finalize

Abstract method, must be implemented in a derived class.

$model->finalize($id);

Mark an upload as completed and do any activity that is supposed to be performed in this case.

If this method raises an exception, it might be called again later if the client calls the PATCH HTTP method again with zero data.

get_info

Abstract method, must be implemented in a derived class.

my $hash_ref = $model->get_info($id);

Get information about the specific upload. The return value MUST be a hash reference holding the following data:

complete

boolean (in Perl sense) marking the upload as completed or not.

length

the total length of the upload. If available, it is a non-negative integer; otherwise, it is undef.

metadata

the metadata provided upon creation of the upload (through "create_upload"). It can be undef is not available.

offset

the current offset of the upload as a non-negative decimal integer.

max_size

my $n = $model->max_size;

Get the maximum size of an upload. Defaults to undef which means no limit.

save_chunk

Abstract method, must be implemented in a derived class.

$model->save_chunk($id, $offset, $data_ref);

Save a chunk of data at $offset, whatever this means for the model. $data_ref is a reference to a scalar holding the actual data, so that we avoid copying all data around.

set_length

Abstract method, must be implemented in a derived class.

$model->set_length($id, $length);

In case the model supports extension creation-defer-length, this method is called in case the length upon creation is not provided by the client, but it is at a later stage during one of the PATCH calls.

extensions_as_string

my $string = $model->extensions_as_string;

Get the list of "extensions" as a single string with all elements joined by a comma, ready to be used as a Tus-Extension header.

get_offset

my $offset = $model->get_offset($id);

Convenience method, get the offset value of the hash reference returned by "get_info".

is_complete

my $bool = $model->is_complete($id);

Check if an upload (identified by $id) is complete or not.

supports_extension

my $bool = $model->supports_extension($extension_name);

Check if $extension_name is part of the list provided by "extensions".

ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)

See documentation for Protocol::Tus.