com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Step 1: Defining the Data Service

Owned by Former user (Deleted)
Last updated: Nov 04, 2016
7 min read

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 enable batch requests for operations that contain multiple parameters for a single request. When a data service is created with the batch request mode enabled, 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. 

    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.

    Enableboxcarring/request box

    From DSS 3.5.0 onwards we are going to deprecate the back end approach used for boxcarring. Instead we are introducing a new request type (request_box), where you can call multiple operations via a single service call. In WSO2 DSS 3.5.0, both boxcarring and request box is disabled in a data service by default. You can enable both these options by clicking the Enable Boxcarring check box. The same “enableBoxcarring="true" attribute in the .dbs file applies to both boxcarring and request box.

    Using request_box: When using the generated wsdl, it will contain all the service level details you need to know in order to invoke a “request_box” request. It’s simply a wrapper element (“request_box”), which wraps the operations you need to call. You can put any number of operations within that “request_box” element any number of times. The order of operations depend on the flow you need to follow. Furthermore, this will return the result of the last operation you have put in the “request_box” wrapper element. 

    The "request_box" operation will be automatically added to the data service. For a practical demonstration, see the Request Box Sample.


    Using 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.

    The following control operations get automatically added to the data service when boxcarring is used.
    • 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 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 session cookies sent by the server. Let's see how to enable session management in different service clients. Boxcarring uses the session information to keep track of operations belonging to one batch. This session information will be sent along the request from the beginning of the boxcarring session to its end. That is, the cookie from the begin_boxcar operation response will be appended to all consequent calls until the boxcarring session is aborted or ended.

    When you work with boxcarring in a clustered setup, you need to enable sticky sessions in your load balancer. Otherwise, each request will be treated as an individual request, and the transaction behavior will not work as expected for the whole boxcarring session. Note that you do not need sticky sessions when using request box, because request box is always a single request that is sent to a single node in the cluster. The sticky sessions feature is required only when we need to send multiple requests to a single node in the cluster, as in the case of boxcarring.

    See how the sticky sessions feature is enabled when you /wiki/spaces/CLUSTER44x/pages/9732195 as your load balancer.     


    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();

    For a practical demonstration of boxcarring, see the Boxcarring Sample. 
    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.

    Enable Transports

    The transport settings of a data service allows you to specify the transport protocols that should be applicable when receiving messages to the data service. However, this facility to select the transport types as and when you create the data service will directly add the transport settings to the .dbs file of the data service. See Working with Transports for information on transports used in DSS.

    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. 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 the 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.

    If a JTA transaction is already started, incoming messages will automatically bind with it. 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 Step 2: Adding Datasources.

  4. After adding a data source, click  Next to add a query. For instructions, see Step 3: Writing Data Service Queries.
  5. After adding a query, click Next to add operations. For instructions, see
  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.
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.