SPECIAL NOTICE
==============
The main feature of this release are the ActiveWorks broker administrative
APIs are enhanced.  They have not been thoroughly tested, they may not even
work in a number of cases.

Some of the demo scripts under bin/ may be broken, if so they will be
repaired in the near future.


INTRODUCTION
============
The Aw.pm module provides a Perl interface to the ActiveWorks libraries.
The Perl script writer may instantiate new Perl objects for ActiveWorks
adapters, clients, events, adapter events, adapter utilities, and dates
with a class hierarchy nearly identical to that of the Java API while
maintaining the expected norms and conveniences of Perl.


Changes
=======
See the "Changes" file provided with each release.


INSTALLATION
============
See the "INSTALL" file.


DOCUMENTATION
=============
POD is forthcoming, see the doc/Aw.html file for a class and method list.
See also the Java and C CADK manuals of ActiveWorks.


LICENSE
=======
GNU GPL vs 2.0 or later.


DISCLAIMERS
===========
In addition to the disclaimers in the GPL: this interface to the ActiveWorks
libraries is NOT in any way endorsed by ActiveSoft or RCN.


FEATURES
========
"Events are Hashes, Hashes are Events"

No need to fuss with adapter config files unless you really want to (I don't).


What it Can Do..
--------------
The provided classes and their methods are sufficient to run simple
adapters.  See the "time_adapter.pl" and "time_test.pl" scripts for
examples.

At RCN we use Perl (5.004_04 and 5.005_03) based adapters in our production
environment that readily handle over 12,000 requests in a day.

Embeds readily in Apache with mod_perl.  See the apache directory for
examples.

Works with either ActiveWorks 3.0 or 4.x libraries.  Comment/Uncomment the
appropriate lines in the Makefile.PL.


What it Can't Do..
----------------
Multiple adapters running simultaneously in a single script are not
guaranteed to operate sanely.

Broker administration.

Not every API that has been mapped into Perl has actually be used.  There
will likely be bugs waiting to snip at the first person to invoke said
methods.

Has not been tested against the ActiveWorks 3.1 libraries.


TODO
====

 *  Admin methods...
 *  Make sure that it is thread safe when multiple adapters live
    in a single script.
 *  Maybe split Aw.xs into component files for each package.


AUTHOR'S COMMENTS
=================
As the Perl slogan goes: "There is more than one way to do it!".
I have certainly found this to be true when working with Perl
primitives for object design.  The initial approach in this
release is to follow the Java API which has the conveniences
of:

  1) Is presumably a well thought out object interface.
  2) Having a design.
  3) It's already documented ;-)
  4) Will look familiar to Java converts.

However the Java API is not always going to be the most natural
to Perl developers and some Perlisms may occasionally be in 
order.  When a Perl shortcut is taken the rule followed is to
provide the shortcut in addition to the Java analog.  This rule
is broken when for how error handling is treated.  No BrokerError
objects are provided.  Instead the Mysql package model is applied.

Finally, the AdapterUtil class is still mysterious in purpose to
me.  In C they seem to be a way to work with callback data
("handles").  In Java there seems to be a bit more to it.  I have
converted some of the routines that expect handles into adapters
methods so the programmer isn't burdened with making implicit
data explicit.  The AdapterUtil class with the same methods is
however provided.


Error Policy
------------
Superimposing the Java API on a Perl API using a C API bore
at least one casualty.  Or enhancement depending on your point
of view.

Like C, Perl does not support the concept of thrown exceptions.
Every Aw Perl method will record broker errors by pointing to
( obj->err ) BrokerErrors returned by the underlying C APIs.
These BrokerError data types are not the default return types
into Perl space.  $! will be set to the value of
awErrorToCompleString starting from the v0.13 release.

Many of the Java methods were "void" in return type while leaving
errors to be detected in the thrown exception.  In such instances
the Perl method will return a boolean  (the "awaBool" type
specifically mapped onto Perl's T_BOOL) to indicate the presence
of errors.  This would be in keeping with other methods that in
both the C and Java APIs do return booleans for success or failure.

Other methods that might return strings or integers likewise set
up error results in the objects error pointer.  In cases where a
new object was the expected return type, an "undef" is returned
on failure.  The cause of the failure may be analyzed by invoking
Aw::Error methods as functions (e.g. $ec = Aw::Error::getCode(); )
or by instantiating a new error object using "last" (vs "new")
$err = last Aw::Error;   In both cases an internal global error
pointer is applied that always points to the last error created
in the XS layer.  Or just check $! as of v0.13.

Classes derived from the Aw::Basic class will have these error
methods available:

	::err  		returns a boolean to indicate the presence of an error.

	::errmsg	returns a string describing the error message equivalent
			to "awErrorToCompleteString".

	::error		returns a Aw::Error object from which addition
			details about the error can be garnered.




Comments and suggestions to:  yacob@rcn.com