<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
<articleinfo>
<title>ACS Service Contract Documentation</title>
</articleinfo>

<section>
<title>ACS Service Contract Documentation</title>

<section>
<title>Why</title>
<para>

To facilitate greater code reuse, application integration, 
    and package extensibility within the OpenACS.</para>

<para>

To do this acs-service-contract defines an api for the creation
    of interfaces and discovery of interface implementations.</para>


</section>

<section>
<title>Background</title>
<para>

Most component systems are based on the use of interfaces. Interfaces
    allow components to create contracts which define their functional
    level of reuse and customization. It also provides the infrastructure
    for runtime discovery of which implemented interfaces are available.</para>

<para>

The ACS4 is based on a thin object system, that is primarily relational
    but the acs_objects system allows a veneer of object orientedness
    by providing globally unique object ids, object metadata, and bundling
    of data and methods as an object. While this permits a level of
    reuse on an object or package basis, it requires hardcoding the unit 
    of reuse.</para>

<para>

ACS Service contract allows these objects and packages to also 
    define and register their implementation of interfaces, so the level
    of reuse is defined at the contract level. </para>

<para>

In addition ACS Service contract provides mean to dispatch method
    calls on an interface implementation. The dispatch means
    is only available through tcl. </para>

<para>

Interface Discovery is available programmatically as well as via
    documentation through ad_proc.</para>

<para>

The Service Contract interface specification was inspired by
    WDSL, the interface specfication for web services.</para>


</section>

<section>
<title>Hitchiker's Guide to Service Contract Definitions</title>
<itemizedlist>
<listitem><para>
contract - analagous to interface, contracts serve as logical 
                  containers for operations.</para></listitem>
<listitem><para>
operation - a method of an interface. defines a method signature,
                  including both input and outputs as well as metadata
                  such as caching.</para></listitem>
<listitem><para>
implementation - an implementation is a set of concrete functions
                  that fufills an interface.</para></listitem>
<listitem><para>
implementation alias - is the method of an implementation that
                  fufills a given operation of the contract.</para></listitem>
<listitem><para>
bindings - association between an interface and an implementation.</para></listitem>
<listitem><para>
types - define the kind of input and outputs a operation recieves.</para></listitem>
</itemizedlist>

</section>

<section>
<title>Usage</title>

<section>
<title>Design the Contract</title>
<para>

First Off design the interface for your contract, keeping in mind
     that all implementations need to implement it and that extension of
     the contract after deployment is often not practical. In other words
     take the time to do a little future proofing and thinking about 
     possible uses that you weren't planning on.</para>


</section>

<section>
<title>Defining Operations</title>
<para>

Next define the logical operations that will make up your contract</para>


</section>

<section>
<title>Register the Contract</title>
<para>

with acs contracts.</para>


</section>
<para>

Implement the Contract</para>


</section>

<section>
<title>FAQ</title>

<section>
<title>Why Does an implementation reference an interface?</title>
<para>

This might seem a little strange since a binding is the official
     reference between an implementation and an interface. However
     it is quite possible that an implementation for interface might
     exist prior to the interface being defined, ie the interface
     defining package is not installed. By retaining this information
     the interface defining package can be installed and the implementations
     already installed on the system can be bound to it.</para>


</section>

</section>

<section>
<title>Api Reference</title>
<para>

[for oracle please syntax replace __ with .]</para>


<section>
<title>Creating Message Types</title>
<itemizedlist>
<listitem><para>
(sql)::
                 acs_sc_msg_type__new (name, spec):<para>

defines a type based on spec. Spec should
           be a string (possibly emtpy) that defines the
           names and types that compose this type.
           example <literal>ObjectDisplay.Name.InputType</literal>as name
           <literal>object_id:integer</literal>as spec.</para>

</para></listitem>
</itemizedlist>

</section>

<section>
<title>Creating Interfaces </title>
<itemizedlist>
<listitem><para>
(sql):<programlisting>
<![CDATA[
acs_sc_contract__new (contract_name, contract_desc):
]]></programlisting>
</para></listitem>
</itemizedlist>

</section>
<para>

creates a new contract to serve as a logical 
           container for operations. contract_desc is a text
           description of the contract.<itemizedlist>
<listitem><para>
(sql):<programlisting>
<![CDATA[
acs_sc_operation__new (contract_name, operation_name,
                      operation_desc, operation_iscachable_p,
                      operation_inputtype, operation_outputtype
                     ):
]]></programlisting>
</para></listitem>
</itemizedlist>
</para>

<para>

creates a new operation as part of a contract.</para>


<section>
<title>Creating Implementations</title>
<itemizedlist>
<listitem><para>
(tcl) acs_sc_proc (contract, operation, impl):
                registers an implementations. ?? why operation</para></listitem>
</itemizedlist>

</section>

<section>
<title>Discovery</title>
<itemizedlist>
<listitem><para>
(tcl) acs_sc_binding_exists_p (contract, impl): 
                returns boolean whether a binding exists between
                a given contract name and implmentation.</para></listitem>
</itemizedlist>

</section>

<section>
<title>Dispatching    </title>
<itemizedlist>
<listitem><para>
(tcl) acs_sc_call (contract, operation, [arguments, impl]):
                calls an operation</para></listitem>
</itemizedlist>

</section>

</section>

<section>
<title>Examples</title>
<para>

Included in the service contract package are examples for oracle
    and postgresql of a trivial contract.</para>

<para>

Also the search contract functions as a non-trivial core contract
    used by openacs4.</para>


</section>

<section>
<title>Further Reading</title>
<para>

Abstract Factory Pattern - GOF </para>

<para>

Component Systems - Clemens Syzperski</para>

<para>

WSDL Spec</para>


</section>

<section>
<title>Credits</title>
<para>

Most content was provided by Neophytos Demetriou. Most of the 
     errors were provided by Kapil Thangavelu.</para>


</section>

</section>
</article>
