The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
WWW-MLite-2.01
River stage zero No dependents
/ 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/