Web Object Language Files - Communication Layer

The Communication Abstraction Layer is the servers upper bound towards the client. It hides the complexities of serializing data onto the network transport protocol by providing communication classes that do this automatically. The configuration of this layer is split into two major components: communication classes and transactions. While the communication classes describe what data can be transported over the connection, the transactions describe what operations can be performed.

Communication Classes

An example class can be seen here:
<Class name="Ticket">
  <Base lang="php/client" class="MyBaseClass"/>
  <Enum name="TicketState" refColumn="ticket:status"/>
  <Enum name="StateOfMind">
    <Value name="sad"/>
    <Value name="funny"/>
    <Value name="dontcare"/>
  <Property name="ticketid" type="astring" id="yes"/>
  <Property name="eventid" type="int"/>
  <Property name="priceid" type="int"/>
  <Property name="price" type="Price"/>
  <Property name="status" type="TicketState"/>
  <Property name="orderid" type="int"/>
  <Property name="stateofmind" type="StateOfMind" optional="yes"/>
  <Abstract lang="php"/>
  <Mapping table="ticket">
    <Map column="ticketid"/>
    <Map column="priceid"/>
    <Map property="price">
      <Call lang="php" method="WOPrice::fromtableprice(WTprice::getFromDB($data->getpriceid()))"/>
    <Map column="eventid"/>
    <Map column="status"/>
    <Map column="orderid" property="orderid"/>
The "name" attribute of the Class tag gives the communication class a name by which it can be referenced. The language converters will prefix it with "WO" to make it unique and postfix it with "Abstract" if the class is declared abstract - in this case the user must derive the non-abstract class to make it usable.

Class attributes:
namethe name of the class
abstract(optional) marks the class abstract in all generated language targets
base(optional) marks this class derived from the class given as base, the base class must already exist, this attribute overrides the use of the Base tag

The Base tag can be used to derive the class from a class different from WObject, although that class must be derived from WObject. If you want to derive from a class defined in the WOLF file, use the base attribute instead.

Properties and Types

The Enum tag defines a local enumeration. In most cases they will simply reference an enumeration that has already been defined in a database table with a refColumn attribute (syntax: table:column), but it may also locally define its values by using the same Value tags used for database enums.

The Property tag defines a property of the class that can be read and written to:
namethe name of the property
abstract(optional) marks the property abstract - this automatically makes the class abstract and the user has to overwrite the getter and setter methods
id(optional, default=no) marks the property to identify the instance in a cache
type(mandatory) defines the type of the property, see below

Property types:
intan integer - it is at least a 32bit signed type; it is transported as attribute
astringa string that can be safely stored in a XML attribute
stringa string that is transported as element and can reach any length
EnumNamethe name of an enum defined in the same class is possible, local storage is as integer, transport is as string equalling the symbolic name of the value in an attribute
ClassNamethe name of a defined class makes the property an instance of that class; they are transported as sub-elements of this class
List:*prefixing the type with "List:" makes the property a list of that type - any of the above types can be made into lists; on transport list values are always serialized as elements

Mapping Database Tables

The Mapping tag can be used to provide a shortcut cast between a database table type and the communication class type.

Mappings generate conversions in both directions. However, mappings are only generated for the server side, since the client side does not have a database layer.

If the property attribute is ommitted a property with the same name as the listed column is looked for. If the column attribute is ommitted a column with the same name as the property is looked for. If a property is not listed at all it will be left out of the conversion and hence will remain a null value.

In the normal case of mapping in which no transformations between the database query result and the transport data is necessary it is enough to have just the column and/or property names listed. For more complex cases it is possible to specify code that performs the transformation from the database to the communication class with the Call tag. The method specified should return the desired result as a value valid for that property. It can use the $data variable, which represents the communication class instance that is being worked on and the $table variable that represents the table instance that is being converted from. Mappings are always generated in the order they are listed in the WOLF file, so access is only possible to properties that are listed over the current one.

Classes can be documented by adding Doc subtags. Properties can be documented by adding the description directly into the Property tag. Enum values can be documented by adding the description directly into the Value tag.


<Transaction name="GetTicket" updating="yes">
    <Var name="ticketid" type="astring"/>
  <Call lang="php" method="MyClass::getTicketFunction($this);"/>
    <Var name="ticket" type="Ticket/Full"/>
Each transaction must have a name that identifies it. This name is used in the wire protocol to correctly identify the currently requested transaction. Transaction attributes:
namethe name of the transaction
mode(optional, default=checked) can be used to require less restrictive privileges, see below for values
updatingoptional, tells woc whether the transaction is to be considered writing to the database - the default is given in the global "Database" tag.
nologoptional, if given it excludes the request and/or response from the log file (currently: Qt implementation only), use this for transactions that carry passwords or other sensitive information, see below

Transaction modes:
checkedthe default mode: the session must be authenticated and the user must have the privilege to execute this query
auththe session must be authenticated, but no special privilege is required; this can for example be used for the logout function or a function query information about the session itself
openno session is necessary for this to work; usually this is only done for login

NoLog values:
"request" (or: req)excludes the request body from logging
"response" (or: rsp)excludes the response body from logging
"any" (or: "all" or: "request,response")neither request nor response bodies are logged (only the fact that the transaction happened is logged)

Input defines the input parameters (Var tag) of the transaction (ie. what is sent to the server).

Output defines the data (Var tag) sent back to the client.

Var attributes:
namethe name of the variable
typetype of the attribute; all types allowed for class properties (except enums) are allowed here

The Call tag defines which function is called once the transaction has been checked and authenticated and the input decoded.

Call attributes:
langthe language binding this refers to (currently only "php")
methodthe function to call - this can be any function or method

Transactions are represented as classes. On the client side they are used to execute the query and to represent the result. On the server side they internally verify the input and authenticate the transaction and are then used to take and encode the output or possible error conditions.

The Call should use the $this variable to hand over a reference to the transaction itself. The function called should then use the transactions methods to set the result. Please see the binding documentation for details.

Transactions can be documented by adding Doc tags. Inputs and Outputs can be documented by adding the description directly into the Var tags.

Previous: DB Layer