OpenACS

neophytosd
committed
MAIN:neophytosd:20011014103623
on 14 Oct 01
acs service contract documentation by kapil thangavelu
openacs-4/.../www/doc/index.html (+167)
  1 <html>
  2 <head><title>ACS Service Contract Documentation</title></head>
  3 <body bgcolor=white text=black>
  4 <pre>
  5 ACS Service Contract Documentation
  6
  7   Why
  8
  9     To facilitate greater code reuse, application integration,
  10     and package extensibility within the OpenACS.
  11
  12     To do this acs-service-contract defines an api for the creation
  13     of interfaces and discovery of interface implementations.
  14
  15   Background
  16
  17     Most component systems are based on the use of interfaces. Interfaces
  18     allow components to create contracts which define their functional
  19     level of reuse and customization. It also provides the infrastructure
  20     for runtime discovery of which implemented interfaces are available.
  21      
  22     The ACS4 is based on a thin object system, that is primarily relational
  23     but the acs_objects system allows a veneer of object orientedness
  24     by providing globally unique object ids, object metadata, and bundling
  25     of data and methods as an object. While this permits a level of
  26     reuse on an object or package basis, it requires hardcoding the unit
  27     of reuse.
  28
  29     ACS Service contract allows these objects and packages to also
  30     define and register their implementation of interfaces, so the level
  31     of reuse is defined at the contract level.
  32   
  33     In addition ACS Service contract provides mean to dispatch method
  34     calls on an interface implementation. The dispatch means
  35     is only available through tcl.
  36
  37     Interface Discovery is available programmatically as well as via
  38     documentation through ad_proc.
  39
  40     The Service Contract interface specification was inspired by
  41     WDSL, the interface specfication for web services.
  42
  43   Hitchiker's Guide to Service Contract Definitions
  44
  45     - contract - analagous to interface, contracts serve as logical
  46                   containers for operations.
  47
  48     - operation - a method of an interface. defines a method signature,
  49                   including both input and outputs as well as metadata
  50                   such as caching.
  51                 
  52     - implementation - an implementation is a set of concrete functions
  53                   that fufills an interface.
  54  
  55     - implementation alias - is the method of an implementation that
  56                   fufills a given operation of the contract.
  57
  58     - bindings - association between an interface and an implementation.
  59
  60     - types - define the kind of input and outputs a operation recieves.
  61
  62   Usage
  63
  64     Design the Contract
  65
  66        First Off design the interface for your contract, keeping in mind
  67      that all implementations need to implement it and that extension of
  68      the contract after deployment is often not practical. In other words
  69      take the time to do a little future proofing and thinking about
  70      possible uses that you weren't planning on.
  71
  72     Defining Operations
  73
  74        Next define the logical operations that will make up your contract
  75     
  76     Register the Contract
  77
  78        with acs contracts.
  79
  80     Implement the Contract
  81
  82   FAQ
  83
  84      Why Does an implementation reference an interface?
  85
  86        This might seem a little strange since a binding is the official
  87      reference between an implementation and an interface. However
  88      it is quite possible that an implementation for interface might
  89      exist prior to the interface being defined, ie the interface
  90      defining package is not installed. By retaining this information
  91      the interface defining package can be installed and the implementations
  92      already installed on the system can be bound to it.
  93
  94   Api Reference
  95  
  96      [for oracle please syntax replace __ with .]
  97
  98      Creating Message Types
  99
  100         - (sql)::
  101                  acs_sc_msg_type__new (name, spec):
  102
  103            defines a type based on spec. Spec should
  104            be a string (possibly emtpy) that defines the
  105            names and types that compose this type.
  106            example 'ObjectDisplay.Name.InputType' as name
  107            'object_id:integer' as spec.
  108
  109      Creating Interfaces
  110
  111         - (sql)::
  112
  113                  acs_sc_contract__new (contract_name, contract_desc):
  114
  115            creates a new contract to serve as a logical
  116            container for operations. contract_desc is a text
  117            description of the contract.
  118
  119         - (sql)::
  120
  121                  acs_sc_operation__new (contract_name, operation_name,
  122                                        operation_desc, operation_iscachable_p,
  123                                        operation_inputtype, operation_outputtype
  124                                       ):
  125
  126            creates a new operation as part of a contract.
  127
  128      Creating Implementations
  129
  130         - (tcl) acs_sc_proc (contract, operation, impl):
  131                 registers an implementations. ?? why operation
  132
  133      Discovery
  134
  135         - (tcl) acs_sc_binding_exists_p (contract, impl):
  136                 returns boolean whether a binding exists between
  137                 a given contract name and implmentation.
  138
  139      Dispatching   
  140
  141         - (tcl) acs_sc_call (contract, operation, [arguments, impl]):
  142                 calls an operation
  143
  144   Examples
  145
  146     Included in the service contract package are examples for oracle
  147     and postgresql of a trivial contract.
  148  
  149     Also the search contract functions as a non-trivial core contract
  150     used by openacs4.
  151
  152   Further Reading
  153
  154      Abstract Factory Pattern - GOF
  155  
  156      Component Systems - Clemens Syzperski
  157
  158      WSDL Spec
  159
  160   Credits
  161
  162      Most content was provided by Neophytos Demetriou. Most of the
  163      errors were provided by Kapil Thangavelu.
  164
  165 </pre>
  166 </body>
  167 </html>