
			    A W S - Ada Web Server
			    2.2 release / SOAP 1.4

Authors:
   Dmitriy Anisimkov
   Pascal Obry                                              April 14th, 2006



We are happy to announce the availability of the AWS 2.2 release. The API
could change slightly at this stage but should be fairly stable now.

AWS stand for Ada Web Server. It is a small yet powerful HTTP component to
embed in any applications. It means that you can communicate with your
application using a standard Web browser and this without the need for a Web
Server. AWS is fully developed in Ada with GNAT.

AWS support SOAP/WSDL, Server Push, HTTPS/SSL, client HTTP, hotplug
modules...

AWS comes with SOAP/WSDL support, two tools are proposed:

   ada2wsdl   which generates a WSDL document from an Ada spec

   wsdl2aws   which generates stubs/skeletons AWS code from a WSDL document

Both tools have mapping for standard Ada types but also supports Ada
enumerations, character, records and arrays.

The SOAP implementation has been validated on http://validator.soapware.org/.
This on-line service is not anymore available but the current implementation
is validated against the Apache/AXIS SOAP implementation to ensure the
interoperability. Some users have also reported to have used AWS/SOAP with
.NET without trouble.


Changes
-------

Here are the main changes since AWS 2.1 :

   - Remove dependence on IPv6. By default AWS can now built on IPv4 machine
     as before.

   - Improve again the build procedure by using the GNAT Naming project
     support. This avoids copying file around and messing with the makefile.

   - Remove the use of abort statement. One abort was used for the shutdown of
     the line cleaner.

   - Add templates engine new @@INLINE@@ command tag. This make it possible to
     control more finely the output.

   - Add a templates engine routine to release the template cache.

   - Add support for Lazy_Tag. This replaces the previous Context object which
     was not generic enough.

   - Add support for Cursor_Tag. This new tag can be used as an iterator for
     complex data structure. In this case the data remain on the Ada side.

   - New routine Read_Buffer in AWS.Net.Buffered to retrieve the buffer
     content. Can be useful when switching from buffered mode to un-buffered
     mode.

   - Yet another large clean-up in the handling of namespaces to have better
     support of SOAP namespaces in responses. See obsolescent features section
     below.

   - In debug mode, the SOAP/WSDL generated server will output the XML payload
     as received (as-is and before parsing) from the client.

   - Add support for Byte, Unsigned_Long, Unsigned_Int, Unsigned_Short and
     Unsigned_Byte SOAP types.

   - Change Templates_Parser Release routine to use less stack space. Fixes a
     problem found on FreeBSD.

   - Simplify a bit the build procedure as it is not needed to set the
     ADA_PROJECT_PATH to the <aws_root>/.build/projects directory.

   - Work as been done in AWS architecture for better interoperability with
     PolyORB.

   - Fix SOAP/WSDL interoperability problem when the xsi:type information was
     not present in the payload. This has been tested against gSOAP
     implementation.

   - MIME.Content_Type routine has now a default parameter. It is possible to
     specify something else than the application/octet-stream default mime
     type.

   - Add a new dispatcher (Linker) to chain two other dispatchers.

   - Add a Download Manager to free the main server from serving long
     downloads. This Download Manager contains a waiting queue and send
     appropriate response to the client about the status of the download
     (position in the waiting queue, download about to start).

   - Implement a set of JavaScript templates to ease Ajax (Asynchronous
     JavaScript language and XML demos) based developments with AWS.
     This is also known as XML HTTP Requests.

   - Add support for partial downloads on client and server side. AWS can
     now properly answer to download managers that can stop and restart a
     download.

   - Fix handling of names generated by wsdl2aws with -a option.

   - Add new routine in AWS.Status.Session_Timeout to report session timeout.

   - Add new routine to clear the session on the client side. This routine is
     designed to be used when a client explicitly logout from the Web
     application. See AWS.Response.Set.Clear_Session.

   - Add support for Accept/Connect/Shutdown and Error logging to AWS.Net.Log
     package.

   - Add support for user defined communication layer. The AWS communication
     layer can be replaced by a specific one (derived from Socket_Type).

   - The Socket_Type is now controlled. This clean-up the code and it is
     easier to provide user socket implementations.

   - It is now possible to compile SOAP applications using the dynamic
     elaboration model as the SOAP stub/skeletons are now generated
     with a pragma Elaborate_All for all AWS units.

   - Add project files support to Ada2WSDL.

   - Plus many small fixes, enhancements, API comments, and documentation work.


Non upward compatible changes
-----------------------------

Note that the changes listed below can introduce non upward compatibility.
In such a case we try to give proper advice on how to change the code
to work properly. Of course we try to avoid this as much as possible
but we really prefer to have a clean API instead of keeping awkward
implementations.

   - The Templates_Parser Context object has been replaced by the more generic
     Lazy_Tag one. Changing the code to use the new Lazy_Tag is straight
     forward. Context must be renamed to Lazy_Tag, the inherited Callback
     procedure to Value and the spec must be updated to correspond to the
     overridden Value method (see templates_parser.ads).

   - The AWS.Net.Log routines gives Socket_Type parameter instead of
     FD : Integer.

Obsolescent features
--------------------

In each new version we try to be upward compatible with previous
version. This is really important, but in some cases it seems that a
"redesign" of the API would be good in the long term. All obsolescent
features will be listed in this section. Those features will be
removed in the next version. Note that you can check usage of those
features in your application by using the GNAT's -gnatwj option as we
have tagged all obsolescent features with a pragma.

Note that pragma Obsolescent and -gnatwj option is only supported
since GNAT 3.16.

   - SOAP.Message.Payload.Build spec has been changed.
     The previous format was not correct regarding the namespace support.
     Change the code to pass a Name_Space.Object instead of a string. A
     call like:

        Build ("proc_name", Params, "http://ns.org");

     must be change to:

        Build
          ("proc_name", Params,
           SOAP.Name_Space.Create ("awsns", "http://ns.org"));


   - SOAP.Message routines Name_Space and Set_Name_Space have been change
     to take a Name_Space.Object. See above for possible way to change
     the code.

     Default_Name_Space object has been removed. Use AWS.Name_Space.AWS.


Notes
-----

You can have a look at docs/TODO file to see what are the topics that we will
probably implement in future releases.

NOTE: Since we have switched to the .PNG file format we have found that
Netscape Navigator is not able to display the PNG transparent layer properly!

The OpenSSL libraries (optional) distributed are for Windows only. On UNIX
you'll have to build the libraries from sources, it is quite easy to do
so. This has been tested on GNU/Linux without trouble.

The LDAP binding will use the LDAP dynamic library on Windows. On UNIX you
need to build and install OpenLDAP.

See documentation for build information.


Validation
----------

AWS 2.2 has been compiled and tested on:

   Windows XP, GNAT 5.04a, GNAT 5.05w

   GNU/Linux x86, 5.04a, GNAT 5.05w

   Solaris, 5.04a

Others platforms / compiler version combinations have not been tested, it
does not mean that it's not working.

Previous version of AWS have been built on FreeBSD 4.1 and MacOSX.


Known problems
--------------

- There is a bug in Internet Explorer which prevents to download a file when
  the connection is using the SSL encryption and there is the "Cache-Control"
  header set to "no-cache".

  See: http://support.microsoft.com/?kbid=323308


Pointers
--------

AWS User's Mailing List:
   http://lists.act-europe.fr/mailman/listinfo/aws

AWS Home Page (sources and printable documentations in Postscript and PDF):
   http://libre.act-europe.fr/aws

Templates_Parser sources:
   Templates_Parser module (sources and documentation) is provided with AWS
   distribution. Version 8.0 is distributed with AWS 2.1.

   Latest version of this module and the documentation can be found at:

   http://www.obry.org/contrib.html
   http://www.obry.org/templates_parser.html

   Templates_Parser is a very useful add-on for AWS. You should have a look at
   it if you plan to develop a Web application. Templates_Parser permits to
   completely separate the HTML design from the Ada code.

   Some other Templates engine are WebMacro, FreeMarker, PHP, ASP, JSP and
   Velocity. All of them are based on explicit iterators (#foreach with a
   variable) where Templates_Parser is based on implicit ones (you use a more
   intuitive table iterator). Be sure to check the documentation. Only
   the Velocity project has the goal to support complete separation of HTML
   design and code.

GNU/Ada - GNAT

   You need at least GNAT 2005 GPL Edition or GNAT Pro 5.03.

   http://libre.act-europe.fr/GNAT/

Socket binding (Optional) :

   Since AWS 2.1 you need at least version 1.8.4.4 of the Socket binding. Note
   that by default AWS uses GNAT.Sockets. To be able to use AdaSockets with
   AWS you need to copy all the .ali (cp -p) in the directory where the
   libadasockets.a is. This is needed for the GNAT Project support.

   http://www.rfc1149.net/devel/adasockets

XML/Ada (optional):

   You need this library only if you want to use AWS SOAP feature. You need
   at least XML/Ada 1.1.

   http://libre.act-europe.fr/

   Note that it should be possible to use XML/Ada 1.0 but in this case you'll
   have to create the set of project files yourself.

POSIX Binding (optional) :

   for Win32:
      http://www.obry.org/contrib.html

   for UNIX:
      http://www.cs.fsu.edu/~baker/florist.html

OpenSSL library (optional) :

   Sources for UNIX or Win32:
      http://www.openssl.org

   binaries for Win32:
      Included with the main AWS distribution (win32 directory).

   Note that we have used and we distribute (for Win32 platform) OpenSSL
   version 0.9.7d with this AWS release. OpenSSL has been built with
   Mingw GCC version 3.4.1 with -O3 optimization level.

   See OpenSSL license (docs/openssl.license).

OpenLDAP library (optional) :

   Sources for UNIX or Win32:
      http://www.openldap.org/

   binaries for Win32:
      Included with the main AWS distribution (win32 directory). The import
      library will bind to the Microsoft LDAP dynamic library.

Windows Services API (optional):

   To build the runme demo as a Windows NT/2000 services you must download
   the services API made by Ted Dennison for his SETI@Home project.

      http://www.telepath.com/~dennison/Ted/SETI/SETI_Service.html

License
-------

AWS is distributed under the GMGPL (GNAT Modified GPL) license. This license
ensures that commercial applications can be built using AWS. Note that
AWS comes with a set of components. Those components are using a license
compatible with the AWS's one. For information about component's individual
licenses see include/readme.txt.


Reporting bugs
--------------

You can report bugs to:

   Dmitriy Anisimkov	anisimkov@ada-ru.org
   Pascal Obry		pascal@obry.net


AWS User's Mailing List
-----------------------

A good way to keep informed of AWS news and to share experiences with other
AWS users is to register to the AWS dedicated mailing list. See:

   http://lists.act-europe.fr/mailman/listinfo/aws


Contributors
------------

Thanks to the contributors and peoples who send feedbacks, ideas
about AWS. In the early stage of the project this is very valuable.

So thanks goes to Ted Dennison, Wiljan Derks, Sune Falck, David C. Hoos,
Audran Le Baron, Thierry Lelegard, Nicolas Lesbats, Olivier Ramonat,
Jean-Franois Rameau, Maxim Reznik, Jean-Pierre Rosen, Jerme Roussel,
Ariane Sinibardy, Henrik Sundberg.


Thanks to all who have reported bugs and have sent us patches.
