Dashboard > WSO2 WSF- General > Home > Data Services and Resources
  WSO2 WSF- General Log in | Register   View a printable version of the current page.  
  Data Services and Resources
 Browse Space
Added by Chamil Thanthrimudalige , last edited by sumedha rubasinghe on Jan 24, 2008  (view change)
Labels: 
(None)

Introduction

Data Services & Resources are about providing a convenient mechanism to offering a service and resource interface to some data stored in a relational database.  When providing the service interface, the user must indicate how service requests map to queries against collections of tables in a relational database. Similarly, they must indicate how query results are mapped to service responses.

When providing a resource interface, the user must indicate how a set of resources map to queries and how query responses are returned as resource representations (or reports of resource creation or deletion, depending on the HTTP verb in use).

Configuration Language 

Data services and resources are defined using the Data Services and Resource Language (DSRL). What follows is yet incomplete and insufficiently documented. Need more time to finish writing this up (sanjiva). It also doesn't have the resource interface part yet .. that'll borrow heavily from WADL, which I like a lot in terms of how it approaches the problem esp. compared to WRDL.

Data services and resources are described using a <data> element:

<data baseURI="xs:anyURI" name="xs:NMTOKEN">
    config
    query+
    (operation | resource)+
</data>
  • data/@baseURI: a REQUIRED URI indicating the base URI for the operations and resources defined within the <data> element.
  • data/@name: a REQUIRED name of the data service.

Configuring the Database

config refers to configuration information about how to connect to the database:

<config id="xs:ID">
    <property name="xs:NMTOKEN">xs:urType</property>+
</config>
  • config/@id: a OPTIONAL XML ID identifying the config element. If configuration file has multiple <config> elements then this attribute is required.

The actual set of properties will be defined by each type of database connection (e.g., JDBC wil have its own standard set).

(Details TBD.) 

Defining Queries 

query describes a parameterized query and how to map the result to an XML element; thus its like a function that maps some parameters to an XML element. A query definition does not indicate how the parameters are acquired- it just lists the parameters that are needed and assumes that some outer environment will provide those parameters. If the query is at a top level (i.e., direct child of <data>) then either an operation definition or a resource definition provides the context for the parameters. If the query is nested within a <result> element, then the parameter names refer to column names of the result table that the <result> element is describing how to map into XML. The syntax of a <query> element is given below:

<query id="xs:ID"?>
    <param name="xs:NMTOKEN" sqlType="xs:string"? xsdType="xs:QName"?/>*
    <sql>xs:string</sql>
    <result mediaType="xs:string" element="xs:QName" rowName="xs:QName"? useNil="xs:boolean"? defaultNamespace="xs:anyURI"? columnDefault="element|attribute|link|omit"?>
        (element | attribute | link | call-query | text | header)*
    </result>
    <fault element="xs:QName"/>?
</query>

<element name="xs:QName" (column="xs:NMTOKEN" | param="xs:NMTOKEN") xsdType="xs:QName"?/>
<attribute name="xs:QName" (column="xs:NMTOKEN" | param="xs:NMTOKEN")  xsdType="xs:QName"?/>
<link (element="xs:QName" | attribute="xs:QName") uri="uri-template"/>
<text (column="xs:NMTOKEN" | param="xs:NMTOKEN" | value="xs:string")/>
<header name="xs:string" value="uri-template"/>
  • query/@ID: a OPTIONAL XML ID identifying the query. If <query> is a direct child of <data> then this attribute is required.
  • query/param: a declaration of a parameter of the query
    • param/@name: the REQUIRED name of the parameter
    • param/@sqlType: an OPTIONAL string containing a legal SQL type which defines the type of the parameter. If none is specified then defaults to string.
    • param/@xsdType: an OPTIONAL QName indicating the XML Schema type of the parameter as it appears on the wire. If none is given defaults to the mapping of param/@sqlType to an XML Schema type as per [SQL XML Mapping]
  • query/sql: a REQUIRED string containing the SQL query to execute
  • query/result: a REQUIRED element descriibing how the table resulting from executing the query will be converted to an XML element. If any <column> or <query> child elements are present, then ONLY those are transferred as child elements of the result element (or elements, depending on whether result/@rowName is given or not). The order of the nested <column> or <query> elements defines the order of elements in the result element.
    • result/@mediaType: an OPTIONAL string indicating the media type of the response information. Defaults to "application/xml" but it may be overridden by outer layers as needed (for example if the response is going via SOAP 1.2 it would become application/soap+xml).
    • result/@element: a REQUIRED QName which is the name of the element which will hold the results
    • result/@rowName: an OPTIONAL QName which is the name of the element wrapping each row of the result table if more than one element from the table is to be returned. If this attribute is not given, then only the first row is returned and hence no second level wrapper element is needed
    • result/@useNil: an OPTIONAL boolean which indicates whether to map null entries in the result table to elements with xsi:nil=true or whether to skip them. Defaults to false which means to skip them.
    • result/@defaultNamespace: an OPTIONAL URI being the default namespace to use for the namespace name of elements and attributes that result columns are mapped to. Defaults to "" (meaning no namespace).
    • result/@columnDefault: an OPTIONAL indication of what to do with result columns if columns are not explicitly mapped to the output using nested <column> or <query> elements. Defaults to "element" which means to make the column into an element.
    • result/call-query: an OPTIONAL element (which may occur any number of times) which is used to execute a further query and produce an element which will be present in the parent element as a child. This is used primarily to use a value of a column as key to select data from a new table.
    • result/element: an OPTIONAL element (which may occur any number of times) indicating how a specific column in the result table is to be mapped into an element
      • element/@name: a REQUIRED QName giving the name of the element to put the column data into,
      • element/@column: an OPTIONAL string giving the name of the column whose value is to be copied into the element. Either @column or @param is required.
      • element/@param: an OPTIONAL string giving the name of the param whose value is to be copied into the element. Either @column or @param is required.
      • element/@xsdType: an OPTIONAL indication of the XML Schema type of the element. If none is given defaults to the mapping of the SQL type of the result column named by @column to an XML Schema type as per [SQL XML Mapping]
    • result/attribute: an OPTIONAL element (which may occur any number of times) indicating how a specific column in the result table is to be mapped into an attribute of the element representing the current row
      • attribute/@name: a REQUIRED QName giving the name of the attribute to put the column data into,
      • attribute/@column: an OPTIONAL string giving the name of the column whose value is to be copied into the attribute. Either @column or @param is required.
      • attribute/@param: an OPTIONAL string giving the name of the param whose value is to be copied into the attribute. Either @column or @param is required.
      • attribute/@xsdType: an OPTIONAL indication of the XML Schema type of the attribute. If none is given defaults to the mapping of the SQL type of the result column named by @column to an XML Schema type as per [SQL XML Mapping]
    • result/text: an OPTIONAL element (which may occur any number of times) indicating a text node to be inserted into the result element at the current position. The value of the text node is computed from one of the given attributes:
      • text/@column: an OPTIONAL string giving the name of the column whose value is to be copied as the text node. Either @column or @param or @value is required.
      • text/@param: an OPTIONAL string giving the name of the param whose value is to be copied as the text node. Either @column or @param or @value is required.
      • text/@value: an OPTIONAL literal string giving the value is to be copied as the text node. Either @column or @param or @value is required.
    • result/link: : an OPTIONAL element (which may occur any number of times) indicating how a specific column in the result table is to be mapped into an element whose value is a link
      • link/@element: an OPTIONAL QName indicating the name of the element into which the link URL should be placed. Either @element or @link must be present.
      • link/@attribute: an OPTIONAL QName indicating the name of the attribute into which the link URL should be placed. Either @element or @link must be present.
      • link@uri: a REQUIRED URI template [URI Templates] describing how the link is to be created. Any embedded template variables of the URI template refer to column or parameter names.
    • result/header: an OPTIONAL element (which may occur any number of times) indicating how to create a header with a given name and value.
      • header/@name: a REQUIRED string giving the name of the header to generate.
      • header/@value: a REQUIRED URI template [URI Templates] describing how the value of the header is to be created. Any embedded template variables of the URI template refer to column or parameter names.
  • query/fault: an OPTIONAL element indicating what to element name to wrap the fault information with in case of an error while executing the query. This element will have automatically generated unqualified child elements named <code> and <detail> which contain the fault code and available fault details as available to the runtime.

Defining Service Operations 

operation refers to a Web service operation defined by a query. The operation is defined as an invocation of query indicating how the parameters of the query are computed or derived. The syntax is:

<operation name="xs:NCName" path="uri-template"?>
    <call-query href="xs:IDREF"           ?>
        <with-param name="xs:NMTOKEN" (query-param="xs:NMTOKEN" | path-element="xs:NMTOKEN" | part="xs:QName" | xpath="xs:string" | column="xs:NMTOKEN | param="xs:NMTOKEN")/>
        query?
    </call-query>
</operation>
  • operation/@name: is the REQUIRED name of the operation
  • operation/@path: is an OPTIONAL URI template [URI-Template] describing a template that the incoming URI will comply with. The named components of the URI template are later used as parameter values when the query is invoked. Note that unlike a path template in WSDL 2.0 HTTP binding and WADL, this template indicates how to break up the incoming URI based on the pattern in this template. Each embedded variable in the URI Template is then available for passing to the query as a parameter via <with-param>.
  • operation/call-query: describes how a query is to be invoked with the data received in the operation invocation.
    • call-query/@href: an OPTIONAL reference to the query that is to be invoked. If this is missing then a query must be nested within this element.
    • call-query/with-param: a description of a parameter binding for the query invocation: says how a named parameter's value is computed.
      • with-param/@name: a REQUIRED NMTOKEN identifying the parameter whose value is being specified
      • with-param/@query-param: an OPTIONAL attribute indicating the name of the URI query parameter (from operation/@path) whose value is the value of this parameter
      • with-param/@path-element: an OPTIONAL attribute indicating the named component of the URI template (from operation/@path) whose value is the value of this parameter
      • with-param/@part: an OPTIONAL attribute naming the direct child element of the incoming payload element whose value is the value of this parameter
      • with-param/@xpath: an OPTIONAL attribute indicating an XPath expression to be evaluated against the incoming payload element to compute the value of this parameter
      • with-param/@column: an OPTIONAL attribute naming a column of the immediate parent <result> element. That is, this applies only for nested queries and serves the purpose of being able to use a query result as input to a nested query.
      • with-param/@param: an OPTIONAL attribute naming a <param> of the parent <query>. That is, this applies only for nested queries and serves the purpose of being able to use a parameter of the parent query input to a nested query.
    • call-query/query: an OPTIONAL <query> being the anonymous query to be invoked as the implementation of this operation with the parameters identified above

For Any <header> elements executed within a query called as part of this operation definition will result in an SOAP Header block being created with the QName consisting of the baseURI of this data service as the namespace name and the header name as the local name. The value of the header block will be the value of the header.

Defining Resources  

(The section will be supported in a future WSAS release) 

<resource path="uri-template" method="GET|POST|PUT|DELETE">
    <call-query href="xs:IDREF"                                         ?>
        <with-param name="xs:NMTOKEN" (query-param="xs:NMTOKEN" | path-element="xs:NMTOKEN" | part="xs:QName" | xpath="xs:string")/>
        query?
    </call-query>
</resource>

This defines the resource identified by "new URI (/data/@baseURI, /data/resource/@path)" and indicates how the request is mapped to a query invocation.

If a fault occurs during the execution of the query, the HTTP fault code that is generated is determined via the following table. Note that this is done automatically by the runtime; the user does not have to specify which fault code etc. to return.

SQL Error HTTP Code
Explanation
(TBD)    
     
     
     

Any <header> elements executed within a query called as part of this resource definition will result in an HTTP header being created with the corresponding header name and value.

Authentication & Authorization

(This section needs to be edited yet.)

The design that we have come up so far is to give the database administrator two ways to authenticate and authorize the users of the service. The he can either enter the details for a user who has the necessary permissions for doing the operations defined in the service in which case WSO2 Application Server(WSAS) will take care of access control or else he can get the database to control access to the data. Please note that both methods can also be used in a mixed mode.

In the first method WSAS will authenticate the user and then use the authorization details in it's system to do the access control. In this all permissions will be controlled through the security module inside WSAS. WSAS will login and access as itself.

In the second method the user will send the authentication and authorization details and these details will be used when accessing the database. Please note the Security Token that will be used will not be some thing that is special to the Database service.

Examples

Handling References

INCOMPLETE YET.

Consider a database with the following structure.

  • "customers" table with the following columns:
    • id (primary-key, numeric, auto-generated)
    • name
    • date of birth
    • phone number
    • country
  • "products" table with the following columns:
    • code (primary-key, alphanumeric, human-specified)
    • description
  • "orders" table with the following columns:
    • id (primary-key, numeric, auto-generated)
    • customer_id (references customers.id)
    • status (enumeration)
  • "order_items" table with the following columns:
    • order_id (references orders.id)
    • product_code (references products.code)
    • quantity

Imagine I want an operation that gives me information about a particular order based on its id. I would like to get back XML something like this.

<order>
 <id>12345</id>
 <customerId>678</customerId>
 <items>
 <item>
 <productCode>AA-123</productCode>
 <quantity>1</quantity>
 </item>
 <item>
 <productCode>BB-456</productCode>
 <quantity>1000</quantity>
 </item>
 </items>
</order>

The following query appears to do that. Note that my sql knowledge sucks .. so the sql queries below (esp. the 2nd) is prolly busted.

<query>
    <param name="cust" sqlType="INTEGER"/>
    <param name="order" sqlType="INTEGER"/>
    <sql>select customer.id from customers customer where customer_id=?</sql>
    <result element="order">
        <element name="id" param="order"/>
        <element name="customerId" column="customer.id"/>
        <query>
           <param name="customer.id" sqlTyle="INTEGER"/>
           <param name="order" sqlType="INTEGER"/>
           <sql>select * from orders_items ordersItems where orders.customer_id=? and orders.id=? and orders.id=order_items.order_id </sql>
           <result element="items" rowName="item">
               <element name="productCode" column="ordersItems.product_code"/>
               <element name="quantity" column="ordersItems.quantity"/>
           </result>
        </query>
    </result>
</query>

The examples that were here before have been moved to separate child page. If you want to browse through them, it is available under child pages section @ the bottom of this page.

References

[WADL] https://wadl.dev.java.net/wadl20061109.pdf
[WRDL]  http://www.prescod.net/rest/wrdl/wrdl.html
[URI Templates] http://www.ietf.org/internet-drafts/draft-gregorio-uritemplate-00.txt
[SQL XML Mapping] <find reference to spec for how to map SQL types to XML Schema types>
Powered by a free Atlassian Confluence Open Source Project License granted to WSO2 Inc.. Evaluate Confluence today.
Powered by Atlassian Confluence 2.7.1, the Enterprise Wiki. Bug/feature request - Atlassian news - Contact administrators