Prepare any necessary context parameters. To call an OFBiz Service, you may need to pass one or more parameters (called "IN" or "INOUT" parameters) using a Java Map structure. Consult the WebTools Service List for more information on any particular Service’s required and optional input and/or output parameters.

The following code snippet highlights the necessary Java code to call Services synchronously, asynchronously, and as scheduled processes:

Note: Only enough code necessary to illustrate Service invocation is shown.

import org.ofbiz.service.DispatchContext;
import org.ofbiz.service.GenericServiceException;
import org.ofbiz.service.LocalDispatcher;
import org.ofbiz.service.ServiceUtil;
// For an OFBiz Service, get the service dispatcher as follows
LocalDispatcher dispatcher = dctx.getDispatcher();
// For an OFBiz Event, get the service dispatcher as follows
LocalDispatcher dispatcher = (LocalDispatcher) request.getAttribute("dispatcher");
int param1 = 0;
String param2 = "Param 2";
Map input = UtilMisc.toMap("param1", new Integer(param1),
"param2", param2);
try {
// Example of a synchronous Service call. Returns immediately,
// and the Service is invoked and runs in parallel
// with the calling program
Map syncResults = dispatcher.runSync("someService", input);
// Example of an asynchronous Service call. Returns immediately,
// but the Service may not be run until some time in the future
Map asyncResults = dispatcher.runAsync("someService", input);
// Example of calling a Service to run synchronously and ignore
// the result.
Map syncResultsIgnore = dispatcher.runSyncIgnore("someService",
input);
// You may use the dispatcher to schedule a Service
long startTime = (new Date()). getTime();
dispatcher.schedule("someService", input, startTime);
}
catch (GenericServiceException e) {
Debug.logError(e, module);
return ServiceUtil.returnError(e.getMessage());
}

To set your program up to call an OFBiz Service, you must first instantiate a LocalDispatcher object. This Java object will provide all the necessary environmental information required to invoke a Service.

When you invoke one of the LocalDispatcher object's Service invocation methods, you are telling the LocalDispatcher to pass program control to the OFBiz "Service dispatcher", which in turn passes control to the OFBiz "Service engine" configured in the Service definition for the target Service. The Service engine invokes the target Service and passes context information, including all configured IN parameters, to the Service. When the target Service finishes processing, or has been scheduled to run, in the case of scheduled and asynchronous requests, control is passed back to the calling program.

If an error occurs during the Service's processing or during the passing of context information (for example, on parameter validation), a GenericServiceException is thrown by the Service engine and control returns to the catch block of the calling program.

You can use the ModelService object to make your job easier when calling Services. For example, if you have many parameters to pass to a Service and they are already in a Java Map (perhaps they were passed in from another Service), instead of moving them one-by-one to the required Service input Map structure, you can use knowledge of the Service's model to do this all in one statement.

// You first need to get the Service's model
ModelService modelService = null;
try {
modelService =
dispatcher.getDispatchContext().getModelService("myService");
}
catch (GenericServiceException e) {
// Error process left out
}
Map persistMap = modelService.makeValid(paramMap,
ModelService.IN_PARAM);
persistMap.put("userLogin", userLogin);
// Add another parameter to the Map
try {
// Now call the new Service with the persistMap created above
Map persistResult = dispatcher.runSync("myService1", persistMap);

As OFBiz manages Service transaction needs, the calling program may pass transaction timeout indicators. Similarly, the calling program may instruct the Service engine to wrap the target Service in a separate transaction.

// Transaction timeout is in milliseconds
// true = wrap this Service invocation in a separate transaction
Map result = dispatcher.runSync("myService", contextMap, 1000, true);