doc/Application-HOWTO.txt

   1 OpenSRF Application development API
   2 -----------------------------------
   3
   4 OpenSRF offers a very simple Application development API to users of the
   5 framework.  All that is required is to create a Perl module that subclasses
   6 the OpenSRF::Application package and register it's methods with the
   7 Method Dispatcher framework.
   8
   9 Each method executes in the OpenSRF::Application namespace as an instance of
  10 the custom Application.  There are some instance methods on this object which
  11 can be used by the method to alter the behavior or response that the method
  12 sends to the client:
  13
  14   $self->api_name  # returns the name of the method as called by the client
  15
  16   $self->method    # returns the actual perl name of the sub implementing the
  17                    # method
  18
  19   my $meth = $self->method_lookup( 'api_name' )
  20                    # constructs a new instance object implementing another
  21                    # method in the same Application package as a subrequest
  22
  23   my ($subresult) = $meth->run( @params )
  24                    # runs the subrequest method and returns the array of
  25                    # results
  26
  27
  28 The method is also handed an OpenSRF::AppRequest object that has been
  29 constructed for the client request that generated the call to the method.
  30 This OpenSRF::AppRequest object is used to communicate back to the client,
  31 passing status messages or streaming response packets.
  32
  33 All that is required to register an Application with OpenSRF is to place a
  34 setting in the configuration file that names the module that implements the
  35 new Application, and to add the new Application's symbolic name to the list of
  36 servers that should be started by OpenSRF.
  37
  38    Example Application
  39    -------------------
  40
  41   # Perl module and package implementing an math server.
  42   package MyMathServer;
  43   use OpenSRF::Application;
  44   use base 'OpenSRF::Application';
  45
  46   sub do_math {
  47      my $self = shift;    # instance of MyMathServer
  48
  49      my $client = shift;  # instance of OpenSRF::AppRequest connected
  50                           # to the client
  51
  52      my $left_side = shift;
  53      my $op = shift;
  54      my $right_side = shift;
  55
  56      return eval "$left_side $op $right_side";
  57   }
  58
  59   __PACKAGE__->register_method(
  60      api_name => 'useless.do_math',
  61      argc => 3,
  62      method => 'do_math'
  63   );
  64
  65   1;
  66
  67
  68
  69   # Another Perl module and package implementing a square-root server on top
  70   # of the previous math server
  71   package MySquareRootServer;
  72   use OpenSRF::Application;
  73   use base 'OpenSRF::Application';
  74   use MyMathServer;
  75
  76   sub sqrt_math {
  77      my $self = shift;    # instance of MySquareRootServer
  78
  79      my $client = shift;  # instance of OpenSRF::AppRequest connected
  80                           # to the client
  81
  82      my $math_method = $self->method_lookup('useless.do_math');
  83      my ($result) = $math_method->run( @_ );
  84
  85      return sqrt( $result );
  86   }
  87
  88   __PACKAGE__->register_method(
  89      api_name => 'simple.sqrt',
  90      argc => 3,
  91      method => 'sqrt_math'
  92   );
  93
  94   1;
  95