The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Couch-DB-0.005
River stage zero No dependents
/ Couch::DB::Result

NAME

Couch::DB::Result - the reply of a CouchDB server call

SYNOPSIS

  # Any call to the CouchDB server result in this object.
  # But call() is for internal library use: avoid!
  my $result = $couch->call($method, $path, %call_options);

  if($result->isReady) { ... }
  if($result)          { ... }   # same
  $result or die;

  my $data = $result->answer;    # raw JSON response
  my $val  = $result->values;    # interpreted response

  # It's not always needed to inspect the document
  if($result->{ok})    { ... }

DESCRIPTION

The result of a call has many faces: it can be a usage error, a server issue, empty, paged, or even delayed. This Result object is able to handle them all. Read the DETAILS chapter below, to understand them all.

This result objects are pretty heavy: it collects request, response, and much more. So: let them run out-of-scope once you have collected your values().

METHODS

Constructors

Couch::DB::Result->new(%options)

For details on the on_* event handlers, see "DETAILS" in Couch::DB.

 -Option   --Default
  couch      <required>
  on_chain   [ ]
  on_error   [ ]
  on_final   [ ]
  on_values  [ ]
  paging     undef
couch => Couch::DB-object
on_chain => CODE|ARRAY

When a request was completed, a new request can be made immediately. This is especially usefull in combination with _delay, and with internal logic.

on_error => CODE|ARRAY

Called each time when the result CODE changes to be "not a success".

on_final => CODE|ARRAY

Called when the Result object has either an error or an success.

on_values => CODE|ARRAY

Provide a sub which translates incoming JSON data from the server, into pure perl.

paging => HASH

When a call support paging, internal information about it is passed in this HASH.

Accessors

Generic accessors, not related to the Result content.

$obj->code()

Returns an HTTP status code (please use HTTP::Status), which reflects the condition of the answer.

$obj->codeName( [$code] )

Return a string which represents the code. For instance, code 200 will produce string "HTTP_OK".

See CouchDB API section 1.1.4: "HTTP Status Codes" for the interpretation of the codes.

$obj->couch()
$obj->isDelayed()
$obj->isReady()
$obj->message()

Returns undef, or a message (string) which explains why the status is as it is.

$obj->status($code, $message)

Set the $code and $message to something else. Your program should probably not do this: it's the library which determines how the result needs to be interpreted.

When the document is collected

$obj->answer(%options)

When the response was received, this returns the received json answer as HASH of raw data: the bare result of the request.

You can better use the values() method, which returns the data in a far more Perlish way: as Perl booleans, DateTime objects, and so on.

$obj->client()

Which client Couch::DB::Client was used in the last action. Initially, none. When the results are ready, the client is known.

$obj->request()

Returns the request (framework specific) object which was used to collect the data.

$obj->response()

When the call was completed, this will return the (framework specific) object which contains the response received.

$obj->values()

Each CouchDB API call knows whether it passes data types which are (potentially) incompatible between JSON and Perl. Those types get converted for you for convenience in your main program.

The raw data is returned with answer(). See "DETAILS" below.

Paging through results

$obj->isLastPage()

Returns a true value when there are no more page elements to be expected. The page() may already be empty.

$obj->nextPageSettings()

Returns the details for the next page to be collected. When you need these details to be saved outside the program, than use pagingState().

$obj->page()

Returns an ARRAY with the elements collected (harvested) for this page. When there are less elements than the requested page size, then there are no more elements in the collections.

$obj->pageIsPartial()

Returns a true value when there should be made another attempt to fill the page upto the the requested page size.

$obj->pagingState(%options)

Returns information about the logical next page for this response, in a format which can be saved into a session.

 -Option       --Default
  max_bookmarks  10
max_bookmarks => INTEGER

When you save this paging information into a session cookie, you should not store many bookmarks, because they are pretty large and do not compress. Random bookmarks are thrown away. Set to '0' to disable this restriction.

When the collecting is delayed

$obj->delayPlan()

Returns the (framework specific) information about actions to be taken to collect the document.

$obj->setFinalResult(\%data, %options)

Fill this Result object with the actual results.

$obj->setResultDelayed($plan, %options)

When defined, the result document is not yet collected. The $plan contains framework specific information how to realize that in a later stage.

DETAILS

This Result objects have many faces. Understand them well, before you start programming with Couch::DB.

Result is an error

The Result object is overloaded to produce a false value when the command did not succeed for any reason.

. Example: without error handler

  my $result = $db->find(...)
      or die $result->message;

. Example: with error handler

  my $result = $db->find(..., on_error => sub { die } );

Delay the result

When your website has only the slightest chance on having users, then you need to use single server processes shared by many website users. Couch::DB implementations will use event-driven programming to make this possible, but your own program should be configured to make use of this to benefit.

Usually, questions to the database are purely serial. This is an easy case to handle, and totally hidden for you, as user of this module. For instance, when you want to query in parallel, you need to prepare multiple queries, and then start them at the same time.

. Example: prepare a query, delayed

  my $find1 = $db->find(..., _delay => 1)
      or die $result->message;  # only preparation errors
  
  if($find1->isDelayed) ...;    # true
  
  my $result = $find1->run
      or die $result->message;  # network/server errors

  # TODO
  my $result = $couch->parallel([$find1, $find2], concurrent => 2);

Understanding values

To bridge the gap between your program and JSON data received, Couch::DB provides templated conversions. This conversion scheme also attempts to hide protocol changes between CouchDB server versions.

  my $result = $couch->client('local')->serverInfo;
  result or die;

  # Try to avoid this:
  print $result->answer->{version}; # string

  # Use this instead:
  print $result->values->{version};  # version object

In some cases, data is added or modified for convenience: to make it compatible with the version your program has been written for. See Couch::DB::new(api).

OVERLOADING

overload: bool

These Return objecs are overloaded to return a false value when there is any error. For delayed collection of data, this status may change after this object is initially created.

SEE ALSO

This module is part of Couch-DB distribution version 0.005, built on June 23, 2024. Website: http://perl.overmeer.net/CPAN/

LICENSE

Copyrights 2024 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/