# WebService-Async

**Repository Path**: mirrors_gitpan/WebService-Async

## Basic Information

- **Project Name**: WebService-Async
- **Description**: Read-only release history for WebService-Async
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-10-20
- **Last Updated**: 2025-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NAME

WebService::Async - Non-blocking interface to web service APIs

# SYNOPSIS

  use WebService::Async;
  use WebService::Async::Parser::JSON;
  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => { v => '1.0', langpair => 'en|it' },
      response_parser => WebService::Async::Parser::JSON->new,
      on_done         => sub {
          my ($service, $id, $res, $req) = @_;
          print $req->param->{'q'} . " => ";
          print "$res->{responseData}->{translatedText}\n";
      },
  );
  $wa->add_get( q => 'apple' );
  $wa->add_get( q => 'orange' );
  $wa->add_get( q => 'banana', langpair => 'en|fr' );
  $wa->send_request;    # sending three requests in parallel.

  Results below.
    orange => arancione
    banana => la banane
    apple => mela

# DESCRIPTION

WebService::Async is a non-blocking interface to web service APIs.

This is similar to WebService::Simple but this is a non-blocking one.

So this module helps "PSGI/Plack streaming" programming with Tatsumaki and Gearman.
See example 11.

- * Easy to use asynchronous request.

- * Caching with memcached.

- * Retrying automatically on error.

- * Logging with Log::Dispatch::Config (starting connection, storing cache, cache hit, etc...)

- * Flexibly customizable.

# EXAMPLES

Here is 11 simple examples.

## Example 1. A very simple "Synchronous Request" pattern

Here is a very simple usage.

It is almost the same as "WebService::Simple" module.

### SOURCE

  use WebService::Async;
  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => { v => '1.0', langpair => 'en|it' },
  );
  my $ret = $wa->get( q => 'hello' ); # send get request
  print $ret->get;
  

### RESULTS

  {"responseData": {"translatedText":"ciao"}, "responseDetails": null, "responseStatus": 200}

## Example 2. "Synchronous Request" with a response parser

It is almost the same as "WebService::Simple" module.

### SOURCE

  use WebService::Async;
  use WebService::Async::Parser::JSON;
  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => { v => '1.0', langpair => 'en|it' },
      response_parser => WebService::Async::Parser::JSON->new,
  );
  my $ret = $wa->get( q => 'hello' );    # send get request
  print $ret->get->{responseData}->{translatedText};

### RESULTS

  ciao

## Example 3. Asynchronous request

You have to get or create the access-key which relates the response to the request.

### SOURCE

  use WebService::Async;
  use WebService::Async::Parser::JSON;
  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => { v => '1.0', langpair => 'en|it' },
      response_parser => WebService::Async::Parser::JSON->new,
  );
  

  # USING THE AUTOMATIC GENERATED KEY
  my $apple_key  = $wa->add_get( q => 'apple' );
  my $orange_key = $wa->add_get( q => 'orange' );
  my $grape_key  = $wa->add_get( q => 'grape' );
  my $ret = $wa->send_request;
  # blocking here automatically and sending 3 asynchronous requests.
  print $ret->get($orange_key)->{responseData}->{translatedText} . "\n";
  

  # USING YOUR OWN SPECIFIED KEY
  $wa->add_get(id => 1, param => { q => 'pear' });
  $wa->add_get(id => 2, param => { q => 'banana'});
  $wa->add_get(id => 3, lang => 'fr', param => { q => 'cherry', langpair => 'en|fr' });
  $ret = $wa->send_request;
  # blocking here automatically and sending 3 asynchronous requests.
  print $ret->get([id => 3, lang => 'fr'])->{responseData}->{translatedText}. "\n";

### RESULTS

  arancione
  cerise

## Example 4. Asyncronous request with callback

You can get results in your own callback function.

### SOURCE

  use WebService::Async;
  use WebService::Async::Parser::JSON;
  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => { v => '1.0', langpair => 'en|it' },
      response_parser => WebService::Async::Parser::JSON->new,
      on_done         => sub {
          my ( $async, $keys, $result ) = @_;
          print "on_done =>"
            . " key(@{$keys}):"
            . " value($result->{responseData}->{translatedText})\n";
      },
      on_complete => sub {
          my ( $async, $result ) = @_;
          print "on_complete\n";
          for ( $result->keys ) {
              print "  key(@{$_}): value("
                . $result->get($_)->{responseData}->{translatedText} . ")\n";
          }
      },
  );
  $wa->add_get( id => 1, param => { q => 'apple' } );
  $wa->add_get(
      id    => 2,
      param => { q => 'orange' },
      sub { print "on_done => override!\n" }
  );
  $wa->add_get(
      id    => 3,
      lang  => 'fr',
      param => { q => 'grape', langpair => 'en|fr' }
  );
  

  $wa->send_request;
  # blocking here automatically and sending 3 asynchronous requests.

### RESULTS

  on_done => key(id 3 lang fr): value(raisins)
  on_done => override!
  on_done => key(id 1): value(mela)
  on_complete
    key(id 2): value(arancione)
    key(id 3 lang fr): value(raisins)
    key(id 1): value(mela)

## Example 5. Asyncronous Request without auto blocking

If you are familiar with AnyEvent, you can use non-blocking 'send_request';

This usage is useful when you want to access two or more sites at the same time.

### SOURCE

  use WebService::Async;
  use WebService::Async::Parser::JSON;
  my $cv = AE::cv;
  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => { v => '1.0', langpair => 'en|it' },
      response_parser => WebService::Async::Parser::JSON->new,
      on_complete     => \&on_complete,
      auto_block      => 0, # change block mode to manual
  );
  

  sub on_complete {
      my ( $async, $result ) = @_;
      print "on_complete\n";
      for my $key ( $result->keys ) {
          my $text = $result->get($key)->{responseData}->{translatedText};
          print "  key(@{${key}}): value(${text})\n";
      }
      $cv->send;
  }
  

  $wa->add_get( id => 1, param => { q => 'apple' } );
  $wa->add_get( id => 2, param => { q => 'orange' } );
  $wa->add_get( id => 3, param => { q => 'grape' } );
  $wa->send_request;
  $cv->recv;    # You have to block by your responsibility.

### RESULTS

  on_complete
    key(id 2): value(arancione)
    key(id 3): value(uva)
    key(id 1): value(mela)

## Example 6. Logging

If you want to using automatic logging, sets the Log::Dispatch instance to the logger attribute. 

### SOURCE

  use WebService::Async;
  use WebService::Async::Parser::JSON;
  use FindBin qw($Bin);
  

  use Log::Dispatch::Config;
  use Log::Dispatch::Configurator::YAML;
  my $configure =
    Log::Dispatch::Configurator::YAML->new("${Bin}/log_config.yaml");
  Log::Dispatch::Config->configure($configure);
  my $logger = Log::Dispatch::Config->instance;
  

  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => { v => '1.0', langpair => 'en|it' },
      response_parser => WebService::Async::Parser::JSON->new,
      on_complete     => \&on_complete,
      logger          => $logger,
  );
  

  sub on_complete {
      my ( $async, $result ) = @_;
      print "on_complete\n";
      for my $key ( $result->keys ) {
          my $text = $result->get($key)->{responseData}->{translatedText};
          print "  key(@{${key}}): value(${text})\n";
      }
  }
  

  $wa->add_get( id => 1, param => { q => 'apple' } );
  $wa->add_get( id => 2, param => { q => 'orange' } );
  $wa->add_get( id => 3, param => { q => 'grape' } );
  $wa->send_request;
  

### RESULTS

  [Tue Sep 28 15:48:48 2010] [info] Invoke 'add_get' method. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Push a request into the request queue. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [info] Invoke 'add_get' method. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Push a request into the request queue. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [info] Invoke 'add_get' method. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Push a request into the request queue. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [info] Invoke 'send_request' method. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Start processing request queue. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Set the busy flag is true. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Start processing request: http://ajax.googleapis.com/ajax/services/language/translate?q=grape&v=1.0&langpair=en%7Cit?q=grape&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [info] Does not hit any caches: http://ajax.googleapis.com/ajax/services/language/translate?q=grape&v=1.0&langpair=en%7Cit?q=grape&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Start processing request: http://ajax.googleapis.com/ajax/services/language/translate?q=orange&v=1.0&langpair=en%7Cit?q=orange&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [info] Does not hit any caches: http://ajax.googleapis.com/ajax/services/language/translate?q=orange&v=1.0&langpair=en%7Cit?q=orange&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Start processing request: http://ajax.googleapis.com/ajax/services/language/translate?q=apple&v=1.0&langpair=en%7Cit?q=apple&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [info] Does not hit any caches: http://ajax.googleapis.com/ajax/services/language/translate?q=apple&v=1.0&langpair=en%7Cit?q=apple&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Invoking http_request method [first time] (method=GET url=http://ajax.googleapis.com/ajax/services/language/translate?q=grape&v=1.0&langpair=en%7Cit). at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Invoking http_request method [first time] (method=GET url=http://ajax.googleapis.com/ajax/services/language/translate?q=apple&v=1.0&langpair=en%7Cit). at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:48 2010] [debug] Invoking http_request method [first time] (method=GET url=http://ajax.googleapis.com/ajax/services/language/translate?q=orange&v=1.0&langpair=en%7Cit). at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:49 2010] [debug] Receive a response from http://ajax.googleapis.com/ajax/services/language/translate?q=orange&v=1.0&langpair=en%7Cit?q=orange&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:49 2010] [debug] Parse a response. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:49 2010] [debug] Set a parsed response into the internal store. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:49 2010] [debug] Convert a parsed response to the specified format. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:49 2010] [info] One request is successfully completed. Execute 'on_done' callback. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] Receive a response from http://ajax.googleapis.com/ajax/services/language/translate?q=apple&v=1.0&langpair=en%7Cit?q=apple&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] Parse a response. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] Set a parsed response into the internal store. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] Convert a parsed response to the specified format. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [info] One request is successfully completed. Execute 'on_done' callback. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] Receive a response from http://ajax.googleapis.com/ajax/services/language/translate?q=grape&v=1.0&langpair=en%7Cit?q=grape&v=1.0&langpair=en%7Cit at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] Parse a response. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] Set a parsed response into the internal store. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] Convert a parsed response to the specified format. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [info] One request is successfully completed. Execute 'on_done' callback. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] The request is successfully completed. Clear the busy flag. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [debug] The request is successfully completed. Clear all parsed responses. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Tue Sep 28 15:48:51 2010] [info] All the request is successfully completed. Execute 'on_complete' callback. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  

  on_complete
    key(id 2): value(arancione)
    key(id 3): value(uva)
    key(id 1): value(mela)

## Example 7. Asyncronous Request with response converter

You can customize the response by using a custom function or existing converter classes like WebService::Async::Converter::XMLSimple.

### SOURCE

  use Text::MicroTemplate::DataSection 'render_mt';
  use WebService::Async;
  use WebService::Async::Parser::JSON;
  use WebService::Async::Converter::XMLSimple;
  use WebService::Async::Converter::Function;
  

  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => { v => '1.0', langpair => 'en|it' },
      response_parser => WebService::Async::Parser::JSON->new,
      on_done         => sub {
          my ( $sv, $id, $result ) = @_;
          print "${result}\n";
      },
  );
  

  # It is useless because you can not relate the request to the response.
  # See the "Expected results below".
  $wa->response_converter( WebService::Async::Converter::XMLSimple->new );
  

  # You can customize the response by using a custom function.
  $wa->whole_response_converter(
      WebService::Async::Converter::Function->new( converter => \&_converter ) );
  sub _converter {
      my ( $sv, $request, $parsed_response ) = @_;
      my $converted_reponse =
        render_mt( 'whole_template', $parsed_response )->as_string;
      return $converted_reponse;
  }
  

  # translating
  $wa->add_get( id => 1, lang => 'fr', param => { q => 'apple', langpair => 'en|fr' } );
  $wa->add_get( id => 2, lang => 'it', param => { q => 'orange' } );
  $wa->add_get( id => 3, lang => 'it', param => { q => 'grape' } );
  my $result = $wa->send_request;
  print "${result}\n";
  

  __DATA__
  @@ whole_template
  <results>
  ? for my $key ($_[0]->keys_as_hash) {
  ?   my $text = $_[0]->get($key)->{responseData}->{translatedText};
      <translated id="<?= $key->{id} ?>" lang="<?= $key->{lang} ?>"><?= $text ?></translated>
  ? }
  </results>
  

### RESULTS
  

  --- Output from on_done.
  --- It is useless because you can not relate the request to the response.
  <?xml version="1.0" encoding="UTF-8"?>
  <result>
    <responseData>
      <translatedText>mela</translatedText>
    </responseData>
    <responseDetails></responseDetails>
    <responseStatus>200</responseStatus>
  </result>
  

  <?xml version="1.0" encoding="UTF-8"?>
  <result>
    <responseData>
      <translatedText>uva</translatedText>
    </responseData>
    <responseDetails></responseDetails>
    <responseStatus>200</responseStatus>
  </result>
  

  <?xml version="1.0" encoding="UTF-8"?>
  <result>
    <responseData>
      <translatedText>arancione</translatedText>
    </responseData>
    <responseDetails></responseDetails>
    <responseStatus>200</responseStatus>
  </result>
  ---
  

  --- Output from send_request
  --- Relating the request to the resposne by using the key.
  <results>
      <translated id="3" lang="it">uva</translated>
      <translated id="1" lang="fr">Apple</translated>
      <translated id="2" lang="it">arancione</translated>
  </results>
  ---

## Example 8. Caching with memcached

You can cache the responses by using Cache::Memcached.

The log is outputted when the cache stores or retrieves.

### SOURCE

  use Cache::Memcached;
  use WebService::Async;
  use WebService::Async::Parser::JSON;
  use WebService::Async::ResponseCache;
  

  use FindBin qw($Bin);
  use Log::Dispatch::Config;
  use Log::Dispatch::Configurator::YAML;
  my $configure =
    Log::Dispatch::Configurator::YAML->new("${Bin}/log_config.yaml");
  Log::Dispatch::Config->configure($configure);
  my $logger = Log::Dispatch::Config->instance;
  

  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => {
          v        => '1.0',
          langpair => 'en|fr',
      },
      auto_block      => 1,
      response_parser => WebService::Async::Parser::JSON->new,
      logger          => $logger,
  );
  $wa->response_cache(
      WebService::Async::ResponseCache->new(
          cache => Cache::Memcached->new( { servers => ['localhost:11211'] } )
      )
  );
  $wa->add_get(
      id    => 1,
      lang  => 'en',
      param => { q => 'apple' }
  );
  $wa->add_get(
      id    => 2,
      lang  => 'en',
      param => { q => 'banana' }
  );
  my $result = $wa->send_request();
  

### RESULTS
  

  -- First time execution: setting caches.
  [Wed Sep 29 10:23:25 2010] [info] Does not hit any caches: http://ajax.googleapis.com/ajax/services/language/translate?q=banana&v=1.0&langpair=en%7Cfr at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Wed Sep 29 10:23:25 2010] [info] Does not hit any caches: http://ajax.googleapis.com/ajax/services/language/translate?q=apple&v=1.0&langpair=en%7Cfr at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Wed Sep 29 10:23:25 2010] [debug] Cache set at: http://ajax.googleapis.com/ajax/services/language/translate?q=apple&v=1.0&langpair=en%7Cfr at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Wed Sep 29 10:23:27 2010] [debug] Cache set at: http://ajax.googleapis.com/ajax/services/language/translate?q=banana&v=1.0&langpair=en%7Cfr at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  

  -- Second time execution: retrieving from caches.
  [Wed Sep 29 10:12:52 2010] [info] Cache hit: http://ajax.googleapis.com/ajax/services/language/translate?q=banana&v=1.0&langpair=en%7Cfr?q=banana&v=1.0&langpair=en%7Cfr at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111
  [Wed Sep 29 10:12:52 2010] [info] Cache hit: http://ajax.googleapis.com/ajax/services/language/translate?q=apple&v=1.0&langpair=en%7Cfr?q=apple&v=1.0&langpair=en%7Cfr at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 111

## Example 9. Handling exceptions

This is a list of the prohibited matter.

### SOURCE

  use Try::Tiny;
  use WebService::Async;
  my $cv = AE::cv;
  my $wa = WebService::Async->new(
      base_url => 'http://ajax.googleapis.com/ajax/services/language/translate',
      param    => {
          v        => '1.0',
          langpair => 'en|fr',
      },
      auto_block => 0,
  );
  $wa->add_get( q  => 'apple' );
  $wa->add_get( id => 1, param => { q => 'banana' } );
  

  # The requst key is duplicate.
  try {
      $wa->add_get( id => 1, param => { q => 'banana' } );
  }
  catch {
      warn $_;
  };
  $wa->send_request;
  

  # Cannot change the 'auto_block' attribute while the request queue is processing.
  try {
      $wa->auto_block(1);
  }
  catch {
      warn $_;
  };
  

  # Cannnot send the another request while the request queue is processing.
  try {
      $wa->send_request;
  }
  catch {
      warn $_;
  };
  

  # If the status code of the response header is /^2/,
  # throws "HTTP connection error occurred. The status code is '%s'." exception.
  

### RESULTS
  

  The requst key is duplicate. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 198
      WebService::Async::_add_request('WebService::Async=HASH(0xa086778)', 'GET', 'id', 1, 'param', 'HASH(0xa53db30)') called at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 76
      WebService::Async::add_get('WebService::Async=HASH(0xa086778)', 'id', 1, 'param', 'HASH(0xa53db30)') called at examples/example9.pl line 23
      main::__ANON__() called at /opt/perl/lib/site_perl/5.10.0/Try/Tiny.pm line 76
      eval {...} called at /opt/perl/lib/site_perl/5.10.0/Try/Tiny.pm line 67
      Try::Tiny::try('CODE(0xa08ebd0)', 'Try::Tiny::Catch=REF(0xa4fce78)') called at examples/example9.pl line 27
  

  Cannot change the 'auto_block' attribute while the request queue is processing. at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 43
      Class::MOP::Class:::before('WebService::Async=HASH(0xa086778)', 1) called at /opt/perl/lib/site_perl/5.10.0/i686-linux-thread-multi/Class/MOP/Method/Wrapped.pm line 47
      Class::MOP::Method::Wrapped::__ANON__('WebService::Async=HASH(0xa086778)', 1) called at /opt/perl/lib/site_perl/5.10.0/i686-linux-thread-multi/Class/MOP/Method/Wrapped.pm line 89
      WebService::Async::auto_block('WebService::Async=HASH(0xa086778)', 1) called at examples/example9.pl line 32
      main::__ANON__() called at /opt/perl/lib/site_perl/5.10.0/Try/Tiny.pm line 76
      eval {...} called at /opt/perl/lib/site_perl/5.10.0/Try/Tiny.pm line 67
      Try::Tiny::try('CODE(0xa51a330)', 'Try::Tiny::Catch=REF(0xa53dab0)') called at examples/example9.pl line 36
  

  Cannot send the another request while the request queue is processing. at /opt/perl/lib/site_perl/5.10.0/WebService/Async/Role/RequestProcessor.pm line 221
      WebService::Async::Role::RequestProcessor::_process_request_queue('WebService::Async=HASH(0xa086778)') called at /opt/perl/lib/site_perl/5.10.0/WebService/Async.pm line 93
      WebService::Async::send_request('WebService::Async=HASH(0xa086778)') called at examples/example9.pl line 40
      main::__ANON__() called at /opt/perl/lib/site_perl/5.10.0/Try/Tiny.pm line 76
      eval {...} called at /opt/perl/lib/site_perl/5.10.0/Try/Tiny.pm line 67
      Try::Tiny::try('CODE(0xa51a330)', 'Try::Tiny::Catch=REF(0xa51ae20)') called at examples/example9.pl line 44



## Example 10. Subclassing

See [WebService::Async::Google::TranslateV1_0](http://search.cpan.org/perldoc?WebService::Async::Google::TranslateV1_0)

## Example 11. Proxy Server for Google Translation Service.

This is a more complicated example using Plack, Tatsumaki and Subclassing(WebService::Async::Google::TranslateV1_0).

### SOURCE

  package Translation;
  use Moose;
  extends 'Tatsumaki::Handler';
  

  use Tatsumaki::Application;
  use Encode qw(decode_utf8);
  use WebService::Async::Google::TranslateV1_0;
  

  __PACKAGE__->asynchronous(1);
  

  sub get {
      translate(@_);
  }
  

  sub post {
      translate(@_);
  }
  

  sub translate {
      my ( $self, $arg ) = shift;
      $self->response->content_type('text/xml');
      my $req    = $self->request;
      my $params = $req->parameters;
      my $src    = $params->get('f');
      $params->remove('f');
      my $dest = $params->get('t');
      $params->remove('t');
  

      if ( !defined $src || !defined $dest ) {
          # TODO throws an exception.
      }
      my @dest = split '\|', $dest;
      if ( !@dest ) {
          # TODO throws an exception.
      }
      my $service = WebService::Async::Google::TranslateV1_0->new;
      $service->source_language($src);
      $service->set_destination_languages(@dest);
      $params->each(
          sub {
              $service->set_message( decode_utf8( $_[0] ), $_[1] );
          }
      );
      $service->translate(
          on_each_translation => sub {
              my ( $sv, $id, $res ) = @_;
              $self->stream_write($res);
          },
          on_translation_complete => sub {
              my ( $atg, $all_res ) = @_;
              $self->stream_write($all_res);
              $self->finish;
          },
      );
  }
  

  my $app = Tatsumaki::Application->new( [
        '/translation/api/get' => 'Translation'
        ] );
  return $app;
  

# METHODS

## new(%opt)

Constructor. Create WebService::Async instance.

Available options are:

- base_url

Base url exclude query strings.

- param

Query parameters. HashRef.

- auto_block

1 or 0. Auto blocking or not.

- max_per_host

Maximum per host. $AnyEvent::HTTP::MAX_PER_HOST.

- timeout

Seconds.

- retry_interval

Seconds.

- max_retry_count

If given three, retrying three times on connection error.

- response_parser

WebService::Async::Parser::* instance.

- response_converter

WebService::Async::Converter::* instance.

- whole_response_converter

WebService::Async::Converter::* instance.

- logger

Log::Dispatch instance.

- user_agent

User agent name or alias.
Alias can be 'Windows IE 6', 'Windows Mozilla', 'Mac Safari', 'Mac Mozilla', 'Linux Mozilla', 'Linux Konqueror'.

- on_done

A code reference invoking when a request is done.

- on_complete

A code reference invoking when all requests is completed.

- on_error

A code reference invoking when the error occurs.

- on_critical_error

A code reference invoking when the critical error occurs.

- check_error

A code reference for checking  errors.

- critical_error_message

This is a message that replaces the converted response when the critical error occurs.

See [WebService::Async::Google::TranslateV1_0](http://search.cpan.org/perldoc?WebService::Async::Google::TranslateV1_0)

## get

Sending a get request and blocking.
Returns a converted response.
This method is synchronous use only.

## post

Sending a post request and blocking.
Returns a converted response.
This method is synchronous use only.

## add_get

Creating a get request and queuing it.
Returns a array reference which includes key for access the response.

## add_post

Creating a post request and queuing it.
Returns a array reference which includes key for access the response.

## send_request

Sending all queued requests and blocking;
Returns a converted response.

# SUBCLASSING

For better encapsulation, you can create subclass of WebService::Async to customize the behavior.

See [WebService::Async::Google::TranslateV1_0](http://search.cpan.org/perldoc?WebService::Async::Google::TranslateV1_0).

# PARSERS

If you want to use an existing parsers, see example 2.

Or if you want to create your own parsers such as a WebService::Async::Parser::MessagePack,
see [WebService::Async::Parser::JSON](http://search.cpan.org/perldoc?WebService::Async::Parser::JSON).

# CACHING

See example 8.

# DIAGNOSTICS

- Cannot send the another request while the request queue is processing.

Once you run 'send_request' method, you can not run another one until 'send_request' is finished.

- The requst key is duplicate.

You must avoid to duplicating keys on using 'add_get' or 'add_post' method.

- Cannot change the 'auto_block' attribute while the request queue is processing.

You can not change the 'auto_block' attribute while the request queue is processing.

- HTTP connection error occurred. The status code is '%s'.

Throws If the status code of the response header is not /^2/.

# DEPENDENCIES

- [AnyEvent](http://search.cpan.org/perldoc?AnyEvent)

- [AnyEvent::HTTP](http://search.cpan.org/perldoc?AnyEvent::HTTP)

- [Clone](http://search.cpan.org/perldoc?Clone)

- [Data::UUID](http://search.cpan.org/perldoc?Data::UUID)

- [Data::Section::Simple](http://search.cpan.org/perldoc?Data::Section::Simple)

- [Encode](http://search.cpan.org/perldoc?Encode)

- [Hash::MultiKey](http://search.cpan.org/perldoc?Hash::MultiKey)

- [JSON](http://search.cpan.org/perldoc?JSON)

- [Log::Dispatch::Config](http://search.cpan.org/perldoc?Log::Dispatch::Config)

- [Moose](http://search.cpan.org/perldoc?Moose)

- [MooseX::WithCache](http://search.cpan.org/perldoc?MooseX::WithCache)

- [Regexp::Common](http://search.cpan.org/perldoc?Regexp::Common)

- [Scalar::Util](http://search.cpan.org/perldoc?Scalar::Util)

- L<Smart::Args;>

- [Try::Tiny](http://search.cpan.org/perldoc?Try::Tiny)

- [URI::Escape](http://search.cpan.org/perldoc?URI::Escape)

- [XML::Simple](http://search.cpan.org/perldoc?XML::Simple)

- [Plack::Loader](http://search.cpan.org/perldoc?Plack::Loader)

- [Plack::Request](http://search.cpan.org/perldoc?Plack::Request)

- [Test::Deep](http://search.cpan.org/perldoc?Test::Deep)

- [Test::Exception](http://search.cpan.org/perldoc?Test::Exception)

- [Test::TCP](http://search.cpan.org/perldoc?Test::TCP)

- [Text::MicroTemplate](http://search.cpan.org/perldoc?Text::MicroTemplate)

- [Text::MicroTemplate::DataSection](http://search.cpan.org/perldoc?Text::MicroTemplate::DataSection)

- [UNIVERSAL](http://search.cpan.org/perldoc?UNIVERSAL)

# POD BUGS

This POD does'nt make sense because my English Sux.

The best way to understand the usage of this module is reading the "SYNOPSIS" and "EXAMPLES" section.

# GIT REPOSITORY

http://github.com/keroyonn/p5-WebService-Async

# AUTHOR

keroyonn <keroyon@cpan.org>

# SEE ALSO

- [WebService::Simple](http://search.cpan.org/perldoc?WebService::Simple)

- [Tatsumaki](http://search.cpan.org/perldoc?Tatsumaki)

# LICENSE

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