The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-MLite-2.01
River stage zero No dependents
1 ++
/ WWW::MLite::Client

NAME

WWW::MLite::Client - WWW::MLite REST Client base class

VIRSION

Version 1.00

SYNOPSIS

    use WWW::MLite::Client;

    my $client = new MDScore::Client(
            verbose         => 0, # 0 - off, 1 - on
            url             => "https://your.domain.name/path",
            timeout         => 180,
            format          => "auto", # xml, json, yaml, auto
            content_type    => "text/plain",
            sr_attrs        => {
                xml => [
                        { # For serialize
                            RootName   => "request",
                        },
                        { # For deserialize
                            ForceArray => 1,
                            ForceContent => 1,
                        }
                    ],
                json => [
                        { # For serialize
                            utf8 => 0,
                            pretty => 1,
                            allow_nonref => 1,
                            allow_blessed => 1,
                        },
                        { # For deserialize
                            utf8 => 0,
                            allow_nonref => 1,
                            allow_blessed => 1,
                        },
                    ],
            },
            no_check_redirect => 0,
            ua_opts => {
                    agent                   => "MyClient/1.00",
                    max_redirect            => 10,
                    requests_redirectable   => ['GET','HEAD'],
                    protocols_allowed       => ['http', 'https'],
                },
            headers => {
                    'Cache-Control' => "no-cache",
                    'Accept'        => "text/plain",
                },
        );

    my $perl = $client->request( POST => "/api", "...data..." );
    print STDERR $client->error unless $client->status;
    print Dumper($perl) if defined($perl);

DESCRIPTION

WWW::MLite REST Client base class.

This module provides interaction between the REST server and the REST client

new

    my $client = new MDScore::Client(
            verbose         => 0, # 0 - off, 1 - on
            url             => "https://your.domain.name/path",
            timeout         => 180,
            format          => "auto", # xml, json, yaml, auto
            content_type    => "text/plain",
            sr_attrs        => {
                xml => [
                        { # For serialize
                            RootName   => "request",
                        },
                        { # For deserialize
                            ForceArray => 1,
                            ForceContent => 1,
                        }
                    ],
                json => [
                        { # For serialize
                            utf8 => 0,
                            pretty => 1,
                            allow_nonref => 1,
                            allow_blessed => 1,
                        },
                        { # For deserialize
                            utf8 => 0,
                            allow_nonref => 1,
                            allow_blessed => 1,
                        },
                    ],
            },
            no_check_redirect => 0,
            ua_opts => {
                    agent                   => "MyClient/1.00",
                    max_redirect            => 10,
                    requests_redirectable   => ['GET','HEAD'],
                    protocols_allowed       => ['http', 'https'],
                },
            headers => {
                    'Cache-Control' => "no-cache",
                    'Accept'        => "text/plain",
                },
        );
content_type

Content type of request and response

Default: text/plain

format

Format name: xml, json, yaml, none or auto

Deserialization will be skipped if format not specified

headers

hash of headers for Agent

Default: { 'Cache-Control' => "no-cache" }

no_check_redirect

If set the no_check_redirect to true then the check for redirects will not be performed

sr_attrs

Hash of the attributes-array for request serialization and deserialization

For example:

    {
        xml => [
                { # For serialize
                    RootName   => "request",
                },
                { # For deserialize
                    ForceArray => 1,
                    ForceContent => 1,
                }
            ],
        json => [
                { # For serialize
                    utf8 => 0,
                    pretty => 1,
                    allow_nonref => 1,
                    allow_blessed => 1,
                },
                { # For deserialize
                    utf8 => 0,
                    allow_nonref => 1,
                    allow_blessed => 1,
                },
    }
timeout

Timeout for LWP requests, in seconds

Default: 180 seconds (5 mins)

ua_opts

Hash of LWP::UserAgent options

Default:

  {
    agent                   => __PACKAGE__."/".$VERSION,
    max_redirect            => MAX_REDIRECT,
    requests_redirectable   => ['GET','HEAD'],
    protocols_allowed       => ['http', 'https'],
  }
uri

URI object, that describes URL of the WEB Server. See url attribute

url

Full URL of the WEB Server, eg.: http://user:password@your.domain.name/path/to?foo=bar

verbose

Verbose mode. All debug-data are written to trace pool

Default: 0

cleanup

    $client->cleanup;

Cleanup all variable data in object and returns client object. Returns the Client object

error

    print $client->error;
    $client->error( " ... error ... " );

Just returns error string if no argument; sets new error string and returns it if argument specified

req

    my $request = $client->req;

Returns request object

See HTTP::Request

request

    my $data = $client->request( GET => "/my/path?foo=bar" );
    my $data = $client->request( GET => "/my/path?foo=bar", undef, sub { ... } );
    my $data = $client->request( GET => "/my/path?foo=bar", sub { ... }, sub { ... } );
    my $data = $client->request( POST => "/my/path", { foo => "bar" } );
    my $data = $client->request( PUT => "/my/path", "...data..." );

Performs request and returns response data

First arg

HTTP Method:

    HEAD, GET, POST, PUT, PATCH, DELETE and etc.

Default: GET

Second arg

Path and query string

Default: undef

Third arg

Data: undef, string, perl-structure for serialization or request callback function

Default: undef

Example for uploading:

    my $file = "/path/to/filename";
    $self->request(PUT => "/foo/bar/filename", sub {
        my $req = shift; # HTTP::Request object
        $req->header('Content-Type', 'application/octet-stream');
        if (-e $file and -f $file) {
            my $size = (-s $file) || 0;
            return 0 unless $size;
            my $fh;
            $req->content(sub {
                unless ($fh) {
                    open($fh, "<", $file) or do {
                        $self->error(sprintf("Can't open file %s: %s", $file, $!));
                        return "";
                    };
                    binmode($fh);
                }
                my $buf = "";
                if (my $n = read($fh, $buf, 1024)) {
                    return $buf;
                }
                close($fh);
                return "";
            });
            return $size;
        }
        return 0;
    });
Fourth arg

Callback response function

Default: undef

Example for downloading:

    my $expected_length;
    my $bytes_received = 0;
    my $res = $client->request(GET => "/path", undef, sub {
        my($chunk, $res) = @_;
        $bytes_received += length($chunk);
        unless (defined $expected_length) {
            $expected_length = $res->content_length || 0;
        }
        if ($expected_length) {
            printf STDERR "%d%% - ",
                100 * $bytes_received / $expected_length;
        }
        print STDERR "$bytes_received bytes received\n";
        # XXX Should really do something with the chunk itself
        # print $chunk;
    });

See LWP::UserAgent

res

    my $response = $client->res;

Returns response object

See HTTP::Response

serializer

    my $serializer = $client->serializer;

Returns serializer object

status

    my $status = $client->status;
    my $status = $client->status( 1 );

Status accessor. Returns object status value. 0 - Error; 1 - Ok You also can set new status value

trace

    my $trace = $client->trace;
    $client->trace("New trace record");

Gets trace stack or pushes new trace record to trace stack

transaction

    print $client->transaction;

Gets transaction string

HISTORY

See Changes file

TO DO

See TODO file

BUGS

* none noted

SEE ALSO

WWW::MLite, HTTP::Message, LWP

AUTHOR

Serż Minus (Sergey Lepenkov) http://www.serzik.com <abalama@cpan.org>

COPYRIGHT

Copyright (C) 1998-2019 D&D Corporation. All Rights Reserved

LICENSE

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

See LICENSE file and https://dev.perl.org/licenses/