/XML-OverHTTP/README

http://xml-treepp.googlecode.com/ · #! · 270 lines · 180 code · 90 blank · 0 comment · 0 complexity · bda4935b8a1ef5edb6e2c2037a8d4253 MD5 · raw file

  1. NAME
  2. XML::OverHTTP - A base class for XML over HTTP-styled web service
  3. interface
  4. DESCRIPTION
  5. This module is not used directly from end-users. As a child class of
  6. this, module authors can easily write own interface module for XML over
  7. HTTP-styled web service.
  8. METHODS PROVIDED
  9. This module provides some methods and requires other methods overridden
  10. by child classes. The following methods are to be called in your module
  11. or by its users.
  12. new
  13. This constructor method returns a new object for your users. It accepts
  14. query parameters by hash.
  15. my $api = MyAPI->new( %param );
  16. MyAPI.pm inherits this XML::OverHTTP modules.
  17. add_param
  18. This method adds query parameters for the request.
  19. $api->add_param( %param );
  20. It does not validate key names.
  21. get_param
  22. This method returns a current query parameter.
  23. $api->get_param( 'key' );
  24. treepp
  25. This method returns an XML::TreePP object to make the request.
  26. $api->treepp->get( 'key' );
  27. And you can set its object as well.
  28. my $mytpp = XML::TreePP->new;
  29. $api->treepp( $mytpp );
  30. total_entries, entries_per_page and current_page parameters in $mytpp
  31. are updated.
  32. request
  33. This method makes the request for the web service and returns its
  34. response tree.
  35. my $tree = $api->request;
  36. After calling this method, the following methods are available.
  37. tree
  38. This method returns the whole of the response parsed by XML::TreePP
  39. parser.
  40. my $tree = $api->tree;
  41. Every element is blessed when "elem_class" is defined.
  42. root
  43. This method returns the root element in the response.
  44. my $root = $api->root;
  45. xml
  46. This method returns the response context itself.
  47. print $api->xml, "\n";
  48. code
  49. This method returns the response status code.
  50. my $code = $api->code; # usually "200" when succeeded
  51. page
  52. This method returns a Data::Page object to create page navigation.
  53. my $pager = $api->page;
  54. print "Last page: ", $pager->last_page, "\n";
  55. And you can set its object as well.
  56. my $pager = Data::Page->new;
  57. $api->page( $pager );
  58. pageset
  59. This method returns a Data::Pageset object to create page navigation.
  60. The paging mode is "fixed" as default.
  61. my $pager = $api->pageset;
  62. $pager->pages_per_set( 10 );
  63. print "First page of next page set: ", $page_info->next_set, "\n";
  64. Or set it to "slide" mode if you want.
  65. my $pager = $api->pageset( 'slide' );
  66. page_param
  67. This method returns pair(s) of query key and value to set the page
  68. number for the next request.
  69. my $hash = $api->page_param( $page );
  70. The optional second argument specifies the number of entries per page.
  71. my $hash = $api->page_param( $page, $size );
  72. The optional third argument incluedes some other query parameters.
  73. my $newhash = $api->page_param( $page, $size, $oldhash );
  74. page_query
  75. This method returns a processed query string which is joined by '&'
  76. delimiter.
  77. my $query = $api->page_query(); # current page
  78. my $query = $api->page_query( $page, $size, $hash ); # specified page
  79. METHOD YOU MUST OVERRIDE
  80. You MUST override at least one method below:
  81. url
  82. This is a method to specify the url for the request to the web service.
  83. E.g.,
  84. sub url { 'http://www.example.com/api/V1/' }
  85. METHODS YOU SHOULD OVERRIDE
  86. The methods that you SHOULD override in your module are below:
  87. root_elem
  88. This is a method to specify a root element name in the response. E.g.,
  89. sub root_elem { 'rdf:RDF' }
  90. is_error
  91. This is a method to return "true" value when the response seems to have
  92. error. This returns "undef" when it succeeds. E.g.,
  93. sub is_error { $_[0]->root->{status} != 'OK' }
  94. total_entries
  95. This is a method to return the number of total entries for "Data::Page".
  96. E.g.,
  97. sub total_entries { $_[0]->root->{hits} }
  98. entries_per_page
  99. This is a method to return the number of entries per page for
  100. "Data::Page". E.g.,
  101. sub entries_per_page { $_[0]->root->{-count} }
  102. current_page
  103. This is a method to return the current page number for "Data::Page".
  104. E.g.,
  105. sub current_page { $_[0]->root->{-page} }
  106. page_param
  107. This is a method to return paging parameters for the next request. E.g.,
  108. sub page_param {
  109. my $self = shift;
  110. my $page = shift || $self->current_page();
  111. my $size = shift || $self->entries_per_page();
  112. my $hash = shift || {};
  113. $hash->{page} = $page if defined $page;
  114. $hash->{count} = $size if defined $size;
  115. $hash;
  116. }
  117. When your API uses SQL-like query parameters, offset and limit:
  118. sub page_param {
  119. my $self = shift;
  120. my $page = shift || $self->current_page() or return;
  121. my $size = shift || $self->entries_per_page() or return;
  122. my $hash = shift || {};
  123. $hash->{offset} = ($page-1) * $size;
  124. $hash->{limit} = $size;
  125. $hash;
  126. }
  127. METHODS YOU CAN OVERRIDE
  128. You CAN override the following methods as well.
  129. http_method
  130. This is a method to specify the HTTP method, 'GET' or 'POST', for the
  131. request. This returns 'GET' as default. E.g.,
  132. sub http_method { 'GET' }
  133. default_param
  134. This is a method to specify pairs of default query parameter and its
  135. value for the request. E.g.,
  136. sub default_param { { method => 'search', lang => 'perl' } }
  137. notnull_param
  138. This is a method to specify a list of query parameters which are
  139. required by the web service. E.g.,
  140. sub notnull_param { [qw( api_key secret query )] }
  141. These keys are checked before makeing a request for safe.
  142. query_class
  143. This is a method to specify a class name for query parameters. E.g.,
  144. sub elem_class { 'MyAPI::Query' }
  145. The default value is "undef", it means a normal hash is used instead.
  146. attr_prefix
  147. This is a method to specify a prefix for each attribute in the response
  148. tree. XML::TreePP uses it. E.g.,
  149. sub attr_prefix { '' }
  150. The default prefix is zero-length string "" which is recommended.
  151. text_node_key
  152. This is a method to specify a hash key for text nodes in the response
  153. tree. XML::TreePP uses it. E.g.,
  154. sub text_node_key { '_text' }
  155. The default key is "#text".
  156. elem_class
  157. This is a method to specify a base class name for each element in the
  158. response tree. XML::TreePP uses it. E.g.,
  159. sub elem_class { 'MyAPI::Element' }
  160. The default value is "undef", it means each elements is a just hashref
  161. and not bless-ed.
  162. force_array
  163. This is a method to specify a list of element names which should always
  164. be forced into an array representation in the response tree. XML::TreePP
  165. uses it. E.g.,
  166. sub force_array { [qw( rdf:li item xmlns )] }
  167. force_hash
  168. This is a method to specify a list of element names which should always
  169. be forced into an hash representation in the response tree. XML::TreePP
  170. uses it. E.g.,
  171. sub force_hash { [qw( item image )] }
  172. SEE ALSO
  173. XML::TreePP
  174. <http://www.kawa.net/works/perl/overhttp/overhttp-e.html>
  175. AUTHOR
  176. Yusuke Kawasaki <http://www.kawa.net/>
  177. COPYRIGHT AND LICENSE
  178. Copyright (c) 2007 Yusuke Kawasaki. All rights reserved. This program is
  179. free software; you can redistribute it and/or modify it under the same
  180. terms as Perl itself.