/ 
SOAP-Lite-ActiveWorks-0.11
River stage zero No dependents
/ SOAP::Transport::ActiveWorks::Lite

NAME

SOAP::Transport::ActiveWorks::Lite - Server/Client side ActiveWorks support for SOAP::Lite for Perl

SYNOPSIS

use SOAP::Lite +autodispatch =>
  uri      => 'activeworks://myBroker:clientGroup@my.active.host:7449',
  proxy    => 'http://my.http.host/aw-soap/',
  on_fault => sub { my($soap, $res) = @_;
    die ref $res ? $res->faultdetail : $soap->transport->status, "\n";
  }
;

print "Remote Time is ", ${ AdapterDevKit::timeRequest->SOAP::publish }{time}, "\n";

DESCRIPTION

The SOAP::Transport::ActiveWorks::Lite class provides support for ActiveWorks URIs to access ActiveWorks brokers through an HTTP proxy server with SOAP structured requests. The package also allows an ActiveWorks adapter to be used as a SOAP server to either invoke arbitrary Perl classes or to publish and return ActiveWorks events specified in a SOAP structure.

This class mirrors the interface of the SOAP::Transport::HTML class which should be referred to for general documentation. The URI differences will be discussed here with example usage.

ACTIVEWORKS URI COMPONENTS

The general schema of an ActiveWorks URI is as follows:

activeworks://<broker>:<client group>@<host>:<port>

All parameters are optional and defaults can be set within the BEGIN section of the SOAP::Transport::ActiveWorks package. The assumed client group is always 'SOAP' and SOAP requests are forwarded to a SOAP adapter (server/soap_adapter.pl is provided) assumed to be running on the default broker.

If an alternative client group is specified the SOAP request is assumed to contain fields corresponding to a named ActiveWorks event available on the broker. See section PSEUDO EVENTS for details.

HTTP PROXY SETTINGS

When using an HTTP server to proxy publish AW events the 'proxy' autodispatcher parameter should be set to your SOAP server URI as you would with a normal SOAP request.

use SOAP::Lite +autodispatch =>
  uri      => 'urn:', # use default broker, client group, etc.
  proxy    => 'http://my.http.host/aw-soap/',
  on_fault => sub { my($soap, $res) = @_;
    die ref $res ? $res->faultdetail : $soap->transport->status, "\n";
  }
;

Note that the SOAP server, 'aw-soap' in this case, must be enabled to dispatch requests to an ActiveWorks handler. The provided Apache::AwSOAP module demonstrates this:

package Apache::AwSOAP;

use strict;
use Apache;
use SOAP::Transport::ActiveWorks::Lite;

my $server = SOAP::Transport::ActiveWorks::Lite::Apache
   -> dispatch_to( '' );


sub handler { $server->handler(@_); }

1;

The client/http-aw-soap-aw-calculator.pl script demonstrates relaying a SOAP envelope from an http server to an ActiveWorks adapter for processing.

To work with your normal soap server, the AwGateway module may be used to relay an ordinary SOAP request as an ActiveWorks event to a broker specified in the autodispatcher 'uri' parameter. See section AwGateway.

USING AN ACTIVEWORKS BROKER AS A SOAP SERVER

The ACTIVEWORKS module along with the soap-lite-adapter.pl allows you to use an ActiveWorks broker as a SOAP server. Like a normal http server the SOAP adapter will instantiate and invoke the class and method specified in a SOAP request. In addition, classes may be mapped onto ActiveWorks events (see section PSEUDO CLASSES), mapped onto an adapter subroutine for special handling (see http-callback-aw-aw-time.pl for a demonstration) and even relayed to an http SOAP server specified in the method URI (see aw-soap-aw-http-calculator.pl for example usage).

The soap-lite-adapter.pl allows an ActiveWorks client to send and receive requests to a broker with a SOAP envelope to take advantage of the SOAP protocol in a purely ActiveWorks environment.

PSEUDO CLASSES

ActiveWorks events may be instantiated and published much like remote classes. With a 'pseudo class' we treat the remote event as if it were just another SOAP class that we want to access remotely.

The difference will be that we can only send a hash reference as an argument and always get a hash type in return (which is in keeping with the Aw package treatment of events as hashes). Also we publish the event with the dummy method '->publish'.

use SOAP::Lite +autodispatch =>
  uri      => 'activeworks://myBroker:clientGroup@my.active.host:7449',
  proxy    => 'http://my.http.host/aw-soap/',
  on_fault => sub { my($soap, $res) = @_;
    die ref $res ? $res->faultdetail : $soap->transport->status, "\n";
  }
;

 #
 # Hash are used to transport ActiveWorks request event data:
 #
 my %request = ();

 #
 # Populate the event fields:
 #
 $request{numbers} = \@Numbers;

 #
 # Reset default publish timeout from 20 seconds:
 #
 $request{_event_timeout} = 40000;

 #
 # Publish event and force returned SOAPStruct type into a hash:
 #
 my %results = %{ AdapterDevKit::calcRequest->SOAP::publish ( \%request ) };

The client script http-pseudo-aw-aw-calculator.pl and http-pseudo-aw-aw-time.pl demonstrate pseudo class usage.

AwGateway

The AwGateway module is a normal SOAP module that you would keep in your "Deployed Modules" directory. With AwGateway you access an ActiveWorks broker through your usual SOAP server and bi-pass the ACTIVEWORKS module altogether.

See the AwGateway full documentation and the accompanying client script http-gateway-aw-aw-calculator.pl demonstration use.

DEPENDENCIES

The Aw package for Perl interfaces to ActiveWorks libraries.
The SOAP-Lite package.

SEE ALSO

See SOAP::Transport::HTTP

COPYRIGHT

Copyright (C) 2000 Paul Kulchenko. All rights reserved.

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

AUTHOR

The SOAP::Transport::ActiveWorks::Lite module was developed by Daniel Yacob and is derived directly from SOAP::Transport::HTTP by Paul Kulchenko.

Daniel Yacob,  L<yacob@rcn.com|mailto:yacob@rcn.com>
Paul Kulchenko,  L<paulclinger@yahoo.com|mailto:paulclinger@yahoo.com>