Annotating DDL Elements

The SOAPam Service Definition Wizard translates your DDL dictionary 'definitions' to <type> and <element> elements in your Service Definition File (SDF). However, the <element> element supports features not available in DDL. Though you could modify the Wizard-generated <element> elements to take advantage of these features, you'd have to repeat the modifications if you regenerate your SDF. Instead, you can create 'annotations' on DDL definition elements that the will Wizard recognize and incorporate into your SDF automatically.

A SOAPam annotation is merely a DDL comment on an element in a particular form that the Wizard recognizes:

CODE

*<soapamAttributes attribute-name="attribute-value"/>

where "*" in column one is the DDL comment indicator character; attribute-name and attribute-value are any of the attribute name-value pairs that are valid for the <element> element. Any number of attributes can be specified as a space-separated list of name-value pairs. The values of the specified attributes supersede any that Wizard would ordinarily generate.

SOAPam annotations can coexist with any other DDL comments you may have on a given DDL element. You must, however, include the "?COMMENTS" DDL directive in your DDL source in order to direct the DDL compiler save the comments in the compiled DDL dictionary; otherwise the comments are discarded during compilation and won't be available for the Wizard to read.

Consider the following DDL definition.

TEXT

?COMMENTS
DEF MY-IPM.
  02 REPLY-CODE TYPE BINARY 16.
*<soapamAttributes type="dateTime"/>
  02 TIMESTAMP-VALUE TYPE BINARY 64.
END.

Assume that the DDL element TIMESTAMP-VALUE is actually a 64-bit Julian timestamp value, but because there's no specific corresponding DDL data type, we have to use BINARY 64 to describe it. We'd like to have SOAPam convert the Julian timestamp to (and from) the standard ISO 8601 format that Web service clients understand. SOAPam supports this conversion; we need only to indicate that TIMESTAMP-VALUE should be treated as a 'dateTime' data type. Ordinarily, the Wizard would translate this element as an 8-byte integer data type. If we annotate the DDL as shown above, the following is generated in the SDF:

XML

<type name="my_ipm" size="10">
  <element name="reply_code" type="short" offset="0" size="2"/>
  <element name="timestamp_value" type="dateTime" offset="2" size="8"/>
</type>

Here's another example:

TEXT

?COMMENTS
DEF MY-IPM-ANNOTATED.
  02 REPLY-CODE TYPE BINARY 16.
  02 CONTEXT-DATA-LENGTH PIC 9(4) COMP.
*<soapamAttributes type="hexBinary" sizeIs="context_data_length"/>
  02 CONTEXT-DATA TYPE CHARACTER 256.
END.

In this case, the CONTEXT-DATA element is defined as DDL type CHARACTER 256. Let's say that this element actually may contain non-printable characters so that conversion to a text string (the default behavior) is not possible. To address this issue, we can override the value of the "type" attribute with "hexBinary", which will cause CONTEXT-DATA to converted to a hexadecimal string (e.g. 0123456789ABCDEF). In addition, CONTEXT-DATA is a 'variable length' or "VARCHAR"-like element. Its maximum size is 256 bytes, but its size is given by the CONTEXT-DATA-LENGTH element. We can add the "sizeIs" attribute in the annotation to indicate this fact to SOAPam. Here's what the Wizard now produces:

XML

<type name="my_ipm" size="260">
  <element name="reply_code" type="short" offset="0" size="2"/>
  <element name="context_data_length" type="unsignedShort" offset="2" size="2"/>
  <element name="context_data" type="hexBinary" offset="4" size="256" sizeIs="context_data_length"/>
</type>

One final example:

TEXT

?COMMENTS
DEF MY-IPM.
  02 REPLY-CODE TYPE BINARY 16.
  02 ARRAY-1-COUNT PIC 9(4) COMP.
*<soapamAttributes dependsOn="array_1_count" minOccurs="0"/>
  02 ARRAY-1-ITEM PIC 9(4) COMP OCCURS 20 TIMES.
  02 ARRAY-2-COUNT PIC 9(4) COMP.
  02 ARRAY-2-ITEM PIC 9(4) COMP OCCURS 0 TO 10 TIMES DEPENDING ON ARRAY-2-COUNT.
END.

Here our definition contains two arrays. DDL only will allow the "DEPENDING ON" clause to be used on the last element of the definition, but our first array is, logically, a variable-length array as well. We've annotated the DDL to specify the "dependsOn" element name and the "minOccurs" count. The maximum size of the array will still be allocated for the server interprocess message, but only the actual count of array items will be serialized for the Web service client. The resulting SDF <type> is shown below:

XML

<type name="my_ipm" size="">
  <element name="reply_code" type="short" offset="0" size="2"/>
  <element name="array_1_count" type="unsignedShort" offset="2" size="2"/>
  <element name="array_1_item" type="unsignedShort" minOccurs="0" maxOccurs="20" offset="4" size="2" dependsOn="array_1_count"/>
  <element name="array_2_count" type="unsignedShort" offset="44" size="2"/>
  <element name="array_2_item" type="unsignedShort" minOccurs="0" maxOccurs="10" offset="46" size="2" dependsOn="array_2_count"/>
</type>