This documentation is for WSO2 Data Services Server 3.2.2. View documentation for the latest release.
Page Comparison - Defining Namespaces (v.4 vs v.5) - Data Services Server 3.2.2 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Data services are implemented using XML, which means that there can be conflicting element names. Therefore, we use namespaces to uniquely identify the elements defined within a specific web service. Using namespaces for a data service is optional. However, in certain data services, namespaces become necessary. For example, consider a data service with two separate queries using the same set of output mappings. In such situations, you need to use separate namespaces to identify the elements in each query.Namespaces can be used at different levels for  Read below for more information.

Info
title Namespace inheritance in a data service:

Namespaces can be defined at different levels of a data service, which means that you can have multiple namespaces applicable to your data service at the same time. In such a scenario, the top-level namespaces will be inherited by the lower level as explained below.

  1. The namespace at the data service level applies to all aspects of the data service, i.e., to all elements in the results of all the queries (output mapping).
  2. The namespace at the query result level (row namespace) overrides the service namespace and applies a given namespace to all the result elements (output mapping elements) of that query.
  3. The namespace specified for a result element (output mapping) overrides the query-level row namespace.
  4. If you have a complex element with child elements nested:
    1. The namespace for the complex element overrides the result row namespace and assigns the namespace to all its child elements.
    2. The namespace specifically assigned to a child element overrides the parent element's namespace.

See the following topics for instructions on setting namespaces at different levels of a data service:

Table of Contents
maxLevel3
minLevel3

Service namespace

Setting the namespace for a data service

The service namespace is used to uniquely identify a web service, which means that this namespace applies to all elements in the data service. In the WSDL that represents the service, the namespace is indicated by the "targetNamespace" attribute. The service namespace can be overridden at the query level and at output result row level as explained below. The service namespace can be set using the Create/Edit Data Service window of the set when you define a data service using the management console as shown below.

Data service result row namespace

Setting the namespace for a data service query

When you define a query for your data service, you can set a namespace for the elements in the query result (output mapping). That is, the Row Namespace applies to all the result rows that you define as output mappings for that queryThe example below shows how the row namespace is set for the query result element: Customers.

After setting the row namespace, the Customers element's data type of the Customers element falls under the given namespace The XML Schema fragment in data types section taken from the service's WSDL is as follows:as shown below.

Info

Note the following:

  • The row namespace will override the service-level namespace entries that are applicable to the elements in a query result.
  • If you have multiple queries

    for your data service using

    with the same

    result row

    element wrapper but different element rows, be sure to use separate namespaces for each query

    to avoid a conflict.
    Namespaces for specific elements in the

    . The example below illustrates two queries in a data service (.dbs file) with the following qualities:

    • The element wrapper is the same for both queries, which is <result element="employees" rowName="employee">.
    • The two queries contain two unique element rows: 'salary' and 'phone'.

    Therefore, since we are using the same element wrapper for both queries, we need to use two separate namespaces to identify the two conflicting elements ('salary' and 'phone') in the two queries as shown below.

    Code Block
    <query id="employeesByNumberSQL" useConfig="default">
          <sql>select * from Employees where employeeNumber = ?</sql>
          <result defaultNamespace="http://abc.com/empNamespace1" element="employees" rowName="employee">
             <element column="lastName" name="last-name" xsdType="string"/>
             <element column="firstName" name="first-name" xsdType="string"/>
             <element column="email" name="email" xsdType="string"/>
             <element column="salary" name="salary" xsdType="double"/>
          </result>
          <param name="employeeNumber" ordinal="1" sqlType="INTEGER"/>
    </query>
    <query id="employeesByIDSQL" useConfig="default">
          <sql>select * from Employees where employeesID = ?</sql>
          <result defaultNamespace="http://abc.com/empNamespace2" element="employees" rowName="employee">
             <element column="lastName" name="last-name" xsdType="string"/>
             <element column="firstName" name="first-name" xsdType="string"/>
             <element column="email" name="email" xsdType="string"/>
             <element column="phone" name="phone" xsdType="string"/>
          </result>
          <param name="employeeID" ordinal="1" sqlType="INTEGER"/>
    </query>

    Setting namespaces for specific elements in the query result

    The row namespace applies to all elements in the query result. Alternatively, you can specify namespaces for selected elements (output mappingsmapping elements) in the query result as shown below. This namespace will only apply to that element.

    This is how the setting is reflected in the WSDL.

    Info

    Note the following:

  • The namespace defined for a specific output element will override the service-level namespace entries as well as the row namespace entries that are applicable to the element.
  • If you have a data service query using the same result element multiple times, be sure to use separate namespaces for each element to avoid conflicts.

    Namespaces

    The example below illustrates a single query in a data service (.dbs file) that has the same element defined twice. In this situation, we have to use separate namespaces for the two elements in order to distinguish them separately.

    Code Block
    <query id="getProductByIDSQL" useConfig="default">
          <sql>select * from Products where productID = ?</sql>
          <result defaultNamespace="http://abc.com/productIDNamespace" element="products" rowName="product">
             <element column="productID" name="productID" xsdType="string"/>
             <element column="productID" name="productID" xsdType="INTEGER"/>
             <element column="productName" name="productName" xsdType="string"/>
          </result>
    </query>

    Setting namespaces for complex results

    In complex results in data services, the result elements can be arbitrarily nested. These nested elements can have their own namespaces. The example below shows how this is represented in a database file fragment, which has given below illustrates a query with a complex result (nested elements). As shown below, the namespace specified for the 'contact' element is inherited by the child elements that are nested within. However, if you assign specific namespaces to the child elements, the namespace inherited by the parent element will be overridden.

    Code Block
    <query id="customersInBostonSQL" useConfig="default">
          <sql>select  * from Customers where city = 'Boston' and country = 'USA'</sql>
          <result defaultNamespace="http://abc.com/nsb" element="customers" rowName="customer">
             <element column="customerName" name="customer-name" xsdType="string"/>
             <element namespace="http://abc.com/nsb" name="contact">
             	<element column="contactLastName" name="contact-last-name" xsdType="string"/>
             	<element column="contactFirstName" name="contact-first-name" xsdType="string"/>
             </element>
             <element column="phone" name="phone" xsdType="string"/>
             <element column="city" name="city" xsdType="string"/>
             <element column="country" name="country" xsdType="string"/>
          </result>
    </query>

    The WSDL created for the above service is as follows:

    The resulted XML of the executed service is as follows:

    Namespace inheritance in a data service

    There's an inheritance order where a top-level namespace is inherited by its children. In summary, the inheritance is as follows:

    • Service namespace is applied to all aspects of the data service, i.e. results.
    • Result row namespace overrides the service namespace and applies a given namespace for the whole result.
    • Complex result, nested elements override the result row namespace and assign the namespace to all its child elements.
    • A namespace specifically assigned to an element overrides the parent element's namespace and assigns the given namespace to itself.