TABLE OF CONTENTS

Introduction

RFarmer BPS configuration

Database Link

Application

Job

Shell process objects

View shell

Package shell

Run job

Jobs runs

Process implementation

Summary

Appendix A

Introduction

This guide offers the quickest way to start using Farmer Batch Process Server in Oracle. This guide assumes users have a basic knowledge of SQL and PL/SQL technologies as well as overview knowledge of Oracle RBDMS. 
Remote Farmer BPS instance provides possibility to use it mode for presentational, educational, prototyping etc purposes.

To use Farmer graphical user interface of Rich Internet Application class – Farmer Control Panel – web browser is needed.
This document is one another complementary Farmer BPS Documentation, where programming model is described in greater detail, and Farmer Control Panel User Documentation.

Public available Farmer BPS instance is under following description:

    HOST=farmer.tiger.com.pl
    ORACLE_SID=FARMER
    PORT=1521

User deginated for your purposes is:

    HOST=SYS_TEST
    PASSWORD=TESTFARMER

Farmer Control Panel (FCP) for this instance is public available under address:

    http://research.tiger.com.pl:8080/grf/farmer.html

Choose FARMERBPS connection and click Connect button.

Application
Now, create your own application entering following parameters:

  • Name – short application name – no more then 3 letters

  • Description – a few words of description about the application.

  • Code – application code

  • Default user – default application user – enter SYS_TEST for your purposes

The button opens a window New Application. In this window you can add a new application to the Farmer.



Illustration 2: The window New Application

Job
Now, you can create your test job in Jobs section under button. You can configure a new job in the window New job. The window opens when you click.



Illustration 3: New Job

Define the following attributes for quick start purpose:

  • Application – choose the test application from list.

  • Name – enter test process name.

  • Start date – execution date and time (hour and minutes) of the process (default null – system will not start automatically) – leave the default null.

  • Description – enter a few words about the process.

  • Repeat interval – the expression restricting start-up time of the process – parsed by Oracle (syntax and semantic according to Oracle dbms_scheduler), leave the default null value.

  • What – PL / SQL code performed by the process – for Farmer process filled up by default.

  • Implementing user – the name of the database schema, which has implemented a process – set on default application user by default.

  • Default mode – default mode of the process execution (list of value):

      > Batch – processing of data records in a batches about the size Window size et. commitment of database transactions every Window size records.
      > One By One – processing of the set record after record. Autonomous transactions in a database for each record.

Choose batch mode for quick start purposes.

  • Windows size – number of records processed in one batch (a subset) of data processed. The set of records is divided into batches with a given number of elements. Leave default value.

  • Instances interval – interval (in seconds) between startups of the successive threads of the process.

  • Type – process type:

      > View – it means, that the data source of the process is based on the perspective. 
      > Queue – it means, that the data source of the process is based on the queue (process implementation using AQ mechanism, the process goes to sleep in anticipation of the coming event).

For quick start purposes choose view based type.

  • Incrementality – Only for view type process applied. Flag, whether the data in view is processed in incremental mode i.e. after each execution maximal value of ID$ column is written, in next execution only records with higher value of ID$ column will be processed. Leave unchecked for quick start purposes.

  • Instances – a number of threads the process is run. Leave default 1 for quick start purposes.

  • Symmetric – Only for queue type process applied. Flag, if in multi-thead execution particular thread dequeues with any OBJECT_ID$ value or it is filtered by modulo of OBJECT_ID$ value. Not applied for quick start purposes.

  • Windows amount - maximum number of batches processed in a single execution. Not applied for quick start purposes – leave it null.

  • Permanent – value applies to the processes View and Queue; value determines whether, after processing the whole set, process is to be completed whether go to sleep (on time Sleeping interval)

      > Sleeping interval – value applies to the processes Permanent; value determines the sleeping time after treatment process all elements of the set

Leave it null for quick start purposes.

  • Use histogram – flag, whether the process will use the histogram.

      > Histogram – you can select the name of the histogram to use 
      > Dedicated – flag, whether selected histogram is dedicated to the process.

Leave unchecked for quick start purposes.

  • Create semaphore – flag, whether the configuration of the new process should include a creation of the semaphore to synchronize process execution.

Leave checked for quick start purposes.

  • Create skeleton – flag, whether the system should generate shells of the SQL view and PL / SQL package implementing the process.

Check flag for quick start purposes.
Commit configuration with the button . The process appears on the list.

Shell process objects


Login to SYS_TEST user on test instance with any PL/SQL IDE (e.g. Oracle SQL Developer) Among SYS_TEST user objects shell of process view and shell of process PL/SQL package specification and body has appeared. Synonyms for some objects in Farmer Server are also available.

View shell



Illustration 4: View shell

View shell is simply based on dual table and contains only driving columns. View is sorted according to Farmer specification.

Package shell
Package specification shell contains only obligatory interface:

  • sub-typed process view rowtype

  • procedure one



Package body shell contains only obligatory interface:

  • procedure one implementation taking no action

  • hidden run standard implementation which is standard “What” job attribute content



Such a shell objects set consist on shell process i.e. is “fully” functional and ready to run.

Run job
Button allows you to start the process chosen in the list.

Button opens the Run Job window. In this window the Farmer shows the state of the system ready for start the process. The process starts when an inspection of all control points is successful, so that everyone will have the value "OK" in the column value.



Illustration 6: Run job

Negative verified control point is marked by the ERR. Before starting the process you must fix the problem. For this end select the row with the value ERR and then click . In most cases in this way you can manage to fix the problem.

Jobs runs
After process execution completion an entry for the execution appear in Jobs runs section on jobs runs list. To localize particular execution use filter by name (any matching infix – no wild-cards) and run date.



Illustration 7: Jobs runs

After activating particular execution (and thread) you can also inspect logs of the execution, wait events and SQL trace statistic, if proper diagnostic flag was set.

Process implementation
Once you have executed shell process, you can implement your own process with specific business logic. Let's trace following example: our own process will mirror records from all_objects view to local table.

For begin, overwrite process view definition with view based on source all_objects view.

Take notice of object_id column from source view meets conditions to base for both ID$ and OBJECT_ID$ driving column. Data in process view are sorted in order requested by Farmer BPS specification.



Illustration 8: Process implementation 1

Once we have had process view create destination mirror table.



Illustration 9: Process implementation 2

Now, you are ready to implement one procedure in the process package.



Illustration 10: Process implementation 3

Above implementation includes commented out instructions for more sophisticated experiments.

Now process is ready to run, so run it via Farmer Control Panel in standard way. Process execution should be noticeable in Running Jobs section for few seconds depending on number of objects to process.



Illustration 11: Process implementation 4

You have created, implement and run your first Farmer BPS process based on view.

Feel free to experiment with implementation, configuration and monitoring of your first own Farmer BPS process. 

In configuration try to reconfigure following parameters: Default mode, Windows size, Instances interval, Incrementality, Instances, Windows amount, Permanent, Sleeping interval. In implementation try to use non-obligatory callbacks, raise exceptions, tracing multi-threading. In monitoring take notice of logs, wait event stats, stopping and resuming of execution mechanism.

With support of other Farmer papers create your Farmer BPS process based on AQ queue.

This guide is fully valid for local mode Farmer configuration except that in creating application db link name is left empty.


Scott Tiger S.A. © 2011