Signature Field Properties
All 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 flow services and java services, signature fields and their properties can be modified by the user. For adapter services, the adapter defines resource domains that act as callbacks from the developer tool that allow 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:
Required - If true, the field must be present on the pipeline.
Allow null - If false, when the field is present, it 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 adapter service changes are still in progress, the call is made against a temporary object that has all metadata parameter settings as they currently exist in the adapter service editor. This is not the same object that is used for run-time service invocations.
The ADK includes three classes that are used to provide access to signature property information.
PipelineVariableProperties is an 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 is a concrete 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 is a concrete 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 should use the accessor/navigation methods available through that object to locate signature elements for which constraints need to be managed. Within the setSignatureProperties() implementation, it is frequently useful to use the WmAdapterService.inputRecordName() and outputRecordName() methods to get the names of the respective signature wrappers (if wrappers are enabled). If a connection is needed to get constraint information from a connection target, use the WmAdapterService.retrieveConnection() method.
Note:
This is the only place retrieveConnection should be used; using it from the service's execute method will cause errors.
The code listing below demonstrates a simple implementation of 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());
}
}
}