Page History

...

• Service Engine Configuration Guide
• XML File Definitions

Introduction

Anchor
introduction introduction

The Services Framework is new to OFBiz in Version 2. Services are defined as independent pieces of logic which when placed together can be used to process many different types of business requirements. Services can be of many different types: Workflow, Rules, Java, SOAP, BeanShellGroovy, etc. A service with the type Java is much like an event where it is a static method, however with the Services Framework we do not limit to web based applications. Services require input parameters to be in a Map and the results are returned in a Map as well. This is nice since a Map can be serialized and stored or passed via HTTP (SOAP).

...

The Service Dispatcher handles dispatching services to the appropriate Service Engine where it is then invoked. There is exactly one ServiceDispatcher for each Entity Delegator. If there are multiple delegators in an application there will also be multiple dispatchers. The ServiceDispatcher is accessed via a LocalDispatcher. There can be many LocalDispatchers associated with a ServiceDispatcher. Each LocalDispatcher is uniquely named and contains its own list of service definitions. When creating an instance of a LocalDispatcher, a DispatchContextis DispatchContext is also created and passed to the ServiceEngine.

...

...

Above you can see the name of this service is userLogin and it uses the java engine. This service expects two required IN parameters: login.username and login.password. Required parameters are tested before the service is invoked. If the parameters does not match by name and object type the service is not invoked. Parameters which may or may not be sent to the service should be defined as optional. After the service is invoked, the OUT parameters are tested. Only required parameters are tested, however if a parameter is passed which is not defined as optional or required it will cause the service to fail. This service has not required OUT parameters, so the result is simply returned.optional or required it will cause the service to fail. This service has not required OUT parameters, so the result is simply returned.

...

Automatic Entity Maintenance Service Definition

OFBiz can automatically define services for simple Create, Update and Delete (CrUD) operations for many entities.

Set the engine attribute to "entity-auto" and the invoke attribute to "create", "update", or "delete". 

For example:

<service name="createInvoiceContactMech" engine="entity-auto" invoke="create" default-entity-name="InvoiceContactMech">
    <description>Create a ContactMech for an invoice</description>
    <permission-service service-name="acctgInvoicePermissionCheck" main-action="CREATE"/>
    <auto-attributes include="pk" mode="IN" optional="false"/>
</service>

The entity-auto engine can implement the following Create operations:

1. a single OUT primary key for primary auto-sequencing
2. a single INOUT primary key for primary auto-sequencing with optional override
3. a multi-part primary key with all parts part IN except the last which is OUT only (the missing primary key is a sub-sequence mainly for entity association
4. all primary key fields IN for a manually specified primary key

For any more complex situation, write code for your own service instead of relying on an automatically defined one.

Usage

...

Internal Usage of the Services Framework is quite simple. In a Web Application the LocalDispatcher is stored in the ServletContext which can be accessed via the Session object in an Event. For non-web based applications you simply create a GenericDispatcher: GenericDelegator delegator = GenericDelegator.getGenericDelegator("default");
LocalDispatcher dispatcher = new GenericDispatcher("UniqueName",delegator);
Now we have a dispatcher which we can use to invoke services. To invoke the test service create a Map for the context which contains the IN parameter message *then invoke the service:*

...

The testExample1 service will have the exact same required and optional attributes as thetestInterface the testInterface service. Any service which implements testInterfacewill testInterface will also inherit the parameters/attributes. If needed, additional attributes can be added to a specific service by including the attribute tag along with the implementstag. You may also override an attribute by re-defining it after the implements tag.

...

ECA (Event Condition Action) is much like a trigger. When a service is called, a lookup is performed to see if any ECAs are defined for this event. Events include before authentication, before IN parameter validation, before actual service invocation, before OUT parameter validation, before transaction commit, or before the service returns. Next each conditionin condition in the ECA definition is evaluated and if all come back as true, each actionis action is performed. An action is just a service which must be defined to work with the parameters already in the service's context. There are no limit to the number of conditions or actions each ECA may define.

<service-eca>
    <eca service="testScv" event="commit">
        <condition field-name="message" operator="equals" value="12345"/>
        <action service="testBsh" mode="sync"/>
    </eca>
</service-eca>

A tip from Parimal Gain Tip: Note that you may use the set operation to rename a parameter for the triggered service or insert values for instance...

...

The eca element should also have 0 or more condition or condition-fieldelements field elements and 1 or more action elements.

...

The group definition is very simple, it contains a group elements along with 1 or more service elements. The group element contains a name attribute and a modeattribute mode attribute used to define how the group will function. The service element is much like the actionelement action element in an ECA, the difference being the default value for result-to-context.

...

JMS services are much like HTTP services, except the service request is sent to a JMS topic/queue. The engineshould engine should be set to jms, the location should be the name of the jms-service defined in the serviceengine.xml file (see Service Config document), and the invoke should be the name of the service on the remote system you are requesting to run. JMS services by nature are asynchronous.

...