Creating Using Various Data Sources

Using this option, you can service enable a range of data sources such as RDBMS, Cassandra, Excel, CSV, JNDI, Google spreadsheet etc. or custom data sources.

1. Log in to the management console and select Create under Data Service menu.
2. The Create Data Service window opens as follow:
   

   The options in the above window are described below: 

   Data service namespace

   The service namespace uniquely identifies a Web service and is specified by the <targetNamespace> element in the WSDL that represents the service. A data service is simply a Web service with specialized functionality. As a data service implementation is based on XML, namespace handling is an important aspect to it. 

   When developing a data service, you get to specify namespaces in several places. One is as shown above. Others are result row namespace, namespaces for specific elements in a query result and for complex results. For more information, see Defining Namespaces.

   Enable batch request

   Use this option to provide capability to enable batch requests for operations that contain multiple parameter for a single request. When a data service is created with the batch request mode set, for all the in-only operations (i.e., operations that do not have any return value), the system creates a corresponding batch operation automatically. This batch operation takes in an array of parameters, compared to the single parameter list a non-batch operation takes.

   Note: Batch requests can only be used with in-only operations. That is, the query can not have a result element or out-type parameters. Batch requests are typically used with insert operations.

   Enable boxcarring

   Boxcarring is a method of grouping a set of service calls together and executing them at once. Where applicable, a boxcarring session works in a transactional manner such as when used with an RDBMS data source. WSO2 Data Services Server facilitates boxcarring by grouping service calls in the server side. As a result, special service clients are not required and as usual, successive service calls can be made to the server to participate in a boxcarring session.

   Boxcarring is disabled in a data service by default. Ticking the check box enables it. When boxcarring is enabled, the following control operations get automatically added to the data service.

   
   
   • begin_boxcar : A boxcarring session must be started by calling this operation. Once this is called, the server is notified that the subsequent operation calls must belong to this boxcarring session. The server stores these calls without executing them immediately.
   • end_boxcar : After begin_boxcar is called, the actual operations that belong to the boxcarring session follow. The last step is executing the grouped operations and ending the boxcarring session. This is done with the end_boxcar operation. Once this is called, all the grouped operations are executed at once and the boxcarring session ends. After calling end_boxcar, results are not returned to the client because there are multiple service calls executed at once. If there are any results in the operations of the boxcarring session, they are discarded.
     
   • abort_boxcar : If an error occurs in a boxcarring session, the user can choose to end the session by calling the abort_boxcar operation. This invalidates the boxcarring session and removes all pending operations in it.

   For a practical demonstration of boxcarring, see Boxcarring Sample in Samples.

   For boxcarring to function properly, you must use a transport that supports session management, such as HTTP. The service client must also support session management by returning back session cookies sent by the server. Let's see how to enable session management in different service clients.
   

   Session management in Axis2 clients

   Axis2 service clients have full support for session management. The following code snippet shows the process of enabling session in the client and invoking operations in a boxcarring session.

   RDBMSSampleStub stub = new RDBMSSampleStub(epr);
   stub._getServiceClient().getOptions().setManageSession(true);
   stub.begin_boxcar();
   stub.addEmployee(49001, "Smith", "John", "john@test.com", 10000.0);
   stub.incrementEmployeeSalary(5000.0, 1002);
   stub.incrementEmployeeSalary(4500.0, 1003);
   stub.end_boxcar();
   

   In line 2 of the code segment above, the client is requested to handle sessions. Without this command, the boxcarring sessions are not created in the server side. The three operation calls that follow the begin_boxcar operation belong to the newly-created boxcarring session. When end_boxcar is called, the earlier three operations are executed together as a group, in one transaction.

   Note: When using MySQL as the RDBMS, InnoDB Storage Engine must be used.

   Session management in CXF clients

   If the client is CXF, when executing a boxcarring session, you must enable robust in only option with the session management functionality. This is done by setting the endpoint property org.apache.cxf.oneway.robust to true to activate it at the endpoint. A sample CXF client code is shown below:

   private static final QName SERVICE_NAME = new QName("http://ws.wso2.org/dataservice/CXFClientService", "CXFClientDataService");
   CXFClientDataService ss = new CXFClientDataService(wsdlURL, SERVICE_NAME);
   CXFClientDataServicePortType port = ss.getSOAP11Endpoint();
   BindingProvider bp = (BindingProvider)port;
   bp.getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);
   bp.getRequestContext().put(Message.ROBUST_ONEWAY, Boolean.TRUE);
   port.beginBoxcar();

   Enable streaming

   Data service streaming helps manage large data chunks sent back to the client as the response of a data service query. When streaming is enabled, the data is sent to the client as it is generated, without memory building up in the server. By default, streaming is enabled in data services.
   
   Sometimes, you might notice that HTTP status code 200 OK is returned for data service requests that have a result. This happens due to streaming. To get a proper HTTP 500 code for SOAP faults, streaming must be disabled at service-level (as shown here) as well as operation-level.
   

   Enable distributed transactions

   Distributed transaction support helps you manage two or more transactions, often using multiple databases, in a coordinated way. A transaction manager is set up in the middle of these transactions for effective coordination and management.

   Distributed transaction feature is disabled in a data service by default. You can enable it by checking the relevant option. This feature uses Java Transaction API (JTA), which allows distributed transactions to be carried out across multiple XA resources in a Java environment. You can also override this transaction manager.

   For a practical demonstration of distributed transaction, see Distributed Transactions Sample in Samples.

   Distributed transactions with JMS

   JMS has ability to participate in distributed transactions. You can use JMS as the communication channel and run your database transactions in a distributed manner. It guarantees no message loss or failures and ensures single, successful message delivery.

   After distributed transaction support is enabled in a data service (by ticking the relevant check box), it automatically senses the status when an incoming message arrives, and if a JTA transaction is already started, it automatically binds to that. In this case, the transaction is started using the JMS transport receiver, if the receiver is enabled as follows:

   
   
   • Enable the JMS transport receiver in <PRODUCT_HOME>/repository/conf/axis2.xml file. The axis2.xml file contains properties related to Apache ActiveMQ JMS broker by default. Change the settings as suitable to the JMS broker you use. 
   • Add dependent libraries to <PRODUCT_HOME>/repository/components/lib.
     
   • Add the following two properties to configure the transport receiver to use JTA transactions:   
     
     • jta  
     • true
     After the JMS transport is configured, you can use any JMS client to send messages to the configured JMS broker. For example, you can use the Try-it tool in WSO2 Data Services Server. Be sure to enable the JMS transport sender by un-commenting the code block for JMSSender in  <PRODUCT_HOME>/repository/conf/axis2.xml file.        

   Overriding the default transaction manager

   The default transaction manager of a server can be overridden by providing the location to a JNDI name that the transaction manager is bound to. This is especially useful when the server is embedded in other application servers that do not use the standard JNDI name to bind to the transaction manager. In this case, you can provide a custom JNDI name to detect the transaction manager.

   Shown below is an example how WebLogic's JTA transaction manager overrides a data service's default transaction manager. 

   
    

3. Once you have provided a data service name and checked the relevant options in the Create Data Service window, click Next to add a data source. For instructions, see Creating Datasources.
   

4. After adding a data source, click  Next to add a query. For instructions, see Writing Data Service Queries.
5. After adding a query, click Next to add operations. For instructions, see Operation Management.
6. After adding an operation, click Next again to add resources. For instructions, see Exposing Data as REST Resources.
7. After adding a resource, click Finish to complete. You can skip any step from 4 by clicking Finish or Save as Draft at each stage. Saving as a draft creates a work-in-progress service. For more information, see Creating a WIP Data Service.
8. Once you complete data service creating, the Deployed Services window opens with the data service listed. From here, you can manage your service.