<html>
<head>
<base href="https://docs.jboss.org/author">
<link rel="stylesheet" href="/author/s/en/2172/19/5/_/styles/combined.css?spaceKey=TEIID&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://docs.jboss.org/author/display/TEIID/OData+Support">OData Support</a></h2>
<h4>Page <b>edited</b> by <a href="https://docs.jboss.org/author/display/~rareddy">Ramesh Reddy</a>
</h4>
<br/>
<h4>Changes (5)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br>||Property Name||Description||Default Value|| <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">|max-allowed-cursors|Maximum cursors that are allowed at one time|100| <br></td></tr>
<tr><td class="diff-unchanged" >|batch-size|Number of rows to send back each time, -1 returns all rows|256| <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">|cursor-cleanup-every-millis|Time interval between clean-up process to runs in milli seconds|30000| <br>|cursor-ttl-millis|Idle time allowed for cursor to survive a cleanup process in milli seconds|300000| <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">|skiptoken-cache-time|Time interval between the results being recycled/expired between $skiptoken requests|300000| <br>|local-transport-name|Teiid Local transport name for connection|odata| <br></td></tr>
<tr><td class="diff-unchanged" > <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Teiid OData server, implements cursoring logic when the result rows exceed the configured batch size. On every request, only _batch-size_ number of rows are returned. Each such request is considered an active cursor, with a specified amount of idle time. Each time cursor is accessed the time limit is renewed. After the cursor is timed out, the cursor will be closed and remaining results will be cleaned up, and will no longer be available for further queries. Since there is no session based tracking of these cursors, they are limited by _max-allowed-cursors_ value. If Teiid server has been requested with more number of requests than _max-allowed-cursors_ concurrently, then the eldest cursor will be closed. The above configurations are per VDB. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Teiid OData server, implements cursoring logic when the result rows exceed the configured batch size. On every request, only _batch-size_ number of rows are returned. Each such request is considered an active cursor, with a specified amount of idle time specified by _skip-token-cache-time_. After the cursor is timed out, the cursor will be closed and remaining results will be cleaned up, and will no longer be available for further queries. Since there is no session based tracking of these cursors, if the request for skiptoken comes after the expired time, the original query will be executed again and tries to reposition the cursor to relative absolute potion, however the results are not guaranteed to be same as the underlying sources may have been updated with new information meanwhile. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h3. Access <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h2><a name="ODataSupport-WhatisOData"></a>What is OData</h2>
<p>The Open Data Protocol (OData) is a Web protocol for querying and updating data that provides a way to unlock your data and free it from silos that exist in applications today. OData does this by applying and building upon Web technologies such as HTTP, Atom Publishing Protocol (AtomPub) and JSON to provide access to information from a variety of applications, services, and stores. The protocol emerged from experiences implementing AtomPub clients and servers in a variety of products over the past several years. OData is being used to expose and access information from a variety of sources including, but not limited to, relational databases, file systems, content management systems and traditional Web sites.</p>
<p>OData is consistent with the way the Web works - it makes a deep commitment to URIs for resource identification and commits to an HTTP-based, uniform interface for interacting with those resources (just like the Web). This commitment to core Web principles allows OData to enable a new level of data integration and interoperability across a broad range of clients, servers, services, and tools.</p>
<p>copied from <a href="http://odata.org" class="external-link" rel="nofollow">http://odata.org</a></p>
<h2><a name="ODataSupport-TeiidSupportforOData"></a>Teiid Support for OData</h2>
<p>When a user successfully deploys a VDB into a Teiid Server, similar JDBC and ODBC protocol support, the OData protocol support is implicitly provided by the Teiid server without any further configuration. OData is support is currently not available in the Teiid Embedded profile. Teiid makes use of JBoss AS and its already configured <a href="http://www.jboss.org/resteasy" class="external-link" rel="nofollow">RestEasy</a> libraries, and <a href="http://code.google.com/p/odata4j" class="external-link" rel="nofollow">OData4J</a> libraries to provide a Rest based access to the VDB. The access would be similar to accessing to any web resources deployed on JBoss AS. OData support is implemented and deployed through WAR file. A user can access this WAR file in <jboss-as>/modules/org/jboss/teiid/deployments/odata-8.3.0.Final.war. This WAR can be configured with following properties in the web.xml file.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Property Name</th>
<th class='confluenceTh'>Description</th>
<th class='confluenceTh'>Default Value</th>
</tr>
<tr>
<td class='confluenceTd'>batch-size</td>
<td class='confluenceTd'>Number of rows to send back each time, -1 returns all rows</td>
<td class='confluenceTd'>256</td>
</tr>
<tr>
<td class='confluenceTd'>skiptoken-cache-time</td>
<td class='confluenceTd'>Time interval between the results being recycled/expired between $skiptoken requests</td>
<td class='confluenceTd'>300000</td>
</tr>
<tr>
<td class='confluenceTd'>local-transport-name</td>
<td class='confluenceTd'>Teiid Local transport name for connection</td>
<td class='confluenceTd'>odata</td>
</tr>
</tbody></table>
</div>
<p>Teiid OData server, implements cursoring logic when the result rows exceed the configured batch size. On every request, only <em>batch-size</em> number of rows are returned. Each such request is considered an active cursor, with a specified amount of idle time specified by <em>skip-token-cache-time</em>. After the cursor is timed out, the cursor will be closed and remaining results will be cleaned up, and will no longer be available for further queries. Since there is no session based tracking of these cursors, if the request for skiptoken comes after the expired time, the original query will be executed again and tries to reposition the cursor to relative absolute potion, however the results are not guaranteed to be same as the underlying sources may have been updated with new information meanwhile.</p>
<h3><a name="ODataSupport-Access"></a>Access</h3>
<p>For example, if you have a vdb by name <em>northwind</em> deployed and that vdb has a table <em>customers</em> then you can access that table as </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
http://localhost:8080/odata/northwind.1/customers
</pre>
</div></div>
<p>this would be akin to, making a JDBC/ODBC connection and issuing a SQL call as</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
SELECT * FROM customers
</pre>
</div></div>
<p>the returned results from OData query can be in Atom/AtomPub xml format or JSON format. By default AtomPub based XML result is returned.</p>
<p>User can also submit criteria with their query</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
http://localhost:8080/odata/northwind.1/customers?$filter=name eq 'bob'
</pre>
</div></div>
<p>this would be akin to, making a JDBC/ODBC connection and issuing a SQL call as</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
SELECT * FROM customers where name = 'bob'
</pre>
</div></div>
<p>The power of OData querying comes from navigations from one entity to another, similar the foreign key relationships in the relational world. For example, if <em>customers</em> table had a association with <em>orders</em> table, where say <em>customers</em> table had primary key of <em>id</em> then, user can issue a query like</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
http://localhost:8080/odata/northwind.1/customers(1234)/orders?$filter=orderdate > '12-31-2012'
</pre>
</div></div>
<p>this would be akin to, making a JDBC/ODBC connection and issuing a SQL call as</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
SELECT * FROM orders o join customers c join o.customer_id = c.id where c.id=1234 and o.orderdate > '12-31-2012'
</pre>
</div></div>
<p>For detail protocol access you can read the specification at <a href="http://odata.org" class="external-link" rel="nofollow">http://odata.org</a>. You can also read this very useful web resource <a href="http://msdn.microsoft.com/en-us/library/ff478141.aspx" class="external-link" rel="nofollow">for an example</a> access of a OData server.</p>
<h3><a name="ODataSupport-Security"></a>Security</h3>
<p>Currently by default the OData access is secured using the HTTPBasic, and user will be authenticated against the Teiid's default security domain "teiid-security" and makes use of the security role <b>odata</b>. However, if you wish to change the security domain, manually edit the <em>web.xml</em> file WAR file in <em><modules>/org/jboss/teiid/main/deployments</em> directory. In future versions more WS-Security based configurations will be provided.</p>
<h3><a name="ODataSupport-Limitations"></a>Limitations</h3>
<p>The following feature limitations currently apply.</p>
<ul>
<li>Currently the Teiid implements OData V2 specification along with many V3 features, however not completely OData V3 supported.</li>
<li>Blob support for media types are currently not supported.</li>
<li>"$value" construct to retrieve individual column value is not supported</li>
<li>create/update/delete $links is not supported</li>
<li>$expand is not supported</li>
</ul>
<h2><a name="ODataSupport-ClientToolsforAccess"></a>Client Tools for Access</h2>
<p>OData access is really where the user comes in, depending upon your programming model and needs there are various ways you write your access layer into OData. The following are some suggestions</p>
<ul>
<li>Your Browser: The OData Explorer is an online tool for browsing an OData data service.</li>
<li>Microsoft .NET Framework 3.51: the WCF Data Services framework is available as a separate download for .NET 3.x.</li>
<li>Microsoft .NET Framework 4.0: the WCF Data Services framework built into .NET 4.0 (in release candidate as of this writing).</li>
<li>Silverlight 3: the Data Services client library for Silverlight is available for download.</li>
<li>Java: the Restlet 2.0 library for Java (including Java on your Android phone) supports the OData protocol.</li>
<li>Java: Use a library like OData4J for Java based access, or any Rest based framework</li>
<li>JavaScript: the XMLHttpRequest object is standard in modern browsers or you can use jQuery, which comes out of the box with .NET 4.0 or is available for download.</li>
<li>PHP: the Toolkit for PHPprovides OData support for PHP clients.</li>
<li>AJAX: if you're using AJAX for ASP.NET, Microsoft provides the ASP.NET Ajax Library for getting to OData.</li>
<li>Excel 2010 PowerPivot: PowerPivot comes with OData support built right in.</li>
<li>Windows Desktop: LINQPad is a wonderful tool for building OData queries interactively.</li>
<li>Shell Scripts: use CURL tool</li>
</ul>
<h2><a name="ODataSupport-HowTeiidexposesschemaforOData"></a>How Teiid exposes schema for OData</h2>
<p>OData defines its schema using Conceptual Schema Definition Language (CSDL). Every VDB, that is deployed in an ACTIVE state in Teiid server exposes its metadata in CSDL format. For example if you want retrieve metadata for your vdb <em>northwind</em>, you need to issue a query like</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
http://localhost:8080/odata/northwind/$metadata
</pre>
</div></div>
<p>Since OData schema model is not a relational schema model, Teiid uses the following semantics to map its relational schema model to OData schema model.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'>Relational Entity</th>
<th class='confluenceTh'> Mapped OData Entity</th>
</tr>
<tr>
<td class='confluenceTd'>Model Name </td>
<td class='confluenceTd'>Schema Namespace, EntityContainer Name</td>
</tr>
<tr>
<td class='confluenceTd'>Table/View</td>
<td class='confluenceTd'>EntityType, EntitySet</td>
</tr>
<tr>
<td class='confluenceTd'>Table Columns</td>
<td class='confluenceTd'>EntityType's Properties</td>
</tr>
<tr>
<td class='confluenceTd'>Primary Key</td>
<td class='confluenceTd'>EntityType's Key Properties</td>
</tr>
<tr>
<td class='confluenceTd'>Foreign Key</td>
<td class='confluenceTd'>Navigation Property on EntityType, Association, AssosiationSet</td>
</tr>
<tr>
<td class='confluenceTd'>Procedure</td>
<td class='confluenceTd'>FunctionImport</td>
</tr>
<tr>
<td class='confluenceTd'>Procedure's Table Return</td>
<td class='confluenceTd'>ComplexType</td>
</tr>
</tbody></table>
</div>
<p>Teiid by design does not define any "embedeed" ComplexType in the EnitityType</p>
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/author/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Teiid does not define any one EntityContainer that resulted from different vdb models as a default container, so all entities must be accessed using full path to them.</td></tr></table></div>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://docs.jboss.org/author/users/removespacenotification.action?spaceKey=TEIID">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://docs.jboss.org/author/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://docs.jboss.org/author/display/TEIID/OData+Support">View Online</a>
|
<a href="https://docs.jboss.org/author/pages/diffpagesbyversion.action?pageId=59146740&revisedVersion=5&originalVersion=4">View Changes</a>
|
<a href="https://docs.jboss.org/author/display/TEIID/OData+Support?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>