You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bu...@apache.org on 2015/01/16 10:59:06 UTC
svn commit: r936408 - in /websites/staging/sling/trunk/content: ./
documentation/bundles.html documentation/bundles/datasource-providers.html
Author: buildbot
Date: Fri Jan 16 09:59:06 2015
New Revision: 936408
Log:
Staging update by buildbot for sling
Added:
websites/staging/sling/trunk/content/documentation/bundles/datasource-providers.html
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Jan 16 09:59:06 2015
@@ -1 +1 @@
-1652372
+1652374
Modified: websites/staging/sling/trunk/content/documentation/bundles.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles.html Fri Jan 16 09:59:06 2015
@@ -147,9 +147,10 @@
<li><a href="/documentation/bundles/scheduler-service-commons-scheduler.html">Scheduler Service (commons scheduler)</a></li>
<li><a href="/documentation/bundles/web-console-extensions.html">Web Console Extensions (org.apache.sling.extensions.webconsolebranding, org.apache.sling.extensions.webconsolesecurityprovider)</a></li>
<li><a href="/documentation/bundles/discovery-api-and-impl.html">Discovery API and its Implementations (discovery.api, discovery.impl)</a></li>
+<li><a href="/documentation/bundles/datasource-providers.html">Datasource Provider</a></li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1648495 by cziegeler on Tue, 30 Dec 2014 09:53:47 +0000
+ Rev. 1652374 by chetanm on Fri, 16 Jan 2015 09:58:58 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
Added: websites/staging/sling/trunk/content/documentation/bundles/datasource-providers.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/datasource-providers.html (added)
+++ websites/staging/sling/trunk/content/documentation/bundles/datasource-providers.html Fri Jan 16 09:59:06 2015
@@ -0,0 +1,191 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - DataSource Provider</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/">
+ <img border="0" alt="Apache Sling" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/">
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong><a href="/documentation.html">Documentation</a></strong> <br />
+<a href="/documentation/getting-started.html">Getting Started</a> <br />
+<a href="/documentation/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/documentation/development.html">Development</a> <br />
+<a href="/documentation/bundles.html">Bundles</a> <br />
+<a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a> <br />
+<a href="/documentation/configuration.html">Configuration</a> </p>
+<p><a href="http://s.apache.org/sling.wiki">Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq">FAQ</a> </p>
+<p><strong>API Docs</strong> <br />
+<a href="/apidocs/sling7/index.html">Sling 7</a> <br />
+<a href="/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="/apidocs/sling5/index.html">Sling 5</a> </p>
+<p><strong>Project info</strong> <br />
+<a href="/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/">License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING">Issue Tracker</a> <br />
+<a href="http://ci.apache.org/builders/sling-trunk">Build Server</a> <br />
+<a href="/project-information/security.html">Security</a> </p>
+<p><strong>Source</strong> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk">Subversion</a> <br />
+<a href="git://git.apache.org/sling.git">Git</a> <br />
+<a href="https://github.com/apache/sling">Github Mirror</a> </p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html">Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html">Buy Stuff</a> </p>
+<p><strong><a href="/sitemap.html">Site Map</a></strong></p>
+<!-- no valid ads for now, we'll reactivate this when needed
+<iframe
+ src="http://www.apache.org/ads/button.html"
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+-->
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/bundles.html">Bundles</a>
+ </div>
+
+
+
+ <h1>DataSource Provider</h1>
+ <p>DataSource provider bundle supports two type of DataSource</p>
+<ol>
+<li>Pooled Connection DataSource</li>
+<li>JNDI DataSource</li>
+</ol>
+<h2 id="pooled-connection-datasource-provider">Pooled Connection DataSource Provider</h2>
+<p>This bundle enables creating and configuring JDBC DataSource in OSGi environment based on
+OSGi configuration. It uses <a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html">Tomcat JDBC Pool</a> as the JDBC Connection Pool provider.</p>
+<ol>
+<li>Supports configuring the DataSource based on OSGi config with rich metatype</li>
+<li>Supports deploying of JDBC Driver as independent bundles and not as fragment</li>
+<li>Exposes the DataSource stats as JMX MBean</li>
+<li>Supports updating of DataSource connection pool properties at runtime without restart</li>
+</ol>
+<h3 id="driver-loading">Driver Loading</h3>
+<p>Loading of JDBC driver is tricky on OSGi env. Mostly one has to attach the Driver bundle as a
+fragment bundle to the code which creates the JDBC Connection.</p>
+<p>With JDBC 4 onwards the Driver class can be loaded via Java SE Service Provider mechanism (SPM)
+JDBC 4.0 drivers must include the file META-INF/services/java.sql.Driver. This file contains
+the name of the JDBC driver's implementation of java.sql.Driver. For example, to load the JDBC
+driver to connect to a Apache Derby database, the META-INF/services/java.sql.Driver file would
+contain the following entry:</p>
+<div class="codehilite"><pre><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">derby</span><span class="p">.</span><span class="n">jdbc</span><span class="p">.</span><span class="n">EmbeddedDriver</span>
+</pre></div>
+
+
+<p>Sling DataSource Provider bundles maintains a <code>DriverRegistry</code> which contains mapping of Driver
+bundle to Driver class supported by it. With this feature there is no need to wrap the Driver
+bundle as fragment to DataSource provider bundle</p>
+<h3 id="configuration">Configuration</h3>
+<ol>
+<li>Install the current bundle</li>
+<li>Install the JDBC Driver bundle</li>
+<li>Configure the DataSource from OSGi config for PID <code>org.apache.sling.datasource.DataSourceFactory</code></li>
+</ol>
+<p>If Felix WebConsole is used then you can configure it via Configuration UI at
+http://localhost:8080/system/console/configMgr/org.apache.sling.datasource.DataSourceFactory</p>
+<p><img alt="Web Console Config" src="/documentation/development/sling-datasource-config.png" /></p>
+<p>Using the config ui above one can directly configure most of the properties as explained in <a href="http://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html">Tomcat Docs</a></p>
+<h3 id="convert-driver-jars-to-bundle">Convert Driver jars to Bundle</h3>
+<p>Most of the JDBC driver jars have the required OSGi headers and can be directly deployed to OSGi container
+as bundles. However some of the drivers e.g. Postgres are not having such headers and hence need to be
+converted to OSGi bundles. For them we can use the <a href="http://www.aqute.biz/Bnd/Wrapping">Bnd Wrap</a> command.</p>
+<p>For example to convert the Postgres driver jar follow the steps below</p>
+<div class="codehilite"><pre>$ <span class="n">wget</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="p">.</span><span class="n">com</span><span class="o">/</span><span class="n">bndtools</span><span class="o">/</span><span class="n">bnd</span><span class="o">/</span><span class="n">releases</span><span class="o">/</span><span class="n">download</span><span class="o">/</span>2<span class="p">.</span>3<span class="p">.</span>0<span class="p">.</span><span class="n">REL</span><span class="o">/</span><span class="n">biz</span><span class="p">.</span><span class="n">aQute</span><span class="p">.</span><span class="n">bnd</span><span class="o">-</span>2<span class="p">.</span>3<span class="p">.</span>0<span class="p">.</span><span class="n">jar</span> <span class="o">-</span><span class="n">O</span> <span class="n">bnd</span><span class="p">.</span><span class="n">jar</span>
+$ <span class="n">wget</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">jdbc</span><span class="p">.</span><span class="n">postgresql</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">download</span><span class="o">/</span><span class="n">postgresql</span><span class="o">-</span>9<span class="p">.</span>3<span class="o">-</span>1101<span class="p">.</span><span class="n">jdbc41</span><span class="p">.</span><span class="n">jar</span>
+$ <span class="nb">cat</span> <span class="o">></span> <span class="n">bnd</span><span class="p">.</span><span class="n">bnd</span> <span class="o"><<</span><span class="n">EOT</span>
+<span class="n">Bundle</span><span class="o">-</span><span class="n">Version</span><span class="p">:</span> 9<span class="p">.</span>3<span class="p">.</span>1101
+<span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">postgresql</span>
+<span class="n">Export</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">postgresql</span>
+<span class="n">Include</span><span class="o">-</span><span class="n">Resource</span><span class="p">:</span> <span class="p">@</span><span class="n">postgresql</span><span class="o">-</span>9<span class="p">.</span>3<span class="o">-</span>1101<span class="p">.</span><span class="n">jdbc41</span><span class="p">.</span><span class="n">jar</span>
+<span class="n">EOT</span>
+$ <span class="n">java</span> <span class="o">-</span><span class="n">jar</span> <span class="n">bnd</span><span class="p">.</span><span class="n">jar</span> <span class="n">bnd</span><span class="p">.</span><span class="n">bnd</span>
+</pre></div>
+
+
+<p>In the steps above we</p>
+<ol>
+<li>Download the bnd jar and postgres driver jar</li>
+<li>Create a bnd file with required instructions.</li>
+<li>Execute the bnd command</li>
+<li>Resulting bundle is present in <code>org.postgresql-9.3.1101.jar</code></li>
+</ol>
+<h2 id="jndi-datasource">JNDI DataSource</h2>
+<p>While running in Application Server the DataSource instance might be managed by app server and registered with
+JNDI. To enable lookup of DataSource instance from JNDI you can configure <code>JNDIDataSourceFactory</code></p>
+<ol>
+<li>Configure the DataSource from OSGi config for PID <code>org.apache.sling.datasource.JNDIDataSourceFactory</code></li>
+<li>Provide the JNDI name to lookup from and other details</li>
+</ol>
+<p>If Felix WebConsole is used then you can configure it via Configuration UI at
+http://localhost:8080/system/console/configMgr/org.apache.sling.datasource.JNDIDataSourceFactory</p>
+<p>Once configured <code>JNDIDataSourceFactory</code> would lookup the DataSource instance and register it with OSGi
+ServiceRegistry</p>
+<h2 id="usage">Usage</h2>
+<p>Once the required configuration is done the <code>DataSource</code> would be registered as part of the OSGi Service Registry
+The service is registered with service property <code>datasource.name</code> whose value is the name of datasource provided in
+OSGi config.</p>
+<p>Following snippet demonstrates accessing the DataSource named <code>foo</code> via DS annotation</p>
+<div class="codehilite"><pre><span class="n">import</span> <span class="n">javax</span><span class="p">.</span><span class="n">sql</span><span class="p">.</span><span class="n">DataSource</span><span class="p">;</span>
+<span class="n">import</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">scr</span><span class="p">.</span><span class="n">annotations</span><span class="p">.</span><span class="n">Reference</span><span class="p">;</span>
+
+<span class="n">public</span> <span class="n">class</span> <span class="n">DSExample</span> <span class="p">{</span>
+
+ <span class="p">@</span><span class="n">Reference</span><span class="p">(</span><span class="n">target</span> <span class="p">=</span> "<span class="p">(</span><span class="o">&</span><span class="p">(</span><span class="n">objectclass</span><span class="p">=</span><span class="n">javax</span><span class="p">.</span><span class="n">sql</span><span class="p">.</span><span class="n">DataSource</span><span class="p">)(</span><span class="n">datasource</span><span class="p">.</span><span class="n">name</span><span class="p">=</span><span class="n">foo</span><span class="p">))</span>"<span class="p">)</span>
+ <span class="n">private</span> <span class="n">DataSource</span> <span class="n">dataSource</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1652374 by chetanm on Fri, 16 Jan 2015 09:58:58 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>