XPathFunction and XPathType annotations

IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Developing monitor models > Create monitor models > Authoring XPath functions
XPathFunction and XPathType annotations

The XPathFunction annotation contains the information necessary to mark a method as a user-defined XPath function. The XPathType annotation can be used on a method to clarify the return value of the method, or on the parameters of a method to clarify the type of the parameter.

XPathFunction annotation
The XPathFunction annotation has the following elements.

Name Required or optional Type Description
namespaceName Required String The namespace in which the function is found. It must be in the form of a valid uniform resource identifier (URI). This namespace will be assigned a prefix in the function prefix library area when the functions of this namespace are added to a monitor model.
localName Required String The XPath name of the function. It does not have to be the same or in any way related to the name of the Java method implementing this function. It should be a valid NCName. Although everything will work if you use an invalid NCName, it will not be possible to call the function from within an expression.
description Optional String The description of this method. This description might be displayed by content assist. The default is "".
descriptionKey Optional String Used to find a localized description of this method. The format of this String is bundle.name/key_name. The bundle is searched for with the standard Java bundle resolution mechanism in the JAR in which this method is found, given the current locale settings. If the bundle or key cannot be found, the description is used. The description might be displayed by content assist. The default is "".
callingConvention Optional XPathFunction.CallingConvention Only the built-in JAXB bindings are supported.
isDeterministic Required boolean True if the output of this function only depends on its parameters.
For example, add(1, 2) always returns 3 so isDeterministic is true. However, random() returns a different value for every call, so isDeterministic is false. Functions marked with isDeterministic as true can be used to produce constant expressions, allowing for additional validation.
isSelfContained Required boolean True if the function does not use any external resources that exist only in the target environment. Functions marked with isSelfContained as true are called during validation if the parameters can be determined, allowing for additional validation. If you have a function that makes external connections to a database or server, it should have isSelfContained set to false so that it is not called during monitor model development.

XPathType annotation
The XPathType annotation has the following elements.

Name Required or optional Type Description
name Optional String Can be used to give a name to a parameter as a form of documentation. If the XPathType annotation is used on a method, this element is ignored. The default is "".
itemType Optional XPathType.Type Clarifies the type of return value or parameter. When it is set to Infer, the default datatype applies. The XMLGregorianCalendar has no default type associated with it. The XPathType annotation must always be used with XMLGregorianCalendar, and it must specify the itemType. The default is Infer.
occurrenceIndicator Optional XPathType.Indicator Further clarifies the type of return value or parameter. For a full understanding of occurrence indicators, you need to understand the XPath type system. For this application, however, all you really need to know is that if this is set to One on a return value, it means that you are promising to never return null. If you set this to One on a parameter, you expect that the argument should never be null. A setting of ZeroOrOne allows nulls for these values at run time, and the type will be marked with a '?' in the user interface to indicate that the value might be null. If you want to be able to use a function to assign a value to a metric that has the A value is required for this metric check box selected, you must mark the return value of the method with the XPathType annotation element occurrenceIndicator set to One, because this metric should not be set to null. The default is ZeroOrOne.

Authoring XPath functions

Name	Required or optional	Type	Description
namespaceName	Required	String	The namespace in which the function is found. It must be in the form of a valid uniform resource identifier (URI). This namespace will be assigned a prefix in the function prefix library area when the functions of this namespace are added to a monitor model.
localName	Required	String	The XPath name of the function. It does not have to be the same or in any way related to the name of the Java method implementing this function. It should be a valid NCName. Although everything will work if you use an invalid NCName, it will not be possible to call the function from within an expression.
description	Optional	String	The description of this method. This description might be displayed by content assist. The default is "".
descriptionKey	Optional	String	Used to find a localized description of this method. The format of this String is bundle.name/key_name. The bundle is searched for with the standard Java bundle resolution mechanism in the JAR in which this method is found, given the current locale settings. If the bundle or key cannot be found, the description is used. The description might be displayed by content assist. The default is "".
callingConvention	Optional	XPathFunction.CallingConvention	Only the built-in JAXB bindings are supported.
isDeterministic	Required	boolean	True if the output of this function only depends on its parameters. For example, add(1, 2) always returns 3 so isDeterministic is true. However, random() returns a different value for every call, so isDeterministic is false. Functions marked with isDeterministic as true can be used to produce constant expressions, allowing for additional validation.
isSelfContained	Required	boolean	True if the function does not use any external resources that exist only in the target environment. Functions marked with isSelfContained as true are called during validation if the parameters can be determined, allowing for additional validation. If you have a function that makes external connections to a database or server, it should have isSelfContained set to false so that it is not called during monitor model development.

Name	Required or optional	Type	Description
name	Optional	String	Can be used to give a name to a parameter as a form of documentation. If the XPathType annotation is used on a method, this element is ignored. The default is "".
itemType	Optional	XPathType.Type	Clarifies the type of return value or parameter. When it is set to Infer, the default datatype applies. The XMLGregorianCalendar has no default type associated with it. The XPathType annotation must always be used with XMLGregorianCalendar, and it must specify the itemType. The default is Infer.
occurrenceIndicator	Optional	XPathType.Indicator	Further clarifies the type of return value or parameter. For a full understanding of occurrence indicators, you need to understand the XPath type system. For this application, however, all you really need to know is that if this is set to One on a return value, it means that you are promising to never return null. If you set this to One on a parameter, you expect that the argument should never be null. A setting of ZeroOrOne allows nulls for these values at run time, and the type will be marked with a '?' in the user interface to indicate that the value might be null. If you want to be able to use a function to assign a value to a metric that has the A value is required for this metric check box selected, you must mark the return value of the method with the XPathType annotation element occurrenceIndicator set to One, because this metric should not be set to null. The default is ZeroOrOne.