Scripting AMQP

The PAL Scripting Language

Introduction
Scripting Commands
Protocol Commands
PAL Implementations
PAL Internals

1. Introduction

PAL - the protocol automation language - is a scripting language designed to automate ASL-modeled protocols, such as the AMQ protocol. PAL is written as XML and combines two sets of functionality:

A simple scripting language.
A set of commands that automate the protocol.

The scripting language functionality provides loops, conditional and repeated blocks, variables etc. The protocol method commands talk to the server and manipulate content.

Sample PAL Scripts

This section is in the form of a tutorial that explains each functionality with an example. Here is a sample PAL script:

<?xml?>
<pal script = "amq_pal_gen">
    <echo>
    Hello world!
    </echo>
</pal>

To compile the script use "pal" command. It will create an executable for you. You can run the executable straight away. Use "-h" option to get command line parameters for the executable.

$ pal hello.pal
2007/03/23 06:46:41: gsl/4 M: Generating hello.c...
Compiling hello...
Linking hello...
$ ./hello
06:46:56: Hello world!
$

Here is a script that demonstrates some of the standard PAL control commands:

<?xml?>
<pal script = "amq_pal_gen">
    <set name = "index" value = "0" />
    <repeat>
        <inc name = "index" />
        <if name = "index" value = "10">
            <break/>
        </if>
        <else>
            <echo>I can count up to $index</echo>
        </else>
    </repeat>
</pal>

And an equivalent, shorter version:

<?xml?>
<pal script = "amq_pal_gen">
    <repeat times = "10" counter = "index">
        <echo>I can count up to $index</echo>
    </repeat>
</pal>

To connect to a server and open a session we use the <session> control command. Here is a script that connects to a server and then echoes the connection properties:

<?xml?>
<pal script = "amq_pal_gen">
    <session>
        <echo>channel_max=$channel_max</echo>
        <echo>frame_max=$frame_max</echo>
        <echo>heartbeat=$heartbeat</echo>
        <echo>server_copyright=$server_copyright</echo>
        <echo>server_host=$server_host</echo>
        <echo>server_information=$server_information</echo>
        <echo>server_platform=$server_platform</echo>
        <echo>server_product=$server_product</echo>
        <echo>version_major=$version_major</echo>
        <echo>version_minor=$version_minor</echo>
    </session>
</pal>

Note that the script does not specify what server to talk to, nor the IP port. These and other options are passed on the command-line. For the standard C PAL implementation run the script executable with "-h" to get a list of all options.

Having established a session we can send methods to the server:

<?xml?>
<pal script = "amq_pal_gen">
    <session>
        <queue_declare queue = "myqueue" />
        <queue_bind queue = "myqueue" exchange = "myexchange" />
        <basic_content size = "64000" message_id = "id-0001" />
        <basic_publish exchange = "myexchange" routing_key = "myqueue" />
        <basic_browse queue = "myqueue" />
        <basic_arrived>
            <echo>Message '$message_id' came back to us</echo>
        </basic_arrived>
        <empty>
            <echo>Message did not come back, this is bad!</echo>
        </empty>
    </session>
</pal>

PAL lets us define often-used method arguments at the 'session' level. These are then inherited to methods that don't explicity specify them. So we can rewrite the above script to make it shorter:

<?xml?>
<pal script = "amq_pal_gen">
    <session
        exchange = "myexchange"
        queue = "myqueue"
        >
        <exchange_declare class = "fanout" />
        <queue_declare />
        <queue_bind />
        <basic_content size = "64000" message_id = "id-0001" />
        <basic_publish routing_key = "myqueue" />
        <basic_browse />
        <basic_arrived>
            <echo>Message '$message_id' came back to us</echo>
        </basic_arrived>
        <empty>
            <echo>Message did not come back, this is bad!</echo>
        </empty>
    </session>
</pal>

We can also create content bodies by reading data from test data files, or by running helper commands. See the 'read' and 'exec' options for the content commands. It's as simple as (for instance):

<basic_content exec = "perl -S myprog.pl" />

Scripts can be made flexible by passing arguments on the command line. Here is a simple example:

<?xml?>
<pal script = "amq_pal_gen">
    <set name = "number" value = "1234" cmdline = "N" />
    <set name = "string" value = "abcd" cmdline = "S" />
    <echo>Number=$number, string=$string</echo>
</pal>

Which we can run with the options -N and -S:

cmdline -N 9999 -S XXXX

Lastly let's look at macros, which are ways of collecting repetitive commands into groups to save time:

<?xml?>
<pal script = "amq_pal_gen">
    <macro name = "queue new">
        <exchange_declare exchange = "stdqueue" class = "fanout" />
        <queue_declare queue = "$queue" />
        <queue_bind queue = "$queue" exchange = "stdqueue" />
    </macro>
    <macro name = "send message">
        <basic_content size = "$size" message_id = "id-$random" />
        <basic_publish exchange = "stdqueue" routing_key = "$queue" />
    </macro>
    <session>
        <set name = "queue" value = "myqueue" />
        <invoke macro = "queue new" />
        <invoke macro = "send message">
            <set name = "size" value = "64000" />
        </invoke>
        <basic_browse queue = "myqueue" />
        <basic_arrived>
            <echo>Message '$message_id' came back to us</echo>
        </basic_arrived>
        <empty>
            <echo>Message did not come back, this is bad!</echo>
        </empty>
    </session>
</pal>

If you use macros to any extent you'll want to look at the <include> command, described in the next section.

2. Scripting Commands

Summary

These are the basic scripting commands, which can be nested to form scripts of any complexity:

invoke  - invoke a macro
server  - start a protocol server
set     - define or modify a variable
inc     - increment a counter variable
dec     - decrement a counter variable
echo    - echo text to the console
abort   - echo text to the console and abort the script
assert  - assert some condition is true
repeat  - repeat a loop some number of times
while   - repeat a loop while some condition is true
break   - exit a loop
if      - execute commands if a condition is true
else    - execute commands if the previous if condition was false
elsif   - combined if and else
wait    - wait for the server to return data

Overall PAL Script Structure

The overall structure of the PAL script is:

<pal script = "amq_pal_gen">
    [ <include filename = "filename" /> ]...
    [ <macro name = "macroname">
        [ script command ]...
      </macro> ]...
    [ <session>
        [ script command ]...
      </session> ]...
</pal>

The Include Command

The <include> command copies the contents of another PAL file into the current script. It has this syntax:

<include filename = "scriptfile" />

The filename must include the file extension (usually .pal). The included file should not have a <pal> level but may contain macros or script commands.

The Macro Command

The <macro> command defines a block of commands that can be reused in as a single command in the script. It has this syntax:

<macro
    name = "macroname">
    [ script command ]...
</macro>

Macros have no effect until they are used through the 'invoke' command.

The Session Command

The <session> command defines a session:

<session
  [ restart = "0 | 1" ]
  [ server = "servername" ]
  [ failover = "msecs" ]
    >
    [ script command ]...
</session>

PAL may in future allow multiple sessions to be started in parallel, but for now sessions are executed serially.
If the restart option is 1, the session will restart in a new connection, whatever the state of previous sessions. If 0, the session will restart in the previous connection, if any.
The servername can be used to test multiple servers in a single script. This option is not used for general-purpose scripts.
If the failover is set to an integer greater than zero, on a broken connection the script will pause for the specified number of milliseconds, and then try to reconnect to the same or alternate server. To use alternate servers, specify multiple server names in the 'server' attribute, seperated by spaces.

The Invoke Command

The <invoke> command expands a macro:

<invoke
    macro = "macroname"
    />

If the macro uses variables in commands, you can set these variables either before the <invoke> command, or inside it, using <set> commands.

The Server Command

The <server> commands starts or restarts a protocol server:

<server
    name = "servername"
  [ stdout = "filename" ]
  [ stderr = "filename" ]
  [ where = "directory" ]
    />

Do not specify a file extension (.exe) or your scripts will not be portable.
If a protocol server was already started, this command stops the server and then restarts it.
Only one protocol server can be started at a time.
The name value can include arbitrary server arguments but not shell redirection commands.
To redirect the server's output, use the stdout and stderr options.

The Timer Command

The <timer> commands shows or resets the script timer.

<timer
  [ action = "show | reset" ]
    />

The action is optional and defaults to "reset".

The Set Command

The <set> command defines a variable. Variables can be strings or integers. You can use variables in repeat, while, and if blocks, and as symbols for templating arguments and strings. Untyped variables are typed according to their value.

<set
    name = "variablename"
  [ value = "newvalue" ]
  [ type = "string | integer" ]
    cmdline = "char"
    />

The value is optional, and defaults to "".
If the value is purely numeric, the type will default to "integer", and if not the type will default to "string".
The cmdline option specifies a single character. Do not use one of the command-line options already used by the PAL implementation (see section at the end of this document).

The Inc Command

The <inc> command increments an integer variable:

<inc
    name = "variablename"
    />

The Dec Command

The <dec> command decrements an integer variable:

<dec
    name = "variablename"
    />

Decrementing a variable below zero is illegal and raises a fatal error. This is done to catch script errors - negative values are normally not meaningful in test scripts.

The Random Command

The <random> command sets a variable to a random value within a specified range:

<random
    name = "variablename"
  [ min = "minvalue" ]
    max = "maxvalue"
    />

The minimum is optional, and defaults to zero.

The Read Command

The <read> command accepts a line of input from the console and assigns this to a variable:

<read
    name = "variablename"
  [ prompt = "promptstring" ]
    />

The prompt is optional; if defined, this will be shown to the user (with no newline) before the console waits for input.

The Echo Command

The <echo> command echoes a line of text:

<echo [trace = "1|2|3"]>line of text</echo>

The text can use variables with the syntax: $variablename.
The trace level set using a command-line switch. Use the help option (-h) on the test program for details.

The Assert Command

The <assert> command tests a condition and aborts the script if the condition is false.

<assert
    name = "variablename"
  [ test = "eq | ne | gt | lt | ge | le" ]
  [ value = "testvalue" ]
    >[line of text]</assert>

The variablename is a script variable, or a connection or session property, or a standard PAL variable.
If the test and value are not specified, they default to "ne" and "0" or "" depending on the type of variable.
If just the test is not specified, it defaults to "eq".
If the assert statement includes a message, this is printed before an assertion failure.

The Repeat Command

The <repeat> command defines an iterative loop, which can run forever or for a specified number of times. The counter is global (do not use the same counter for two nested loops). To access the counter within the repeat loop, use $variablename.

<repeat
  [ counter = "variablename" ]
  [ times = "integer" ]
  [ progress = "integer" ]
    >
    [ script command ]...
</repeat>

If the times attribute is not specified, the loop will run forever or until the script does a <break/>.
The counter does not need to be previously defined. If no counter is specified, the repeat loop will create its own internal counter which cannot then be used as a symbolic value.
If the progress option is set to an integer N, then after every N passes through the loop, the test script will print a dot to the standard error output.

The While Command

The <while> command defines a conditional loop, which runs so long as a specified condition is true:

<while
    name = "variablename"
  [ test = "eq | ne | gt | lt | ge | le" ]
  [ value = "testvalue" ]
  [ counter = "variablename" ]
  [ progress = "integer" ]
    >
    [ script command ]...
</while>

See the <assert> command for an explanation of the test and value properties.
If a counter is specified, this variable is automatically set to zero when the while loop starts and incremented each time the loop runs. You can access the counter variable after the while loop.
If the progress option is set to an integer N, then after every N passes through the loop, the test script will print a dot to the standard error output.

The Break Command

The <break> command exits the enveloping repeat or while loop and has this syntax:

<break/>

The If Command

The <if> command defines a block that is executed if a specific condition is true:

<if
    name = "variablename"
  [ test = "eq | ne | gt | lt | ge | le" ]
  [ value = "testvalue" ]
    >
    [ script command ]...
</if>

See the <assert> command for an explanation of the test and value properties.

The Else Command

The <else> command defines a block that is executed if the previous <if> condition was false:

<else>
    [ script command ]...
</else>

The Elsif Command

The <elsif> command defines a block that is executed if the previous <if> condition was false and some further condition is true:

<elsif
    name = "variablename"
  [ test = "eq | ne | gt | lt | ge | le" ]
  [ value = "testvalue" ]
    >
    [ script command ]...
</elsif>

See the <assert> command for an explanation of the test and value properties.

The Wait Command

The <wait> command pauses the script for a number of milliseconds, or until content is received from the server:

<wait
  [ timeout = "milliseconds" ]
    />

Inside a session the default timeout is 'forever'. Outside a session, the default timeout is 'zero'.

Here is an example of using the <wait> command:

<?xml?>
<pal script = "amq_pal_gen">
    <set name = "index" value = "0" />
    <echo>Waiting without an active connection...</echo>
    <wait timeout = "1000" />
    <session>
        <echo>Waiting inside an active connection...</echo>
        <wait timeout = "1000" />
    </session>
    <echo>OK</echo>
</pal>

The Abort Command

The <abort> command echoes a line of text and halts the script.

<abort>line of text</abort>

The text can use variables with the syntax: $variablename.

The Exit Command

The <exit> command halts the script.

<exit [status = "value"] >

The default status value is 0.

PAL Variables

PAL uses the convention '$name' to allow variable substitution. This is allowed in:

The body of <echo> and <abort> commands.
All attributes except variablenames.

PAL defines all connection and session properties as variables. These are the connection properties:

channel_max - proposed maximum channels.
class_id - failing method class.
frame_max - proposed maximum frame size.
heartbeat - desired heartbeat delay.
host - server to connect to.
known_hosts - list of known hosts.
method_id - failing method ID.
reply_code - reply code from server.
reply_text - localised reply text.
server_copyright - server copyright.
server_host - server hostname and port.
server_information - other server information.
server_name - server instance name.
server_platform - operating platform.
server_product - name of server implementation.
server_version - version of server.
version_major - protocol major version.
version_minor - protocol major version.

These are the session properties:

active - start/stop content frames.
class_id - failing method class.
cluster_id - Cluster id.
consumer_count - number of consumers.
consumer_tag - consumer tag.
content_size - message content size.
delivery_tag - server-assigned delivery tag.
exchange - exchange name.
identifier - staging identifier.
message_count - number of messages in queue.
method_id - failing method ID.
queue - queue name.
redelivered - message is being redelivered.
reply_code - reply code from server.
reply_text - localised reply text.
routing_key - Message routing key.
staged_size - already staged amount.
ticket - access ticket granted by server.

Note that the standard ASL technique for returning values from protocol methods is via the session properties. Thus the variable 'message_count' holds the number of messages after a queue.browse request and a queue.browse-ok response.

PAL also defines these built-in variables:

$script - name of current PAL script.
$connection - 1 if the connection is alive, else 0.
$session - 1 if the session is alive, else 0.
$random - a random integer in the range 0..32767, when used as an insertion value, produces a 4-digit hex string.
$body_size - the body size of the last content to be created, arrived, or returned.

You must not name your own variables using any of the connection, session, or built-in names. PAL resolves a variable reference in this order:

First, in-built variables.
Content properties, inside an arrived/returned loop.
Session properties.
Connection properties.
Script variables and counters.

Here is a sample script that demonstrates various ways of using variables:

<?xml?>
<pal script = "amq_pal_gen">
    <set name = "expect_major"   value = "9" />
    <set name = "exchange_class" value = "fanout" />
    <set name = "queue"          value = "test-queue" />
    <set name = "exchange"       value = "test-exchange" />
    <set name = "times"          value = "100" />
    <set name = "size"           value = "64000" />
    <session
        queue    = "$queue"
        exchange = "$exchange"
        >
        <echo>Connected to $server_product/$server_version - $server_platform</echo>
        <assert name = "version_major" value = "$expect_major" />
        <exchange_declare class = "$exchange_class" />
        <queue_declare />
        <queue_bind />
        <repeat times = "$times" counter = "id">
          <basic_content size = "$size" content_type = "text/html" message_id = "id-$id" />
          <basic_publish routing_key = "$queue" />
        </repeat>
        <repeat>
            <basic_browse />
            <basic_returned>
                <echo>Returned: $message_id</echo>
            </basic_returned>
            <basic_arrived>
                <inc name = "count" />
                <echo>Arrived: $message_id</echo>
            </basic_arrived>
            <empty>
                <break/>
            </empty>
        </repeat>
        <echo>Total number of messages exchanged: $count</echo>
    </session>
</pal>

3. Protocol Commands

General Principles

ASL protocols have the useful property of being very high-level. That is, the protocol methods generally need little or no abstraction to be immediately obvious and useful to application developers. This makes it reasonable in PAL to simply expose the protocol methods directly to the scripting language. This strategy is helped by:

The use of clear and consistent names for methods and method properties.
The use of intelligent defaults for optional properties.

ASL protocols share the same connection and channel initiation and tear-down architecture. The methods used to do this - such as Connection.Tune - are hidden from the PAL developer. Specifically, we hide:

All Connection class methods.
The Channel.Open and Close methods.
All methods sent by the server and received by the client. Since PAL is for client-side automation, these cannot be scripted.

Content Commands

For each content class, PAL provides a command to create the content and set its properties. E.g.

<basic_content
  [ size = "bodysize"  ("1024") ]
  [ fill = "random | null | repeat"  ("random") ]
  [ read = "..." ]
  [ exec = "..." ]
  [ headers = "0|(1)" ]
  [ content_type = "propertyvalue" ]
  [ content_encoding = "propertyvalue" ]
  [ message_id = "propertyvalue" ]
    >
    [ <headers>
      [ <field
            name = "fieldname"
          [ value = "fieldvalue" ]
          [ type = "string | integer"  ("string") ]
            /> ]...
    </headers> ]
  [ content text ]
</basic_content>

The size attribute specifies the size in octets of the content buffer. Its default value is "1024".
The fill attribute specifies the fill mode. It can be "random", which sets the body to random data, or "null", which sets it to binary zeroes, or "repeat", which repeats the content text up to the specified size.
The body of the content item optionally provides a content text. If this is set, it's reformatted as a single line of text, and used as message body. This overrides the default fill ('random').
The read attribute specifies a file from which to read the content body. This is useful when you want to send test messages with a specific format.
The exec attribute specifies a command to run, so that the stdout of the command can be used as the content body. The command must be the name of an executable program, on the path, with arguments as desired. The program receives the current content body as stdin, much like a web server CGI program.
If the headers field is set to zero, the output of the executed program is not reparsed. If one, the output is reparsed to collect message properties and headers as follows: each line specifies a header field name, followed by ":", followed by a space and a value. Field names starting with "x-table-" are stored as-is (minus the x-table- prefix) in a field table with that name. Other fields must match known content properties. Hyphens are allowed in field names, and field names are case-insensitive. The headers are ended with a blank line. Parsed headers create a CGI-like interface for calling programs.
For each content property defined in the protocol (except field tables) PAL defines an attribute for the content command.
For field tables, PAL defines a child entity with the same name, e.g. 'headers'. Field tables are then constructed from one or more <field> definitions.
After a content command, the script can access the content body size as a variables ($body_size in expressions, or body_size in assertions and conditions).

Processing Arrived Content

For each content class, PAL provides a command that lets you process arrived messages. Contents do not necessarily arrive in a strict synchronous order - it depends on the protocol - so this command acts as a loop, and repeats for each arrived content at the moment it is invoked.

<basic_arrived
  [ counter = "variablename" ]
    >
    [ script command ]...
</basic_arrived>
<empty>
    [ script command ]...
</empty>

If a counter is specified, this variable is automatically set to zero when the loop starts and incremented each time the loop runs. You can access the counter variable after the loop.
If there was no arrived content, the script executes the following <empty> command, if any.

You can use these variables within an arrived loop:

$body_text - content body as printable text.
$body_size - size of content body.
$exchange - original exchange to which content was sent.
$routing_key - routing key specified in content.
$producer_id - original producer id.

Processing Returned Content

We process returned content in a similar way to arrived content:

<basic_returned
  [ counter = "variablename" ]
    >
    [ script command ]...
</basic_returned>
<empty>
    [ script command ]...
</empty>

If a counter is specified, this variable is automatically set to zero when the loop starts and incremented each time the loop runs. You can access the counter variable after the loop.
If there was no arrived content, the script executes the following <empty> command, if any.

Synchronous Content Processing

PAL does not provide any asynchronous content processing. The script runs as a single-threaded procedure from start to end. Content will arrive when the script is busy, i.e. during any command that talks to the server. To process content after such commands, use the 'arrived' commands. To process content while not doing such commands, use <wait/> and then use the arrived command.

Protocol Method Commands

A protocol method command sends a protocol method to the server. If the method is a synchronous method, the script waits for a response from the server. If the method is asynchronous, the script continues without waiting. The basic syntax for protocol method commands is:

<class_method [properties...]>
    <field_table_name>
      [ <field
            name = "fieldname"
          [ value = "fieldvalue" ]
          [ type = "string | integer"  ("string") ]
            /> ]...
    </field_table_name>
</class_method>

Properties that are not specified take a default value, which is zero for numeric properties, FALSE for Boolean properties, and NULL for strings and field tables.

The Channel_flow Command

The <channel_flow> command (enable/disable flow from peer):

<channel_flow
    [ active = "start/stop content frames" ]
/>

This method asks the peer to pause or restart the flow of content data. This is a simple flow-control mechanism that a peer can use to avoid oveflowing its queues or otherwise finding itself receiving more messages than it can process. Note that this method is not intended for window control. The peer that receives a request to stop sending content should finish sending the current content, if any, and then wait until it receives a Flow restart method.

The Channel.Flow method accepts the following arguments:

active (bit) - start/stop content frames. If 1, the peer starts sending content frames. If 0, the peer stops sending content frames.

The Channel_flow_ok Command

The <channel_flow_ok> command (confirm a flow method):

<channel_flow_ok
    [ active = "current flow setting" ]
/>

Confirms to the peer that a flow command was received and processed.

The Channel.Flow-Ok method accepts the following arguments:

active (bit) - current flow setting. Confirms the setting of the processed flow method: 1 means the peer will start sending or continue to send content frames; 0 means it will not.

The Access_request Command

The <access_request> command (request an access ticket):

<access_request
    [ realm = "name of requested realm" ]
    [ exclusive = "request exclusive access" ]
    [ passive = "request passive access" ]
    [ active = "request active access" ]
    [ write = "request write access" ]
    [ read = "request read access" ]
/>

This method requests an access ticket for an access realm. The server responds by granting the access ticket. If the client does not have access rights to the requested realm this causes a connection exception. Access tickets are a per-channel resource.

The Access.Request method accepts the following arguments:

realm (shortstr) - name of requested realm. Must start with a slash "/" and continue with path names separated by slashes. A path name consists of any combination of at least one of [A-Za-z0-9] plus zero or more of [.-_+!=:].
exclusive (bit) - request exclusive access. Request exclusive access to the realm. If the server cannot grant this - because there are other active tickets for the realm - it raises a channel exception.
passive (bit) - request passive access. Request message passive access to the specified access realm. Passive access lets a client get information about resources in the realm but not to make any changes to them.
active (bit) - request active access. Request message active access to the specified access realm. Acvtive access lets a client get create and delete resources in the realm.
write (bit) - request write access. Request write access to the specified access realm. Write access lets a client publish messages to all exchanges in the realm.
read (bit) - request read access. Request read access to the specified access realm. Read access lets a client consume messages from queues in the realm.

The Exchange_declare Command

The <exchange_declare> command (declare exchange, create if needed):

<exchange_declare
    [ ticket = "access ticket granted by server" ]
    [ exchange = "exchange name" ]
    [ type = "exchange type" ]
    [ passive = "do not create exchange" ]
    [ durable = "request a durable exchange" ]
    [ auto_delete = "auto-delete when unused" ]
    [ internal = "create internal exchange" ]
/>

This method creates an exchange if it does not already exist, and if the exchange exists, verifies that it is of the correct and expected class.

The Exchange.Declare method accepts the following arguments:

ticket (short) - access ticket granted by server. When a client defines a new exchange, this belongs to the access realm of the ticket used. All further work done with that exchange must be done with an access ticket for the same realm. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
exchange (shortstr) - exchange name. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
type (shortstr) - exchange type. Each exchange belongs to one of a set of exchange types implemented by the server. The exchange types define the functionality of the exchange - i.e. how messages are routed through it. It is not valid or meaningful to attempt to change the type of an existing exchange.
passive (bit) - do not create exchange. If set, the server will not create the exchange. The client can use this to check whether an exchange exists without modifying the server state.
durable (bit) - request a durable exchange. If set when creating a new exchange, the exchange will be marked as durable. Durable exchanges remain active when a server restarts. Non-durable exchanges (transient exchanges) are purged if/when a server restarts.
auto_delete (bit) - auto-delete when unused. If set, the exchange is deleted when all queues have finished using it.
internal (bit) - create internal exchange. If set, the exchange may not be used directly by publishers, but only when bound to other exchanges. Internal exchanges are used to construct wiring that is not visible to applications.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.
arguments (table) - arguments for declaration. A set of arguments for the declaration. The syntax and semantics of these arguments depends on the server implementation. This field is ignored if passive is 1.

The Exchange_declare_nowait Command

The <exchange_declare_nowait> command (declare exchange, create if needed):

<exchange_declare_nowait
    [ ticket = "access ticket granted by server" ]
    [ exchange = "exchange name" ]
    [ type = "exchange type" ]
    [ passive = "do not create exchange" ]
    [ durable = "request a durable exchange" ]
    [ auto_delete = "auto-delete when unused" ]
    [ internal = "create internal exchange" ]
/>

This method creates an exchange if it does not already exist, and if the exchange exists, verifies that it is of the correct and expected class.

The Exchange.Declare method accepts the following arguments:

ticket (short) - access ticket granted by server. When a client defines a new exchange, this belongs to the access realm of the ticket used. All further work done with that exchange must be done with an access ticket for the same realm. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
exchange (shortstr) - exchange name. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
type (shortstr) - exchange type. Each exchange belongs to one of a set of exchange types implemented by the server. The exchange types define the functionality of the exchange - i.e. how messages are routed through it. It is not valid or meaningful to attempt to change the type of an existing exchange.
passive (bit) - do not create exchange. If set, the server will not create the exchange. The client can use this to check whether an exchange exists without modifying the server state.
durable (bit) - request a durable exchange. If set when creating a new exchange, the exchange will be marked as durable. Durable exchanges remain active when a server restarts. Non-durable exchanges (transient exchanges) are purged if/when a server restarts.
auto_delete (bit) - auto-delete when unused. If set, the exchange is deleted when all queues have finished using it.
internal (bit) - create internal exchange. If set, the exchange may not be used directly by publishers, but only when bound to other exchanges. Internal exchanges are used to construct wiring that is not visible to applications.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.
arguments (table) - arguments for declaration. A set of arguments for the declaration. The syntax and semantics of these arguments depends on the server implementation. This field is ignored if passive is 1.

The Exchange_delete Command

The <exchange_delete> command (delete an exchange):

<exchange_delete
    [ ticket = "access ticket granted by server" ]
    [ exchange = "exchange name" ]
    [ if_unused = "delete only if unused" ]
/>

This method deletes an exchange. When an exchange is deleted all queue bindings on the exchange are cancelled.

The Exchange.Delete method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
exchange (shortstr) - exchange name. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
if_unused (bit) - delete only if unused. If set, the server will only delete the exchange if it has no queue bindings. If the exchange has queue bindings the server does not delete it but raises a channel exception instead.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Exchange_delete_nowait Command

The <exchange_delete_nowait> command (delete an exchange):

<exchange_delete_nowait
    [ ticket = "access ticket granted by server" ]
    [ exchange = "exchange name" ]
    [ if_unused = "delete only if unused" ]
/>

This method deletes an exchange. When an exchange is deleted all queue bindings on the exchange are cancelled.

The Exchange.Delete method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
exchange (shortstr) - exchange name. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
if_unused (bit) - delete only if unused. If set, the server will only delete the exchange if it has no queue bindings. If the exchange has queue bindings the server does not delete it but raises a channel exception instead.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Queue_declare Command

The <queue_declare> command (declare queue, create if needed):

<queue_declare
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ passive = "do not create queue" ]
    [ durable = "request a durable queue" ]
    [ exclusive = "request an exclusive queue" ]
    [ auto_delete = "auto-delete queue when unused" ]
/>

This method creates or checks a queue. When creating a new queue the client can specify various properties that control the durability of the queue and its contents, and the level of sharing for the queue.

The Queue.Declare method accepts the following arguments:

ticket (short) - access ticket granted by server. When a client defines a new queue, this belongs to the access realm of the ticket used. All further work done with that queue must be done with an access ticket for the same realm. The client provides a valid access ticket giving "active" access to the realm in which the queue exists or will be created, or "passive" access if the if-exists flag is set. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
passive (bit) - do not create queue. If set, the server will not create the queue. The client can use this to check whether a queue exists without modifying the server state.
durable (bit) - request a durable queue. If set when creating a new queue, the queue will be marked as durable. Durable queues remain active when a server restarts. Non-durable queues (transient queues) are purged if/when a server restarts. Note that durable queues do not necessarily hold persistent messages, although it does not make sense to send persistent messages to a transient queue.
exclusive (bit) - request an exclusive queue. Exclusive queues may only be consumed from by the current connection. Setting the 'exclusive' flag always implies 'auto-delete'.
auto_delete (bit) - auto-delete queue when unused. If set, the queue is deleted when all consumers have finished using it. Last consumer can be cancelled either explicitly or because its channel is closed. If there was no consumer ever on the queue, it won't be deleted.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.
arguments (table) - arguments for declaration. A set of arguments for the declaration. The syntax and semantics of these arguments depends on the server implementation. This field is ignored if passive is 1.

The Queue_declare_nowait Command

The <queue_declare_nowait> command (declare queue, create if needed):

<queue_declare_nowait
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ passive = "do not create queue" ]
    [ durable = "request a durable queue" ]
    [ exclusive = "request an exclusive queue" ]
    [ auto_delete = "auto-delete queue when unused" ]
/>

The Queue.Declare method accepts the following arguments:

ticket (short) - access ticket granted by server. When a client defines a new queue, this belongs to the access realm of the ticket used. All further work done with that queue must be done with an access ticket for the same realm. The client provides a valid access ticket giving "active" access to the realm in which the queue exists or will be created, or "passive" access if the if-exists flag is set. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
passive (bit) - do not create queue. If set, the server will not create the queue. The client can use this to check whether a queue exists without modifying the server state.
durable (bit) - request a durable queue. If set when creating a new queue, the queue will be marked as durable. Durable queues remain active when a server restarts. Non-durable queues (transient queues) are purged if/when a server restarts. Note that durable queues do not necessarily hold persistent messages, although it does not make sense to send persistent messages to a transient queue.
exclusive (bit) - request an exclusive queue. Exclusive queues may only be consumed from by the current connection. Setting the 'exclusive' flag always implies 'auto-delete'.
auto_delete (bit) - auto-delete queue when unused. If set, the queue is deleted when all consumers have finished using it. Last consumer can be cancelled either explicitly or because its channel is closed. If there was no consumer ever on the queue, it won't be deleted.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.
arguments (table) - arguments for declaration. A set of arguments for the declaration. The syntax and semantics of these arguments depends on the server implementation. This field is ignored if passive is 1.

The Queue_bind Command

The <queue_bind> command (bind queue to an exchange):

<queue_bind
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ exchange = "exchange name" ]
    [ routing_key = "message routing key" ]
/>

This method binds a queue to an exchange. Until a queue is bound it will not receive any messages. In a classic messaging model, store-and-forward queues are bound to a dest exchange and subscription queues are bound to a dest_wild exchange.

The Queue.Bind method accepts the following arguments:

ticket (short) - access ticket granted by server. The client provides a valid access ticket giving "active" access rights to the queue's access realm. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to bind. If the queue name is empty, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
exchange (shortstr) - exchange name. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
routing_key (shortstr) - message routing key. Specifies the routing key for the binding. The routing key is used for routing messages depending on the exchange configuration. Not all exchanges use a routing key - refer to the specific exchange documentation. If the routing key is empty and the queue name is empty, the routing key will be the current queue for the channel, which is the last declared queue.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.
arguments (table) - arguments for binding. A set of arguments for the binding. The syntax and semantics of these arguments depends on the exchange class.

The Queue_bind_nowait Command

The <queue_bind_nowait> command (bind queue to an exchange):

<queue_bind_nowait
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ exchange = "exchange name" ]
    [ routing_key = "message routing key" ]
/>

The Queue.Bind method accepts the following arguments:

ticket (short) - access ticket granted by server. The client provides a valid access ticket giving "active" access rights to the queue's access realm. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to bind. If the queue name is empty, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
exchange (shortstr) - exchange name. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
routing_key (shortstr) - message routing key. Specifies the routing key for the binding. The routing key is used for routing messages depending on the exchange configuration. Not all exchanges use a routing key - refer to the specific exchange documentation. If the routing key is empty and the queue name is empty, the routing key will be the current queue for the channel, which is the last declared queue.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.
arguments (table) - arguments for binding. A set of arguments for the binding. The syntax and semantics of these arguments depends on the exchange class.

The Queue_purge Command

The <queue_purge> command (purge a queue):

<queue_purge
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
/>

This method removes all messages from a queue. It does not cancel consumers. Purged messages are deleted without any formal "undo" mechanism.

The Queue.Purge method accepts the following arguments:

ticket (short) - access ticket granted by server. The access ticket must be for the access realm that holds the queue. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to purge. If the queue name is empty, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Queue_purge_nowait Command

The <queue_purge_nowait> command (purge a queue):

<queue_purge_nowait
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
/>

This method removes all messages from a queue. It does not cancel consumers. Purged messages are deleted without any formal "undo" mechanism.

The Queue.Purge method accepts the following arguments:

ticket (short) - access ticket granted by server. The access ticket must be for the access realm that holds the queue. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to purge. If the queue name is empty, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Queue_delete Command

The <queue_delete> command (delete a queue):

<queue_delete
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ if_unused = "delete only if unused" ]
    [ if_empty = "delete only if empty" ]
/>

This method deletes a queue. When a queue is deleted any pending messages are sent to a dead-letter queue if this is defined in the server configuration, and all consumers on the queue are cancelled.

The Queue.Delete method accepts the following arguments:

ticket (short) - access ticket granted by server. The client provides a valid access ticket giving "active" access rights to the queue's access realm. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to delete. If the queue name is empty, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
if_unused (bit) - delete only if unused. If set, the server will only delete the queue if it has no consumers. If the queue has consumers the server does does not delete it but raises a channel exception instead.
if_empty (bit) - delete only if empty. If set, the server will only delete the queue if it has no messages. If the queue is not empty the server raises a channel exception.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Queue_delete_nowait Command

The <queue_delete_nowait> command (delete a queue):

<queue_delete_nowait
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ if_unused = "delete only if unused" ]
    [ if_empty = "delete only if empty" ]
/>

This method deletes a queue. When a queue is deleted any pending messages are sent to a dead-letter queue if this is defined in the server configuration, and all consumers on the queue are cancelled.

The Queue.Delete method accepts the following arguments:

ticket (short) - access ticket granted by server. The client provides a valid access ticket giving "active" access rights to the queue's access realm. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to delete. If the queue name is empty, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
if_unused (bit) - delete only if unused. If set, the server will only delete the queue if it has no consumers. If the queue has consumers the server does does not delete it but raises a channel exception instead.
if_empty (bit) - delete only if empty. If set, the server will only delete the queue if it has no messages. If the queue is not empty the server raises a channel exception.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Basic_qos Command

The <basic_qos> command (specify quality of service):

<basic_qos
    [ prefetch_size = "prefetch window in octets" ]
    [ prefetch_count = "prefetch window in messages" ]
    [ global = "apply to entire connection" ]
/>

This method requests a specific quality of service. The QoS can be specified for the current channel or for all channels on the connection. The particular properties and semantics of a qos method always depend on the content class semantics. Though the qos method could in principle apply to both peers, it is currently meaningful only for the server.

The Basic.Qos method accepts the following arguments:

prefetch_size (long) - prefetch window in octets. The client can request that messages be sent in advance so that when the client finishes processing a message, the following message is already held locally, rather than needing to be sent down the channel. Prefetching gives a performance improvement. This field specifies the prefetch window size in octets. The server will send a message in advance if it is equal to or smaller in size than the available prefetch size (and also falls into other prefetch limits). May be set to zero, meaning "no specific limit", although other prefetch limits may still apply. The prefetch-size is ignored if the no-ack option is set.
prefetch_count (short) - prefetch window in messages. Specifies a prefetch window in terms of whole messages. This field may be used in combination with the prefetch-size field; a message will only be sent in advance if both prefetch windows (and those at the channel and connection level) allow it. The prefetch-count is ignored if the no-ack option is set.
global (bit) - apply to entire connection. By default the QoS settings apply to the current channel only. If this field is set, they are applied to the entire connection.

The Basic_consume Command

The <basic_consume> command (start a queue consumer):

<basic_consume
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ consumer_tag = "consumer tag" ]
    [ no_local = "do not deliver own messages" ]
    [ no_ack = "no acknowledgement needed" ]
    [ exclusive = "request exclusive access" ]
/>

This method asks the server to start a "consumer", which is a transient request for messages from a specific queue. Consumers last as long as the channel they were created on, or until the client cancels them.

The Basic.Consume method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to consume from. If the queue name is null, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
consumer_tag (shortstr) - consumer tag. Specifies the identifier for the consumer. The consumer tag is local to a connection, so two clients can use the same consumer tags. If this field is empty the server will generate a unique tag. Identifier for the consumer, valid within the current connection.
no_local (bit) - do not deliver own messages. If the no-local field is set the server will not send messages to the client that published them.
no_ack (bit) - no acknowledgement needed. If this field is set the server does not expect acknowledgments for messages. That is, when a message is delivered to the client the server automatically and silently acknowledges it on behalf of the client. This functionality increases performance but at the cost of reliability. Messages can get lost if a client dies before it can deliver them to the application.
exclusive (bit) - request exclusive access. Request exclusive consumer access, meaning only this consumer can access the queue.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Basic_consume_nowait Command

The <basic_consume_nowait> command (start a queue consumer):

<basic_consume_nowait
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ consumer_tag = "consumer tag" ]
    [ no_local = "do not deliver own messages" ]
    [ no_ack = "no acknowledgement needed" ]
    [ exclusive = "request exclusive access" ]
/>

The Basic.Consume method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to consume from. If the queue name is null, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
consumer_tag (shortstr) - consumer tag. Specifies the identifier for the consumer. The consumer tag is local to a connection, so two clients can use the same consumer tags. If this field is empty the server will generate a unique tag. Identifier for the consumer, valid within the current connection.
no_local (bit) - do not deliver own messages. If the no-local field is set the server will not send messages to the client that published them.
no_ack (bit) - no acknowledgement needed. If this field is set the server does not expect acknowledgments for messages. That is, when a message is delivered to the client the server automatically and silently acknowledges it on behalf of the client. This functionality increases performance but at the cost of reliability. Messages can get lost if a client dies before it can deliver them to the application.
exclusive (bit) - request exclusive access. Request exclusive consumer access, meaning only this consumer can access the queue.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Basic_cancel Command

The <basic_cancel> command (end a queue consumer):

<basic_cancel
    [ consumer_tag = "consumer tag" ]
/>

This method cancels a consumer. This does not affect already delivered messages, but it does mean the server will not send any more messages for that consumer. The client may receive an abitrary number of messages in between sending the cancel method and receiving the cancel-ok reply.

The Basic.Cancel method accepts the following arguments:

consumer_tag (shortstr) - consumer tag. Identifier for the consumer, valid within the current connection.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Basic_cancel_nowait Command

The <basic_cancel_nowait> command (end a queue consumer):

<basic_cancel_nowait
    [ consumer_tag = "consumer tag" ]
/>

The Basic.Cancel method accepts the following arguments:

consumer_tag (shortstr) - consumer tag. Identifier for the consumer, valid within the current connection.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Basic_publish Command

The <basic_publish> command (publish a message):

<basic_publish
    [ content = "content buffer to transfer" ]
    [ ticket = "access ticket granted by server" ]
    [ exchange = "exchange name" ]
    [ routing_key = "Message routing key" ]
    [ mandatory = "indicate mandatory routing" ]
    [ immediate = "request immediate delivery" ]
/>

This method publishes a message to a specific exchange. The message will be routed to queues as defined by the exchange configuration and distributed to any active consumers when the transaction, if any, is committed.

The Basic.Publish method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
exchange (shortstr) - exchange name. Specifies the name of the exchange to publish to. The exchange name can be empty, meaning the default exchange. If the exchange name is specified, and that exchange does not exist, the server will raise a channel exception. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
routing_key (shortstr) - Message routing key. Specifies the routing key for the message. The routing key is used for routing messages depending on the exchange configuration.
mandatory (bit) - indicate mandatory routing. This flag tells the server how to react if the message cannot be routed to a queue. If this flag is set, the server will return an unroutable message with a Return method. If this flag is zero, the server silently drops the message.
immediate (bit) - request immediate delivery. This flag tells the server how to react if the message cannot be routed to a queue consumer immediately. If this flag is set, the server will return an undeliverable message with a Return method. If this flag is zero, the server will queue the message, but with no guarantee that it will ever be consumed.

The Basic_get Command

The <basic_get> command (direct access to a queue):

<basic_get
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ no_ack = "no acknowledgement needed" ]
/>

This method provides a direct access to the messages in a queue using a synchronous dialogue that is designed for specific types of application where synchronous functionality is more important than performance.

The Basic.Get method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to consume from. If the queue name is null, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
no_ack (bit) - no acknowledgement needed. If this field is set the server does not expect acknowledgments for messages. That is, when a message is delivered to the client the server automatically and silently acknowledges it on behalf of the client. This functionality increases performance but at the cost of reliability. Messages can get lost if a client dies before it can deliver them to the application.

The Basic_ack Command

The <basic_ack> command (acknowledge one or more messages):

<basic_ack
    [ delivery_tag = "server-assigned delivery tag" ]
    [ multiple = "acknowledge multiple messages" ]
/>

This method acknowledges one or more messages delivered via the Deliver or Get-Ok methods. The client can ask to confirm a single message or a set of messages up to and including a specific message.

The Basic.Ack method accepts the following arguments:

delivery_tag (longlong) - server-assigned delivery tag. The server-assigned and channel-specific delivery tag
multiple (bit) - acknowledge multiple messages. If set to 1, the delivery tag is treated as "up to and including", so that the client can acknowledge multiple messages with a single method. If set to zero, the delivery tag refers to a single message. If the multiple field is 1, and the delivery tag is zero, tells the server to acknowledge all outstanding mesages.

The Basic_reject Command

The <basic_reject> command (reject an incoming message):

<basic_reject
    [ delivery_tag = "server-assigned delivery tag" ]
    [ requeue = "requeue the message" ]
/>

This method allows a client to reject a message. It can be used to interrupt and cancel large incoming messages, or return untreatable messages to their original queue.

The Basic.Reject method accepts the following arguments:

delivery_tag (longlong) - server-assigned delivery tag. The server-assigned and channel-specific delivery tag
requeue (bit) - requeue the message. If this field is zero, the message will be discarded. If this bit is 1, the server will attempt to requeue the message.

The File_qos Command

The <file_qos> command (specify quality of service):

<file_qos
    [ prefetch_size = "prefetch window in octets" ]
    [ prefetch_count = "prefetch window in messages" ]
    [ global = "apply to entire connection" ]
/>

The File.Qos method accepts the following arguments:

prefetch_size (long) - prefetch window in octets. The client can request that messages be sent in advance so that when the client finishes processing a message, the following message is already held locally, rather than needing to be sent down the channel. Prefetching gives a performance improvement. This field specifies the prefetch window size in octets. May be set to zero, meaning "no specific limit". Note that other prefetch limits may still apply. The prefetch-size is ignored if the no-ack option is set.
prefetch_count (short) - prefetch window in messages. Specifies a prefetch window in terms of whole messages. This is compatible with some file API implementations. This field may be used in combination with the prefetch-size field; a message will only be sent in advance if both prefetch windows (and those at the channel and connection level) allow it. The prefetch-count is ignored if the no-ack option is set.
global (bit) - apply to entire connection. By default the QoS settings apply to the current channel only. If this field is set, they are applied to the entire connection.

The File_consume Command

The <file_consume> command (start a queue consumer):

<file_consume
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ consumer_tag = "consumer tag" ]
    [ no_local = "do not deliver own messages" ]
    [ no_ack = "no acknowledgement needed" ]
    [ exclusive = "request exclusive access" ]
/>

The File.Consume method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to consume from. If the queue name is null, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
consumer_tag (shortstr) - consumer tag. Specifies the identifier for the consumer. The consumer tag is local to a connection, so two clients can use the same consumer tags. If this field is empty the server will generate a unique tag. Identifier for the consumer, valid within the current connection.
no_local (bit) - do not deliver own messages. If the no-local field is set the server will not send messages to the client that published them.
no_ack (bit) - no acknowledgement needed. If this field is set the server does not expect acknowledgments for messages. That is, when a message is delivered to the client the server automatically and silently acknowledges it on behalf of the client. This functionality increases performance but at the cost of reliability. Messages can get lost if a client dies before it can deliver them to the application.
exclusive (bit) - request exclusive access. Request exclusive consumer access, meaning only this consumer can access the queue.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The File_consume_nowait Command

The <file_consume_nowait> command (start a queue consumer):

<file_consume_nowait
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ consumer_tag = "consumer tag" ]
    [ no_local = "do not deliver own messages" ]
    [ no_ack = "no acknowledgement needed" ]
    [ exclusive = "request exclusive access" ]
/>

The File.Consume method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to consume from. If the queue name is null, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
consumer_tag (shortstr) - consumer tag. Specifies the identifier for the consumer. The consumer tag is local to a connection, so two clients can use the same consumer tags. If this field is empty the server will generate a unique tag. Identifier for the consumer, valid within the current connection.
no_local (bit) - do not deliver own messages. If the no-local field is set the server will not send messages to the client that published them.
no_ack (bit) - no acknowledgement needed. If this field is set the server does not expect acknowledgments for messages. That is, when a message is delivered to the client the server automatically and silently acknowledges it on behalf of the client. This functionality increases performance but at the cost of reliability. Messages can get lost if a client dies before it can deliver them to the application.
exclusive (bit) - request exclusive access. Request exclusive consumer access, meaning only this consumer can access the queue.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The File_cancel Command

The <file_cancel> command (end a queue consumer):

<file_cancel
    [ consumer_tag = "consumer tag" ]
/>

This method cancels a consumer. This does not affect already delivered messages, but it does mean the server will not send any more messages for that consumer.

The File.Cancel method accepts the following arguments:

consumer_tag (shortstr) - consumer tag. Identifier for the consumer, valid within the current connection.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The File_cancel_nowait Command

The <file_cancel_nowait> command (end a queue consumer):

<file_cancel_nowait
    [ consumer_tag = "consumer tag" ]
/>

This method cancels a consumer. This does not affect already delivered messages, but it does mean the server will not send any more messages for that consumer.

The File.Cancel method accepts the following arguments:

consumer_tag (shortstr) - consumer tag. Identifier for the consumer, valid within the current connection.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The File_open Command

The <file_open> command (request to start staging):

<file_open
    [ identifier = "staging identifier" ]
    [ content_size = "message content size" ]
/>

This method requests permission to start staging a message. Staging means sending the message into a temporary area at the recipient end and then delivering the message by referring to this temporary area. Staging is how the protocol handles partial file transfers - if a message is partially staged and the connection breaks, the next time the sender starts to stage it, it can restart from where it left off.

The File.Open method accepts the following arguments:

identifier (shortstr) - staging identifier. This is the staging identifier. This is an arbitrary string chosen by the sender. For staging to work correctly the sender must use the same staging identifier when staging the same message a second time after recovery from a failure. A good choice for the staging identifier would be the SHA1 hash of the message properties data (including the original filename, revised time, etc.).
content_size (longlong) - message content size. The size of the content in octets. The recipient may use this information to allocate or check available space in advance, to avoid "disk full" errors during staging of very large messages.

The File_open_ok Command

The <file_open_ok> command (confirm staging ready):

<file_open_ok
    [ staged_size = "already staged amount" ]
/>

This method confirms that the recipient is ready to accept staged data. If the message was already partially-staged at a previous time the recipient will report the number of octets already staged.

The File.Open-Ok method accepts the following arguments:

staged_size (longlong) - already staged amount. The amount of previously-staged content in octets. For a new message this will be zero.

The File_stage Command

The <file_stage> command (stage message content):

<file_stage
    [ content = "content buffer to transfer" ]
/>

This method stages the message, sending the message content to the recipient from the octet offset specified in the Open-Ok method.

The File_publish Command

The <file_publish> command (publish a message):

<file_publish
    [ ticket = "access ticket granted by server" ]
    [ exchange = "exchange name" ]
    [ routing_key = "Message routing key" ]
    [ mandatory = "indicate mandatory routing" ]
    [ immediate = "request immediate delivery" ]
    [ identifier = "staging identifier" ]
/>

This method publishes a staged file message to a specific exchange. The file message will be routed to queues as defined by the exchange configuration and distributed to any active consumers when the transaction, if any, is committed.

The File.Publish method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
exchange (shortstr) - exchange name. Specifies the name of the exchange to publish to. The exchange name can be empty, meaning the default exchange. If the exchange name is specified, and that exchange does not exist, the server will raise a channel exception. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
routing_key (shortstr) - Message routing key. Specifies the routing key for the message. The routing key is used for routing messages depending on the exchange configuration.
mandatory (bit) - indicate mandatory routing. This flag tells the server how to react if the message cannot be routed to a queue. If this flag is set, the server will return an unroutable message with a Return method. If this flag is zero, the server silently drops the message.
immediate (bit) - request immediate delivery. This flag tells the server how to react if the message cannot be routed to a queue consumer immediately. If this flag is set, the server will return an undeliverable message with a Return method. If this flag is zero, the server will queue the message, but with no guarantee that it will ever be consumed.
identifier (shortstr) - staging identifier. This is the staging identifier of the message to publish. The message must have been staged. Note that a client can send the Publish method asynchronously without waiting for staging to finish.

The File_ack Command

The <file_ack> command (acknowledge one or more messages):

<file_ack
    [ delivery_tag = "server-assigned delivery tag" ]
    [ multiple = "acknowledge multiple messages" ]
/>

This method acknowledges one or more messages delivered via the Deliver method. The client can ask to confirm a single message or a set of messages up to and including a specific message.

The File.Ack method accepts the following arguments:

delivery_tag (longlong) - server-assigned delivery tag. The server-assigned and channel-specific delivery tag
multiple (bit) - acknowledge multiple messages. If set to 1, the delivery tag is treated as "up to and including", so that the client can acknowledge multiple messages with a single method. If set to zero, the delivery tag refers to a single message. If the multiple field is 1, and the delivery tag is zero, tells the server to acknowledge all outstanding mesages.

The File_reject Command

The <file_reject> command (reject an incoming message):

<file_reject
    [ delivery_tag = "server-assigned delivery tag" ]
    [ requeue = "requeue the message" ]
/>

This method allows a client to reject a message. It can be used to return untreatable messages to their original queue. Note that file content is staged before delivery, so the client will not use this method to interrupt delivery of a large message.

The File.Reject method accepts the following arguments:

delivery_tag (longlong) - server-assigned delivery tag. The server-assigned and channel-specific delivery tag
requeue (bit) - requeue the message. If this field is zero, the message will be discarded. If this bit is 1, the server will attempt to requeue the message.

The Stream_qos Command

The <stream_qos> command (specify quality of service):

<stream_qos
    [ prefetch_size = "prefetch window in octets" ]
    [ prefetch_count = "prefetch window in messages" ]
    [ consume_rate = "transfer rate in octets/second" ]
    [ global = "apply to entire connection" ]
/>

The Stream.Qos method accepts the following arguments:

prefetch_size (long) - prefetch window in octets. The client can request that messages be sent in advance so that when the client finishes processing a message, the following message is already held locally, rather than needing to be sent down the channel. Prefetching gives a performance improvement. This field specifies the prefetch window size in octets. May be set to zero, meaning "no specific limit". Note that other prefetch limits may still apply.
prefetch_count (short) - prefetch window in messages. Specifies a prefetch window in terms of whole messages. This field may be used in combination with the prefetch-size field; a message will only be sent in advance if both prefetch windows (and those at the channel and connection level) allow it.
consume_rate (long) - transfer rate in octets/second. Specifies a desired transfer rate in octets per second. This is usually determined by the application that uses the streaming data. A value of zero means "no limit", i.e. as rapidly as possible.
global (bit) - apply to entire connection. By default the QoS settings apply to the current channel only. If this field is set, they are applied to the entire connection.

The Stream_consume Command

The <stream_consume> command (start a queue consumer):

<stream_consume
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ consumer_tag = "consumer tag" ]
    [ no_local = "do not deliver own messages" ]
    [ exclusive = "request exclusive access" ]
/>

The Stream.Consume method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to consume from. If the queue name is null, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
consumer_tag (shortstr) - consumer tag. Specifies the identifier for the consumer. The consumer tag is local to a connection, so two clients can use the same consumer tags. If this field is empty the server will generate a unique tag. Identifier for the consumer, valid within the current connection.
no_local (bit) - do not deliver own messages. If the no-local field is set the server will not send messages to the client that published them.
exclusive (bit) - request exclusive access. Request exclusive consumer access, meaning only this consumer can access the queue.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Stream_consume_nowait Command

The <stream_consume_nowait> command (start a queue consumer):

<stream_consume_nowait
    [ ticket = "access ticket granted by server" ]
    [ queue = "queue name" ]
    [ consumer_tag = "consumer tag" ]
    [ no_local = "do not deliver own messages" ]
    [ exclusive = "request exclusive access" ]
/>

The Stream.Consume method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
queue (shortstr) - queue name. Specifies the name of the queue to consume from. If the queue name is null, refers to the current queue for the channel, which is the last declared queue. The queue name identifies the queue within the vhost. Queue names may consist of any mixture of digits, letters, and underscores.
consumer_tag (shortstr) - consumer tag. Specifies the identifier for the consumer. The consumer tag is local to a connection, so two clients can use the same consumer tags. If this field is empty the server will generate a unique tag. Identifier for the consumer, valid within the current connection.
no_local (bit) - do not deliver own messages. If the no-local field is set the server will not send messages to the client that published them.
exclusive (bit) - request exclusive access. Request exclusive consumer access, meaning only this consumer can access the queue.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Stream_cancel Command

The <stream_cancel> command (end a queue consumer):

<stream_cancel
    [ consumer_tag = "consumer tag" ]
/>

This method cancels a consumer. Since message delivery is asynchronous the client may continue to receive messages for a short while after canceling a consumer. It may process or discard these as appropriate.

The Stream.Cancel method accepts the following arguments:

consumer_tag (shortstr) - consumer tag. Identifier for the consumer, valid within the current connection.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Stream_cancel_nowait Command

The <stream_cancel_nowait> command (end a queue consumer):

<stream_cancel_nowait
    [ consumer_tag = "consumer tag" ]
/>

The Stream.Cancel method accepts the following arguments:

consumer_tag (shortstr) - consumer tag. Identifier for the consumer, valid within the current connection.
nowait (bit) - do not send a reply method. If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

The Stream_publish Command

The <stream_publish> command (publish a message):

<stream_publish
    [ content = "content buffer to transfer" ]
    [ ticket = "access ticket granted by server" ]
    [ exchange = "exchange name" ]
    [ routing_key = "Message routing key" ]
    [ mandatory = "indicate mandatory routing" ]
    [ immediate = "request immediate delivery" ]
/>

This method publishes a message to a specific exchange. The message will be routed to queues as defined by the exchange configuration and distributed to any active consumers as appropriate.

The Stream.Publish method accepts the following arguments:

ticket (short) - access ticket granted by server. An access ticket granted by the server for a certain set of access rights within a specific realm. Access tickets are valid within the channel where they were created, and expire when the channel closes.
exchange (shortstr) - exchange name. Specifies the name of the exchange to publish to. The exchange name can be empty, meaning the default exchange. If the exchange name is specified, and that exchange does not exist, the server will raise a channel exception. The exchange name is a client-selected string that identifies the exchange for publish methods. Exchange names may consist of any mixture of digits, letters, and underscores. Exchange names are scoped by the virtual host.
routing_key (shortstr) - Message routing key. Specifies the routing key for the message. The routing key is used for routing messages depending on the exchange configuration.
mandatory (bit) - indicate mandatory routing. This flag tells the server how to react if the message cannot be routed to a queue. If this flag is set, the server will return an unroutable message with a Return method. If this flag is zero, the server silently drops the message.
immediate (bit) - request immediate delivery. This flag tells the server how to react if the message cannot be routed to a queue consumer immediately. If this flag is set, the server will return an undeliverable message with a Return method. If this flag is zero, the server will queue the message, but with no guarantee that it will ever be consumed.

The Tx_select Command

The <tx_select> command (select standard transaction mode):

<tx_select
/>

This method sets the channel to use standard transactions. The client must use this method at least once on a channel before using the Commit or Rollback methods.

The Tx_commit Command

The <tx_commit> command (commit the current transaction):

<tx_commit
/>

This method commits all messages published and acknowledged in the current transaction. A new transaction starts immediately after a commit.

The Tx_rollback Command

The <tx_rollback> command (abandon the current transaction):

<tx_rollback
/>

This method abandons all messages published and acknowledged in the current transaction. A new transaction starts immediately after a rollback.

The Dtx_select Command

The <dtx_select> command (select standard transaction mode):

<dtx_select
/>

This method sets the channel to use distributed transactions. The client must use this method at least once on a channel before using the Start method.

The Dtx_start Command

The <dtx_start> command (start a new distributed transaction):

<dtx_start
    [ dtx_identifier = "transaction identifier" ]
/>

This method starts a new distributed transaction. This must be the first method on a new channel that uses the distributed transaction mode, before any methods that publish or consume messages.

The Dtx.Start method accepts the following arguments:

dtx_identifier (shortstr) - transaction identifier. The distributed transaction key. This identifies the transaction so that the AMQP server can coordinate with the distributed transaction coordinator.

The Tunnel_request Command

The <tunnel_request> command (sends a tunnelled method):

<tunnel_request
    [ content = "content buffer to transfer" ]
/>

This method tunnels a block of binary data, which can be an encoded AMQP method or other data. The binary data is sent as the content for the Tunnel.Request method.

The Tunnel.Request method accepts the following arguments:

meta_data (table) - meta data for the tunnelled block. This field table holds arbitrary meta-data that the sender needs to pass to the recipient.

4. PAL Implementations

The ANSI C PAL Implementation

Command-Line Arguments

The standard C implementation creates a command-line program that accepts these arguments:

Syntax: program [options...]
Options:
  -s server        Server:port to connect to (localhost)
  -t level         Set trace level (default = 0)
                   0=none, 1=low, 2=medium, 3=high
  -r count         Repeat script count times, 0=forever (1)
  -c               Clock the script (0)
  -a               Animate: show script commands
  -e               Execute in single-step mode (0)
  -q               Quiet mode: no messages
  -v               Show version information
  -h               Show summary of command-line options
The order of arguments is not important. Switches and filenames
are case sensitive. See documentation for detailed information.

Performance Measurements

The -c option clocks the script and produces performance measurement output. Here is an example of a simple stress test script:

<?xml?>
<pal
    name = "stress"
    script = "amq_pal_gen"
    >
    This script sends a large number of messages to a queue and then
    reads them back.  The number of messages can be specified on the
    command-line.
    <session exchange = "myexchange" queue = "myqueue" >
        <set name = "number-of-messages" cmdline = "N" value = "1000" />
        <set name = "message-size" cmdline = "S" value = "1000" />
        <exchange_declare type = "fanout" />
        <queue_declare />
        <queue_bind />
        <repeat times = "$number-of-messages" counter = "index" progress = "100">
            <basic_content size = "$message-size" message_id = "id-$index" />
            <basic_publish routing_key = "myqueue" />
        </repeat>
        <while name = "arrived" test = "lt" value = "$number-of-messages" progress = "100">
            <basic_get />
            <basic_arrived>
                <inc name = "arrived" />
            </basic_arrived>
        </while>
    </session>
</pal>

Which produces this output (the figures are obviously just an example):

...........
...........
16:41:26: I: elapsed time:781 msecs
16:41:26: I: outgoing messages:1000 (976 Kbytes)
16:41:26: I: incoming messages:1000 (976 Kbytes)
16:41:26: I: total messages:2000 (1952 Kbytes) average:2560/sec (2499 Kbytes/sec)
16:41:26: I: message latency min=280 max=410 mean=331 dev=37 msecs

Other Implementations

There are no other implementations of PAL at present.

5. PAL Internals

Terminology

ASL: Abstract Server Language - an iMatix technology for defining protocols and building clients and servers that implement such protocols. ASL is a language, a set of protocol standards, and a set of tools. ASL is itself constructed using XNF.
XNF: XML Normal Form - an iMatix technology for defining XML grammars and building code generators that implement such grammars. XNF is a language, and a set of tools. XNF is constructed using XNF. The key point of XNF is to generate a full validating and denormalising parser and to couple this with hand-written back-end code generators (aka "targets").
GSL: Generator Scripting Lanuage - an iMatix technology used to build code generators. GSL is a scripting language designed to work with tree-structured data (usually XML) and inject this data into a template-driven code generation process. All iMatix code generators are written in GSL, and most are complex enough to benefit from being constructed using XNF.
PAL: Protocol Automation Language - an iMatix technology for writing scripts to automate the client half of a discussion carried out in a protocol built with ASL. PAL is a add-on to ASL.
Session: Another name for "channel". We use "channel" at the protocol level and "session" at the API level, mainly because "session" maps to existing APIs like JMS, while "channel" is common usage for multiplexing networking protocols such as ours.

ASL Refresher

iMatix ASL - the Abstract Server Language - is a protocol and software-construction toolkit we built in order to help develop OpenAMQ. The concept of ASL is loosely based on the concept of formal grammars such as ASN.1, but in typical iMatix fashion is rather more aggressive in aiming to generate high-quality code and documentation.

ASL is a formal language, a grammar. It does not define the low-level wire-protocol but rather the higher-level language that a protocol carries. We describe this language in terms of "methods", grouped into "classes". The specific technology used to carry these methods depends on the specific implementation. Thus, ASL is abstract.

ASL is an extensible framework - a single ASL grammar can be fed to any number of different back-end "targets", each generating some different output. Today we have targets for:

A Standard C implementation of client and server layers.
A Java implementation of client layers.
Documentation in iMatix gurudoc format.

This diagram shows the overall ASL code generation process:

 .----------------.
 |  ASL grammar   |         ASL grammar written as XML files, using
 | for protocol P |         inheritence and other XNF techniques.
 `----------------'
         :
+------------------+
|  ASL front-end   |        GSL parser, generated from asl.xnf.
|      parser      |        using the iMatix XNF toolkit.
+------------------+
         :
 .----------------.
 |  Denormalised, |         Data structure held in memory.
 | validated tree |
 `----------------'
         :
+------------------+
|     Specific     |        GSL code generator, written by hand.
|  back-end target |
+------------------+
         :
 .----------------.
 | Generated text |         Documentation or code as desired.
 |    outputs     |
 `----------------'

We can summarise the approach that drives ASL:

Define an abstract and high-level syntax capable of supporting the full functionality required by all possible protocols in our domain.
Implement the code generators for this abstract syntax.
Use the syntax to define our full protocol.

Note the major benefit of using ASL: writing a large and rich protocol is very cheap, as 100% of the protocol support both at the client and server side is generated, leaving only the functional implementation of the protocol methods as work for the programmer.

Large-scale Testing

By making it cheap to design and implement functionality on top of a standard technical base, ASL also encourages very large and explicit protocols. While a hand-built protocol might use a single method for several purposes, ASL would encourage the definition of several individual methods. This clarity is very pleasant for the application developer, but it means that testing must also happen on a large scale.

This - cheap large-scale testing - is the problem that PAL solves.

The PAL Architecture

These diagrams show how PAL fits into the toolchain. First, the process of constructing a PAL generator for a particular protocol, 'P':

      .----------------.
      |  ASL grammar   |         ASL grammar written as XML files, using
      |    "p.asl"     |         inheritence and other XNF techniques.
      `----------------'
              :
     +------------------+
     |  ASL front-end   |        GSL parser, generated from asl.xnf.
     |      parser      |        using the iMatix XNF toolkit.
     |  "asl_gen.gsl"   |
     +------------------+
              :
      .----------------.
      |  Denormalised, |         Data structure held in memory.
      | validated tree |
      `----------------'
              :
     +------------------+
     |       PAL        |        GSL code generator, hand-made.
     |  back-end target |
     |   "asl_pal.gsl"  |
     +------------------+
        :           :
+-----------+   +-----------+
|  PAL XNF  |   |  PAL stdc |    GSL code generators, hand-made
|  driver   |   |   driver  |
+-----------+   +-----------+
      :               :
.-----------.         :
|   PAL/P   |         :          XNF grammar of PAL language
|  grammar  |         :          specifically for protocol 'P'
`-----------'         :
      :               :
.-----------.   .-----------.
| front-end |   |   stdc    |    Components of a PAL generator
| for PAL/P |   |  target   |    specifically for protocol 'P'
`-----------'   `-----------'

To illustrate, these are the commands that would be used to perform the above chain, for a protocol named 'P':

gsl -target:pal p.asl
gsl p_pal.xnf

Second, the process of turning a PAL script into executable code:

 .----------------.
 |  PAL/P script  |         PAL script written as XML files, using
 |  "example.pal" |         include and other XNF techniques.
 `----------------'
         :
+------------------+
|  PAL/P front-end |        GSL parser, generated from p.asl
|      parser      |        (see previous diagram).
| "p_pal_gen.gsl"  |
+------------------+
         :
 .----------------.
 |  Denormalised, |         Data structure held in memory.
 | validated tree |
 `----------------'
         :
+------------------+
|       stdc       |        GSL code generator, generated from
|  back-end target |        p.asl (see previous diagram).
| "p_pal_stdc.gsl" |
+------------------+
         :
 .----------------.
 |  Source code   |         Generated C test program.
 |  "example.c"   |
 `----------------'

To illustrate, these are the commands that would be used to perform the above chain, for a script called "example":

gsl example.pal

The resulting test program is compiled and linked as usual.

Welcome

Getting Started

OpenAMQ Server

OpenAMQ WireAPI

Community

Footer