[Download] | [Documentation Home] | [Release Note]
Relational Databases are one of the mainly used data sources in data services. Here in this sample, we would be using an embedded H2 database in demonstrating the use of an RDBMS data source with WSO2 Data Services Server.
The sample data services should be deployed as per the instructions mentioned in Deploying Samples section.
The sample service "RDBMSSampleService", can be run using the "tryit" tool, which is bundled with WSO2 Data Services Server, or a code-generated java client sample using this service is demonstrated in the Data Services Clients Sample section.
The scenario is based on a possible database used in a small company to handle its internal affairs. Such as keeping employee and customer records, and information about the products that are produced in the company.
There are seperate queries/operations written for specific tasks of the company, the operations implemented in the service are listed as follows.
Boxcarring support is enabled in this service. By enabling the boxcarring option, the service will contain "begin_boxcar", "end_boxcar" and "abort_boxcar" control operations. Boxcarring is roughly analogous to transactions we see in database systems. The usage of boxcarring can be demonstrated by executing the following operations using the "tryit" tool. NOTE: An employee with employeeNumber=1002 is already in the system, we will be using that for the demonstration.
Figure 1: Normal service invocation, without boxcarring.
Figure 2: Service invocation after a boxcarring session.
As we can see, both "incrementEmployeeSalary" operations has been executed at once when the boxcarring session was ended with "end_boxcar", thus resulting in the salary value 3500. If there's any error in any of the operations inside a boxcarring session, non of the operations will be executed and the service calls will be rolled back. A boxcarring session can also be explicitely cancelled by calling the "abort_boxcar" operation.
This service use validators, in places where the validity of the input parameters have to be checked. This is shown in the "addEmployeeQuery" operation, by having a length validator for the "lastName" field, where the length of the value should be between 3 and 20, and also the "email" field is validated using a pattern validator which uses an regular expression to check if it's a real email address. Follow the below steps to demonstrate this functionality,
Figure 3: Successful service invocation with validators.
The operation "addEmployee" uses the facility to give default values to certain fields, if they were chosen not to be given an explicit value.
Here the parameter "salary" is given the default value 1500. This can be checked by calling the "addEmployee" operation by giving the parameter values leaving out the "salary" value. For example, if the parameter values are employeeNumber=6002; lastName=Smith; firstName=John; email=john@smith.com, a call to the operation "employeesByNumber" with employeeNumber=6002 will result in the following,
Figure 4: Service invocation with default values.
As you see, alongside the given parameters, the "salary" value also have been set to 1500, which is the default value for that field, when the parameter value is not given.
The operations "thousandFive" and "incrementEmployeeSalaryEx" are used in demonstrating the query result export functionality in a data service. The query used in "thousandFive" operation exports the a result value with the name "increment". This increment value is taken in as a parameter by the query in the "incrementEmployeeSalaryEx" operation. Figure 5 shows the dbs fragment that defines this behaviour.
Figure 5: Query result export sample dbs fragment.
This scenario can be tested using the try-it tool. Run the following operations sequentially.
You will notice that the return values from the first "employeeByNumber()" call and the second will have a difference of 1500, which is the amount that was incremented within the boxcarring session, where the 1500 value was passed into "incrementEmployeeSalaryEx" operation by the "thousandFive" operation.