Signature Field Properties
All the Integration Server services (including adapter services, flow services, and Java services) contain an input and output signature definition that identifies the names and types of the pipeline fields, read or written by the service. For each of these fields, there are also a number of properties that can be used to document the intended use of the field or to create constraints on what data is valid for that field at run time. For more information on these properties, see the webMethods Service Development Help for your release.
In the flow services and Java services, signature fields and their properties can be modified by the user. For the adapter services, the adapter defines resource domains that act as callbacks from the developer tool that allows the adapter to specify the name, data type, and structure of the service's signature while the service is being configured. A separate callback mechanism allows the adapter to control a limited subset of signature field constraint properties.
The signature field constraints that are controlled by the adapter include:
Signature Field Constraint | Field Behavior |
Required | If true, the field must be present on the pipeline. |
Allow null | If false, when the field is present, the field cannot hold a null value. |
Allow unspecified fields | Controls whether the document (record) element can hold fields that are not specifically identified in the signature. This constraint has no effect on non-document-type signature elements. |
The controls for these constraints are disabled so the user can view the value, but not modify it. The remaining properties (that are not related to name and type) are enabled and may be managed like any other service.
Note:
Like other service types, signature constraints are only enforced at run time if the associated Validate input or Validate output check box is selected by the user.
Adapters gain access to a signature field's constraints by overriding the setSignatureProperties() method in the WmAdapterService implementation class. This method is called whenever the adapter service node is saved, and whenever the user views the input/output panel of an unsaved adapter service. Because this call is made while the adapter service changes are still in progress, the call is made against a temporary object that has all metadata parameter settings as existing in the adapter service editor. This is not the same object that is used for runtime service invocations.
The ADK includes three classes that are used to provide access to signature property information.
| |
PipelineVariableProperties | Abstract base class that represents any signature element (field or record). It exposes read access to all common signature element properties (name, data type, comments, etc.) and read/write access to the Required and Allow null constraints. |
PipelineFieldProperties | Subclass of PipelineVariableProperties that represents a single non-document-type field in the signature. It adds read only access to properties that are specific to non-document elements (pick list choices, content type, etc.) |
PipelineRecordProperties | Subclass of PipelineVariableProperties that represents a single document-type element in the signature. It adds read/write access to the Allow unspecified fields property, and methods for accessing the member elements of the record. |
The WmAdapterService.setSignatureProperties() method receives two PipelineRecordProperties objects as arguments, one for the input signature and the other for the output signature. The adapter must use the accessor/navigation methods available through the two PipelineRecordProperties objects to locate the signature elements for which the constraints have to be managed. Within the setSignatureProperties() implementation, it is frequently useful to use the WmAdapterService.inputRecordName() and WmAdapterService.outputRecordName() methods to get the names of the respective signature wrappers (if wrappers are enabled). If a connection is needed to get the constraint information from a connection target, use the WmAdapterService.retrieveConnection() method.
Note:
This is the only place retrieveConnection must be used; using it from the service's execute method causes errors.
The code listing below demonstrates a simple implementation of the signature constraint management.
protected void setSignatureProperties(
PipelineRecordProperties inputSigProps,
PipelineRecordProperties outputSigProps) throws ResourceException
{
if(this._tableName != null)
{
// need a connection to look up info about table being updated
MockDbConnection conn = (MockDbConnection)retrieveConnection();
TableInfo info = conn.getTableInfo(this._tableName);
updateSignatureRecord(inputSigProps, info, _columnNames,
inputRecordName());
updateSignatureRecord(outputSigProps, info, _columnNames,
outputRecordName());
}
}
private void updateSignatureRecord(PipelineRecordProperties inputSigProps,
TableInfo tInfo, String[] columnNames, String wrapperName)
{
PipelineRecordProperties wrapperRec =
(PipelineRecordProperties)inputSigProps.findByPath(wrapperName);
wrapperRec.setAllowNull(false);
wrapperRec.setAllowUnspecifiedFields(false);
wrapperRec.setRequired(true);
if(columnNames != null)
{
for(int i = 0; i < columnNames.length; i++)
{
ColumnInfo cInfo = tInfo.getColumnInfo(columnNames[i]);
PipelineVariableProperties fieldProps =
wrapperRec.findByPath(columnNames[i]);
fieldProps.setAllowNull(false);
fieldProps.setRequired(cInfo.isRequired());
}
}
}