Modeling a Custom Operation

Prerequisites

You have created client data objects that you can use in your custom operation.

More information: Creating the Data Model

You have created a service.

If your input or output parameters are not equivalent to a client data object node or Java base type, you need to create a data structure containing those fields that you require in the signature.

More information: Creating Data Structures .

If your custom operation throw an exception, you need to model the exception first.

More information: Handling Exceptions .

Context

A custom operation is a service operation, whose implementation you must code manually. You have full access to the complete mobile client runtime Application Programming Interface (API) as well as to all APIs exposed by the Java Runtime Environment on the Mobile Client for Handhelds.

More information: API Overview

Custom operations are typically used for validations, complex business logic, and the like. The signature of a custom operation is modeled using a dedicated modeling tool which then generates the implementation stub that the developer then fills with life in the Java Editor.

Procedure

In the Service editor, select the service you want to model.
Select tab page Operations and choose Add to add a new service operation.
In the dialog box, select Custom Operation , and enter a Name (mandatory) and a Description (recommended) for the custom operation.
In the Custom Operation Designer , select a data type for the Output Parameter and choose a cardinality.

Select data types for the Input Parameters and their cardinality.

Note

A node's cardinality defines the maximum and minimum number of elements its collection may contain at runtime. It is most important that you do not write coding that attempts to violate these constraints. If you do, a runtime exception will be raised. Your coding should anticipate and then avoid the following situations:

Attempts to delete the default element from a node whose minimum cardinality is 1

Attempts to add a second element to a node whose maximum cardinality is 1

These are the cardinality permutations and their meaning:

Cardinality Permutations	Required Cardinality of the Node Collection	Description
0..1	Any cardinality	Lead selection can be empty. Multiple selection is not possible.
1..1	Any cardinality	As the node selection has to contain exactly one element, the lead selection is always set (provided the node is not empty). Multiple selection is not possible.
0..n	0..n, 1..n only	Multiple selection of elements is possible. The lead selection can be empty.
1..n	1..n only	Multiple selection of elements is possible. The lead selection is set automatically (provided the node is not empty).

Add any exceptions you may want to process and choose Save .

More information: Handling Exceptions

You can drag the exceptions from the Data Type tree into the Exceptions field.
Select your service under the Services node containing your operation and in the context menu choose Open with Java Editor .

In the Java Editor, scroll to the public method of the same name as your custom operation. Its signature exactly reflects the signature you have just modeled in the query operations designer.

You can now implement the operation's implementations between the tags //@@begin implementation and //@@end . The generation ensures that any code between these tags will always be preserved, even if the operation's signature is changed.
Choose Save .