Web Object Language Files

WOLF (*.wolf) files are simple XML files that describe the interface layers of PACK.

Overall File Format

Each wolf file must be enclosed in the <Wolf> and </Wolf> tags. The first few statements inside must describe the project itself:
  <Project baseDir=".." wobDir="wob" name="MyProject" encoding="wob" xml-namespace="ns:MyProject" auth="none"/>
  <Version comm="0100" needcomm="0100" humanReadable="1.1 alpha" svnTarget="."/>
Above the <Project> tag tells woc about the project as a whole:
baseDirthe overall project directory (relative to its current working directory); default: current working directory
wobDirrelative to the baseDir, where to find all wolf files, default: baseDir itself
namethe exact name of the project - among other things this property is used as default interface name in the client
encodingthe encoding of the communication: wob the default encoding, transaction objects are transmitted directly, header information is transmitted in the HTTP headers, soap12 a SOAP 1.2 wrapper is put around the transaction, header information is transmitted in the SOAP header, soap shortcut for the currently newest supported SOAP version
xml-namespacethe XML namespace that all transmitted objects are put into, PACK does not validate the namespace, but if you are working in SOAP mode this is mandatory to maintain compatibility with other SOAP implementations; default: "ns:" plus the project name in URL encoding, it is recommended to set a more unique namespace
authAuthentication mode, default none; valid values are: "none" - no authentication at all, the auth property of transactions is ignored, "session" - one of the transactions generates a session ID that can be verified, "basic" - each authenticated transaction transmits the user name and password

The <Doc> tag can be used to create project documentation. Each tag generates one paragraph. HTML can be embedded by escaping the "<" character as "&lt;".

The <Version> tag describes the communication protocol:
commthe communication protocol described by this wolf file
needcommthe minimum communication protocol this wolf file is compatible with (attention: the processor uses ASCII string comparison, not int comparison)
humanReadablethe version number shown to the user
svnTargetoptional; if given: woc will call SVN to find out which repository revision was used
svnExeoptional; executable to call for subversion (default: svn); if empty or not a reachable executable the SVN related fields in the generated code will be set to empty or defaults

The Include tag can be used to include other wolf files in the processing:

<Include file="user.wolf"/>

Attribute Types

Boolean attributes in wolf files allow integers (0 is false, non-zere is true) or the explicit strings "yes", "true", "on" for true and "no", "false", "off" for false.

Integers can be entered in C notation - if it starts with 1 through 9 it is decimal, if it starts with 0 it is octal, if it starts with 0x it is hexadecimal. All integers are interpreted by woc - the generated source will always contain decimal numbers.

Woc itself handles all names as case-sensitive. Some target languages (eg. PHP) may work case-insensitive.

Chosing Outputs

Outputs should be declared after the basics have been declared, but before any tables, classes or transactions are declared.
<QtClientOutput sourceDir="src" subDir="wob" priInclude="wob.pri" transactionBase="WTransaction" validate="no"/>
<QtServerOutput sourceDir="src" subDir="wob" priInclude="wob.pri" transactionBase="WTransaction" validate="no"/>
<PHPServerOutput sourceDir="www" subDir="inc/wob" extension=".php" clean="yes" transactionBase="WobTransaction" validate="no"/>
<HtmlOutput sourceDir="doc" subDir="wob"/>
<SchemaOutput sourceDir="schema" filename="project.xsd" compound="compound.xsd"/>
<SoapOutput sourceDir="soapdir" fileprefix="myproject"/>
The attribute "sourceDir" tells woc which directory (above baseDir) is the root source directory for each sub-project, the "subDir" attribute tells it which subdirectory below the sourceDir should be used for woc's generated output. The attribute "clean" tells woc to first delete all files from that sub-directory before starting the generator. Multiple generators of the same type can be used, but should have different target directories.

The optional validate attribute lets you decide whether incoming messages should be validated against the schema file before processing them. It defaults to "no", which means Schema support is not generated. The value "optional" generates schema support, but does not switch it on, you can control it programmatically. The value "lax" generates schema support, switches it on, but does not stop processing if validation fails. The value "strict" switches schema support on and stops processing if a message fails validation.

The QtClientOutput tag tells woc to create a generator for a Qt based client - the priInclude attribute tells woc which name it should give to the QMake include for its generated output. The transactionBase attribute allows to chose an extended class as base class of generated transactions - usually this should not be necessary for Qt client targets.

The QtServerOutput tag tells woc to create a generator for a Qt based server, the attributes are the same as for the client output.

With both Qt bases outputs you can optionally specify a shareObjects attribute - if present it contains the class prefix for communication objects. If that prefix is different from the one given as classPrefix woc will assume that some other output will create those objects and not create them in this output. This feature is meant for the case in which client and server reside in the same translation unit and share the same objects (transactions and interfaces can unfortunately not be shared).

Another optional attribute is enableExport - set it to "yes" to enable export of the generated symbols in case you compile them into a DLL and want users of that DLL to be able to use the generated classes in their code. Set it to "no" to hide those symbols ("no" is the default).

The PHPServerOutput tag tells woc to create a generator for a PHP based server. The "extension" attribute tells woc which file extension to use for the generated files (default is .php). Woc will automatically create a "autoload" (plus extension) file that should be included from the main body of the PHP project to load the automatically generated classes. The transactionBase attribute allows to chose an extended class as base class of generated transactions - it is recommended to overwrite some protected functions in order to be able to get more information inside transactions.

The HtmlOutput tag tells woc where to generate API documentation. This target generates generic high level documentation for all configured tables, classes, and transactions. Use doxygen or a similar tool to generate language target specific documentation.

The SchemaOutput tag tells woc to generate XML Schema files that validate the projects generated communication XML documents. The filename tag tells woc which file name to use for the classes and transactions - it will contain a complex type for each class (name: class-ClassName), and a simple type for each enum (enum-ClassName-enumName). For each transaction it will generate two global elements, one for the request and one for the responds, including the corresponding complex types. Normal wob encoded communication can be validated directly against this file. If you want to validate errors or SOAP encoded communication you have to specify a compound file name - if specified woc will also copy the relevant Schema files and link them together in the given compound file, which you can use to validate all messages. This output ignores database tables.

The SoapOutput tag tells woc to generate SOAP WSDL and Schema files. This tag generates an error if the project communication mode is not set to use SOAP. This output ignores database tables. The fileprefix attribute is used to construct the WSDL and Schema files by adding the proper extension (".wsdl" and ".xsd") to it.

Next: DataBase Layer