Read more about this book

(For more resources on Apache see here.)

Introduction

OFBiz has been characterized as having an “event-driven, service-oriented architecture”. Long before it was fashionable to build complex enterprise computer systems using service-oriented techniques, OFBiz implemented a number of architectural features enabling a service-oriented design. These features include:

• A context-aware Service Engine available for use across the entire framework or, if configured, externally through supported network interfaces. OFBiz Service consumers need not concern themselves with the location of the called Service nor with a Service’s implementation details. OFBiz handles all that transparently to both the service provider and consumer.
• Multiple invocation methods including: inline or synchronous with the calling program; out-of-band or asynchronous from the caller’s processing logic and/or as a scheduled job for recurring execution. OFBiz handles all input, output, and context parameter transfers seamlessly to both Service provider and Service caller.
• Chaining of Services for a true, event-driven Service platform and implementation of complex workflows. Services may be configured to be invoked based on external events or triggers. Once triggered, an OFBiz Service may call other Service(s) based on additional triggering Events and/or conditions. Any combination of Services may be chained together to form Service Event Condition Action(s) or SECAs.
• A fully integrated job scheduler for recurring and single use asynchronous job scheduling. The OFBiz job scheduler handles all the mundane coordination tasks associated with job scheduling, including calendar lookups, frequency, and interval timing.
• Service creation and implementation tools, including selectable input and output validations based on configured parameter types; authentication and authorization checks integrated with OFBiz user login processing, and even localization preservation across Service calls.

The heart of the OFBiz service-oriented implementation is the Service Engine factory. Using a factory pattern, OFBiz provides an easily extendable Service management and invocation tool supporting any number of concurrent Services and any number of third-party execution engines including, but not limited to: Java, Groovy, Javascript, JPython, and the OFBiz “simple” Service (based on the OFBiz Mini-Language.) By offloading Service implementation to programming language-specific engines, OFBiz Services may be written and implemented in any language that suits the developer’s fancy.

The Service Engine factory may be called from anywhere in the framework to handle the details of Service invocation, as shown in the following diagram:

Managing existing OFBiz Services

Out-of-the-box OFBiz comes with many hundreds of Services. To find and otherwise manage OFBiz Services, a fully featured Service management dashboard is provided. Privileged users may conveniently handle all Service related tasks using the OFBiz WebTools toolkit as described.

How to do it…

To access the OFBiz Service management main web page, navigate to the following WebTools URL:

https://localhost:8443/webtools/control/ServiceList

When prompted for a username and password, login as the administrative user (username “admin”, password “ofbiz”).

How it works…

WebTools provides a dashboard-like UI to view, manage, run, and support OFBiz Services. The main web page for OFBiz Service support is found at:

https://localhost:8443/webtools/ServiceList

(Note the use of case-sensitive addressing). This web page is shown in the following figure:

There’s more…

Asynchronous and scheduled Service requests are managed by the OFBiz job scheduler. The job scheduler consists of multiple execution threads as configured in the ~framework/ service/config/serviceengine.xml file. Threads run from one or more thread “pools”. From the OFBiz Thread List web page, you may see at a glance the configuration of the OFBiz job scheduler as well as thread and thread pool usage as shown here:

Calling a Service from an HTML form

Services may be called directly from HTML forms by setting the HTML form’s action element to point to the URL of a controller.xml request-map that resolves to either an OFBiz Event that calls a Service or directly to a Service. To demonstrate this, the following section uses the WebTool’s Run Service HTML form to invoke a Service.

Getting ready

For the purposes of this recipe, we shall use an existing Service called testScv and invoke it from the WebTools UI. In this example, we will not be creating an HTML form nor creating a Service, but rather using an existing form and Service:

• To view the results of the testScv Service’s execution, open an OFBiz console window from the command line
• Alternatively, to view the results of the execution, run the Unix tail command tail -f ofbiz.log on the ofbiz.log file ~runtime/ofbiz.log while performing this recipe

How to do it…

Services may be called directly from HTML forms by following these steps:

1. Navigate directly to the Run Service WebTools web page by selecting the Run Service URL: ~webtools/control/runService.
2. From the Run Service form, enter in testScv in the field labeled Service.
3. Leave the field labeled Pool as is.
4. Hit the Submit button to bring up the Schedule Job web page.
5. On the Schedule Job web page, enter in any values for the requested form fields. These fields correspond to any Service INPUT parameters as configured in the Service definition for testScv.

   

6. Hit the Submit button. The testScv has been called by using an HTML form.
7. To verify that the input parameters entered in step 6 earlier are processed by the testScv, inspect the ofbiz.log file as shown:

How it works…

Any OFBiz Service may be called from an OFBiz webapp HTML form simply by:

1. Creating an HTML form with an action attribute URL for the target Service.
2. Creating a controller.xml entry with a request-map for the target Service that matches the HTML form’s action URL. For example, the HTML form for the Run Service tool has an action value as shown in the following code snippet:

   <form name= "scheduleForm" method= "POST"
         action= "/webtools/control/scheduleService" />
     <input type="text" name="testScv" />
     <!-- Stuff Intentionally Removed >
   </form>

When the form is submitted, the URL set within the form’s action (webtools/control/scheduledService) is intercepted by the WebTools controller servlet, which consults its controller.xml file to determine how to handle this request. The controller.xml entry for this URL is shown here:

<request-map uri="scheduleService">
  <security https="true" auth="true"/>
  event type="java" path="org.ofbiz.webapp.event.CoreEvents"
        invoke="scheduleService"/>
  <response name="success" type="view" value="FindJob"/>
  <response name="sync_success" type="view" value="serviceResult"/>
  <response name="error" type="view" value="scheduleJob"/>
</request-map>

The URL request is mapped to an OFBiz Event called scheduleService. Inside the scheduleService Event, a call is made to the Service Engine to invoke testScv using the Java Service implementation engine as shown in the testScv Service definition file:

<service name="testScv" engine="java" export="true"
         validate="false" require-new-transaction="true"
         location="org.ofbiz.common.CommonServices" invoke="testScv">
  <description>Test service</description>
  <attribute name="defaultValue" type="Double"
             mode="IN" default-value="999.9999"/>
  <attribute name="message" type="String" mode="IN" optional="true"/>
  <attribute name="resp" type="String" mode="OUT"/>
</service>

After testScv has been executed, processing control returns to the OFBiz request handler (part of the controller servlet) and then back to the calling webapp as configured in the controller.xml file.

Calling asynchronous Services from HTML forms

You can use WebTools and HTML forms to run a Service asynchronously either one time or on a recurring basis. The following demonstrates the steps necessary to schedule testScv to be executed one time, asynchronously, as a scheduled job.

Getting ready

Navigate directly to the Schedule Job web page.

~https://localhost:8443/webtools/control/scheduleJob

How to do it…

To execute testScv asynchronously follow, these steps:

1. In the Service form field, enter in testScv as shown in the screenshot.
2. Leave the Job field empty. OFBiz will pick a unique name automatically.
3. Use the calendar pop-up icon directly next to the Start Date/Time field to select any date and time after the current wall clock time.

   



4. Submit this form by clicking the Submit button to bring up the Service Parameters form, which allows the caller to provide alternative input parameters to the Service.
5. Add INPUT parameters as shown:



6. Submit the Service Parameters form. testScv will be scheduled to run at the specified time.

How it works…

Scheduled Services are run asynchronously from the calling program. As such, requests for scheduling are handled by the OFBiz job scheduler. Each scheduled Service is assigned a unique job identifier (jobId) and execution pool by the job scheduler. After the Service is scheduled for execution, control returns to the calling program.

There’s more…

Using the OFBiz job scheduler Job List web page, you may find all scheduled jobs. In the following screenshot, testScv is shown as scheduled for execution on the Job List Search Results web page as specified in the recipe:

Because the testScv only writes output to the logfile, we may verify successful execution and scheduling by observing the ofbiz.log runtime logfile as shown:

Calling a Service many times from an HTML form

It is possible to call a Service multiple times from a single HTML form (for example, one time for each row in the form) by placing a line similar to the following with a service-multi event type defined for the controller.xml request-map entry of the target Service.

How to do it…

Follow these steps to call a Service multiple times:

1. Use the event type service-multi within the controller.xml request-map entry as shown here:

   <request-map uri="someService" />
     <event type="service-multi" invoke="someService"/>
     <!-- Other request-map statements intentionally left out -->
   </request-map>

2. If using an OFBiz Form Widget, add a line similar to the following to the Form Widget definition. Note, the list-name is the name of the list that is generating multiple rows for the HTML form:

   <form name="someFormName" type="multi" use-row-submit="true"
         list-name="someList" target="someServiceName" /
           <!-- Form fields removed for reading clarity -->
   </form>

3. If using a FreeMarker template, add lines similar to the following:

   <form name="mostrecent" mode="POST"
         action="<@ofbizUrl>someService</@ofbizUrl>"/>
     <#assign row=0/>
     <#list someList as listItem>
     <#-- HTML removed for reading clarity.
          Each row has a unique input name associated with it
          allowing this single Form to be submitted to the
          "someServiceName" Service from each row -->
     <input type="radio" name="someFormField_o_${row}"
            value="someValue" checked/>
     <input type="radio" name="someFormField_o_${row}"
            value="someValue"/>
     </#list>
   </form>

How it works…

The Event type service-multi provides a convenient shortcut for coding HTML forms that are embedded within lists. Each list item is automatically converted to a unique form field so that a single Service may be called from any row within the list.