| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| |
| |
| <title>Apache Jena - Jena JDBC Drivers</title> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| <link href="/css/bootstrap.min.css" rel="stylesheet" media="screen"> |
| <link href="/css/bootstrap-icons.css" rel="stylesheet" media="screen"><link rel="stylesheet" type="text/css" href="https://jena.apache.org/sass/jena.1b17c39a117e22b46db4c66f6395dc27c134a60377d87d2d5745b8600eb69722.css" integrity="sha256-GxfDmhF+IrRttMZvY5XcJ8E0pgN32H0tV0W4YA62lyI="> |
| <link rel="shortcut icon" href="/images/favicon.ico" /> |
| |
| </head> |
| |
| <body> |
| |
| <nav class="navbar navbar-expand-lg bg-body-tertiary" role="navigation"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| <a class="navbar-brand" href="/index.html"> |
| <img class="logo-menu" src="/images/jena-logo/jena-logo-notext-small.png" alt="jena logo">Apache Jena</a> |
| </div> |
| |
| <div class="collapse navbar-collapse" id="navbarNav"> |
| <ul class="navbar-nav me-auto mb-2 mb-lg-0"> |
| <li id="homepage" class="nav-item"><a class="nav-link" href="/index.html"><span class="bi-house"></span> Home</a></li> |
| <li id="download" class="nav-item"><a class="nav-link" href="/download/index.cgi"><span class="bi-download"></span> Download</a></li> |
| <li class="nav-item dropdown"> |
| <a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false"><span class="bi-journal"></span> Learn <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li class="dropdown-header">Tutorials</li> |
| <li><a class="dropdown-item" href="/tutorials/index.html">Overview</a></li> |
| <li><a class="dropdown-item" href="/documentation/fuseki2/index.html">Fuseki Triplestore</a></li> |
| <li><a class="dropdown-item" href="/documentation/notes/index.html">How-To's</a></li> |
| <li><a class="dropdown-item" href="/documentation/query/manipulating_sparql_using_arq.html">Manipulating SPARQL using ARQ</a></li> |
| <li><a class="dropdown-item" href="/tutorials/rdf_api.html">RDF core API tutorial</a></li> |
| <li><a class="dropdown-item" href="/tutorials/sparql.html">SPARQL tutorial</a></li> |
| <li><a class="dropdown-item" href="/tutorials/using_jena_with_eclipse.html">Using Jena with Eclipse</a></li> |
| <li class="dropdown-divider"></li> |
| <li class="dropdown-header">References</li> |
| <li><a class="dropdown-item" href="/documentation/index.html">Overview</a></li> |
| <li><a class="dropdown-item" href="/documentation/query/index.html">ARQ (SPARQL)</a></li> |
| <li><a class="dropdown-item" href="/documentation/io/">RDF I/O</a></li> |
| <li><a class="dropdown-item" href="/documentation/assembler/index.html">Assembler</a></li> |
| <li><a class="dropdown-item" href="/documentation/tools/index.html">Command-line tools</a></li> |
| <li><a class="dropdown-item" href="/documentation/rdfs/">Data with RDFS Inferencing</a></li> |
| <li><a class="dropdown-item" href="/documentation/geosparql/index.html">GeoSPARQL</a></li> |
| <li><a class="dropdown-item" href="/documentation/inference/index.html">Inference API</a></li> |
| <li><a class="dropdown-item" href="/documentation/ontology/">Ontology API</a></li> |
| <li><a class="dropdown-item" href="/documentation/permissions/index.html">Permissions</a></li> |
| <li><a class="dropdown-item" href="/documentation/extras/querybuilder/index.html">Query Builder</a></li> |
| <li><a class="dropdown-item" href="/documentation/rdf/index.html">RDF API</a></li> |
| <li><a class="dropdown-item" href="/documentation/rdfconnection/">RDF Connection - SPARQL API</a></li> |
| <li><a class="dropdown-item" href="/documentation/rdfstar/index.html">RDF-star</a></li> |
| <li><a class="dropdown-item" href="/documentation/shacl/index.html">SHACL</a></li> |
| <li><a class="dropdown-item" href="/documentation/shex/index.html">ShEx</a></li> |
| <li><a class="dropdown-item" href="/documentation/tdb/index.html">TDB</a></li> |
| <li><a class="dropdown-item" href="/documentation/tdb2/index.html">TDB2</a></li> |
| <li><a class="dropdown-item" href="/documentation/query/text-query.html">Text Search</a></li> |
| </ul> |
| </li> |
| |
| <li class="nav-item dropdown"> |
| <a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false"><span class="bi-journal-code"></span> Javadoc <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/documentation/javadoc.html">All Javadoc</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/arq/">ARQ</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/fuseki2/">Fuseki</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/geosparql/">GeoSPARQL</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/jena/">Jena Core</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/permissions/">Permissions</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/extras/querybuilder/">Query Builder</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/shacl/">SHACL</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/tdb/">TDB</a></li> |
| <li><a class="dropdown-item" href="/documentation/javadoc/text/">Text Search</a></li> |
| </ul> |
| </li> |
| </ul> |
| <form class="d-flex" role="search" action="/search" method="GET"> |
| <div class="input-group"> |
| <input class="form-control border-end-0 border m-0" type="search" name="q" id="search-query" placeholder="Search...." aria-label="Search" style="width: 10rem;"> |
| <button class="btn btn-outline-secondary border-start-0 border" type="submit"> |
| <i class="bi-search"></i> |
| </button> |
| </div> |
| </form> |
| <ul class="navbar-nav"> |
| <li id="ask" class="nav-item"><a class="nav-link" href="/help_and_support/index.html" title="Ask"><span class="bi-patch-question"></span><span class="text-body d-none d-xxl-inline"> Ask</span></a></li> |
| |
| <li class="nav-item dropdown"> |
| <a href="#" title="Get involved" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false"><span class="bi-megaphone"></span><span class="text-body d-none d-xxl-inline"> Get involved </span><b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/getting_involved/index.html">Contribute</a></li> |
| <li><a class="dropdown-item" href="/help_and_support/bugs_and_suggestions.html">Report a bug</a></li> |
| <li class="dropdown-divider"></li> |
| <li class="dropdown-header">Project</li> |
| <li><a class="dropdown-item" href="/about_jena/about.html">About Jena</a></li> |
| <li><a class="dropdown-item" href="/about_jena/architecture.html">Architecture</a></li> |
| <li><a class="dropdown-item" href="/about_jena/citing.html">Citing</a></li> |
| <li><a class="dropdown-item" href="/about_jena/team.html">Project team</a></li> |
| <li><a class="dropdown-item" href="/about_jena/contributions.html">Related projects</a></li> |
| <li><a class="dropdown-item" href="/about_jena/roadmap.html">Roadmap</a></li> |
| <li><a class="dropdown-item" href="/about_jena/security-advisories.html">Security Advisories</a></li> |
| <li class="dropdown-divider"></li> |
| <li class="dropdown-header">ASF</li> |
| <li><a class="dropdown-item" href="https://www.apache.org/">Apache Software Foundation</a></li> |
| <li><a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li> |
| <li><a class="dropdown-item" href="https://www.apache.org/licenses/LICENSE-2.0">License</a></li> |
| <li><a class="dropdown-item" href="https://www.apache.org/security/">Security</a></li> |
| <li><a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| </ul> |
| </li> |
| |
| |
| |
| |
| <li class="nav-item" id="edit"><a class="nav-link" href="https://github.com/apache/jena-site/edit/main/source/documentation/jdbc/drivers.md" title="Edit this page on GitHub"><span class="bi-pencil-square"></span><span class="text-body d-none d-xxl-inline"> Edit this page</span></a></li> |
| </ul> |
| </div> |
| </div> |
| </nav> |
| |
| <div class="container"> |
| <div class="row"> |
| <div class="col-md-12"> |
| |
| <div id="breadcrumbs"> |
|
|
|
|
|
|
|
|
|
|
|
|
| <ol class="breadcrumb mt-4 p-2 bg-body-tertiary">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <li class="breadcrumb-item"><a href='/documentation'>DOCUMENTATION</a></li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <li class="breadcrumb-item"><a href='/documentation/jdbc'>JDBC</a></li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <li class="breadcrumb-item active">DRIVERS.HTML</li>
|
|
|
|
|
|
|
|
|
| </ol>
|
|
|
|
|
|
|
| |
| </div> |
| <h1 class="title">Jena JDBC Drivers</h1> |
| |
| |
| <main class="d-flex flex-xl-row flex-column"> |
| |
| <aside class="text-muted align-self-start mb-3 p-0 d-xl-none d-block"> |
| <h2 class="h6 sticky-top m-0 p-2 bg-body-tertiary">On this page</h2> |
| <nav id="TableOfContents"> |
| <ul> |
| <li><a href="#connection-url-basics">Connection URL Basics</a> |
| <ul> |
| <li><a href="#common-parameters">Common Parameters</a> |
| <ul> |
| <li><a href="#jdbc-compatibility-level">JDBC Compatibility Level</a></li> |
| <li><a href="#pre-processors">Pre-Processors</a></li> |
| <li><a href="#post-processors">Post-Processors</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#available-drivers">Available Drivers</a> |
| <ul> |
| <li><a href="#in-memory">In-Memory</a></li> |
| <li><a href="#tdb">TDB</a></li> |
| <li><a href="#remote-endpoint">Remote Endpoint</a> |
| <ul> |
| <li><a href="#authentication">Authentication</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </aside> |
| <article class="flex-column me-lg-4"> |
| <p>Jena JDBC comes with three built in drivers by default with the option of building |
| <a href="custom_driver.html">custom drivers</a> if desired. This page covers the differences |
| between the provided drivers and the connection URL options for each.</p> |
| <h2 id="connection-url-basics">Connection URL Basics</h2> |
| <p>Connection URLs for Jena JDBC drivers have a common format, they all start with the following:</p> |
| <pre><code>jdbc:jena:foo: |
| </code></pre> |
| <p>Where <code>foo</code> is a driver specific prefix that indicates which specific driver implementation |
| is being used.</p> |
| <p>After the prefix the connection URL consists of a sequence of key |
| value pairs, the characters ampersand (<code>&</code>), semicolon (<code>;</code>) and |
| pipe (<code>|</code>) are considered to be separators between pairs, the |
| separators are reserved characters and may not be used in values. The key is |
| separated from the value by a equals sign (<code>=</code>) though unlike the |
| separators this is not a reserved character in values.</p> |
| <p>There is no notion of character escaping in connection parameters so if you |
| need to use any of the reserved characters in your values then you should |
| pass these to the <code>connect(String, Properties)</code> method directly in the |
| <code>Properties</code> object.</p> |
| <h3 id="common-parameters">Common Parameters</h3> |
| <p>There are some common parameter understood by all Jena JDBC drivers and which |
| apply regardless of driver implementation.</p> |
| <h4 id="jdbc-compatibility-level">JDBC Compatibility Level</h4> |
| <p>As discussed in the <a href="index.html#treatment-of-results">overview</a> the drivers have a notion |
| of JDBC compatibility which is configurable. The <code>jdbc-compatibility</code> parameter is used |
| in connection URLs. To avoid typos when creating URLs programmatically a constant |
| (<code>JenaDriver.PARAM_JDBC_COMPATIBILITY</code>) is provided which contains the parameter |
| name exactly as the code expects it. This parameter provides an integer value |
| in the range 1-9 which denotes how compatible the driver should attempt to |
| be. See the aforementioned overview documentation for more information on the interpretation |
| of this parameter.</p> |
| <p>When not set the default compatibility level is |
| used, note that <code>JenaConnection</code> objects support changing this after |
| the connection has been established.</p> |
| <h4 id="pre-processors">Pre-Processors</h4> |
| <p>The second of the common parameters is the <code>pre-processor</code> parameter which is used to |
| specify one/more <code>CommandPreProcessor</code> implementations to use. The |
| parameter should be specified once for each pre-processor you wish to you and |
| you should supply a fully qualified class name to ensure the pre-processor |
| can be loaded and registered on your connections. The driver will report an |
| error if you specify a class that cannot be appropriately loaded and |
| registered.</p> |
| <p>Pre-processors are registered in the order that they are specified so if you |
| use multiple pre-processors and they have ordering dependencies please ensure |
| that you specify them in the desired order. Note that <code>JenaConnection</code> |
| objects support changing registered pre-processors after the connection has |
| been established.</p> |
| <h4 id="post-processors">Post-Processors</h4> |
| <p>There is also a <code>post-processor</code> parameter which is used to specify |
| one/more <code>ResultsPostProcessor</code> implementations to use. The parameter |
| should be specified once for each post-processor you wish to use and you |
| should supply a fully qualified class name to ensure the post-processor can |
| be loaded and registered on your connections. The driver will report an error |
| is you specify a class that cannot be appropriately loaded and registered.</p> |
| <p>Post-processors are registered in the order that they are specified so if you |
| use multiple post-processors and they have ordering dependencies please |
| ensure that you specify them in the desired order. Note that |
| <code>JenaConnection</code> objects support changing registered post-processors |
| after the connection has been established.</p> |
| <h2 id="available-drivers">Available Drivers</h2> |
| <ul> |
| <li><a href="#in-memory">In-Memory</a></li> |
| <li><a href="#tdb">TDB</a></li> |
| <li><a href="#remote-endpoint">Remote Endpoint</a></li> |
| </ul> |
| <p>Each driver is available as a separate maven artifact, see the <a href="artifacts.html">artifacts</a> page |
| for more information.</p> |
| <h3 id="in-memory">In-Memory</h3> |
| <p>The in-memory driver provides access to a non-persistent non-transactional in-memory dataset. This dataset |
| may either be initially empty or may be initialized from an input file. Remember that |
| this is non-persistent so even if the latter option is chosen changes are not persisted |
| to the input file. This driver is primarily intended for testing and demonstration |
| purposes.</p> |
| <p>Beyond the common parameters it has two possible connection parameters. The first of these |
| is the <code>dataset</code> parameter and is used to indicate an input file that the driver will |
| initialize the in-memory dataset with e.g.</p> |
| <pre><code>jdbc:jena:mem:dataset=file.nq |
| </code></pre> |
| <p>If you prefer to start with an empty dataset you should use the <code>empty</code> parameter instead e.g.</p> |
| <pre><code>jdbc:jena:mem:empty=true |
| </code></pre> |
| <p>If both are specified then the <code>dataset</code> parameter has precedence.</p> |
| <h3 id="tdb">TDB</h3> |
| <p>The TDB driver provides access to a persistent <a href="/documentation/tdb/">Jena TDB</a> dataset. This |
| means that the dataset is both persistent and can be used transactionally. For correct |
| transactional behavior it is typically necessary to set the holdability for connections and |
| statements to <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> as otherwise closing a result set or making |
| an update will cause all other results to be closed.</p> |
| <p>Beyond the common parameters the driver requires a single <code>location</code> parameter that provides |
| the path to a location for a TDB dataset e.g.</p> |
| <pre><code>jdbc:jena:tdb:location=/path/to/data |
| </code></pre> |
| <p>By default a TDB dataset will be created in that location if one does not exist, if you would |
| prefer not to do this i.e. ensure you only access existing TDB datasets then you can add the |
| <code>must-exist</code> parameter e.g.</p> |
| <pre><code>jdbc:jena:tdb:location=/path/to/data&must-exist=true |
| </code></pre> |
| <p>With this parameter set the connection will fail if the location does not exist as a directory, |
| note that this does not validate that the location is a TDB dataset so it is still possible |
| to pass in invalid paths even with this set.</p> |
| <h3 id="remote-endpoint">Remote Endpoint</h3> |
| <p>The Remote Endpoint driver provides access to any SPARQL Protocol compliant store that exposes |
| SPARQL query and/or SPARQL update endpoints. This driver can be explicitly configured to be |
| in read-only or write-only mode by providing only one of the required endpoints.</p> |
| <p>The <code>query</code> parameter sets the query endpoint whilst the <code>update</code> parameter sets the update endpoint e.g.</p> |
| <pre><code>jdbc:jena:remote:query=http://localhost:3030/ds/query&update=http://localhost:3030/ds/update |
| </code></pre> |
| <p>At least one of these parameters is required, if only one is provided you will get a read-only or |
| write-only connection as appropriate.</p> |
| <p>This driver also provides a whole variety of parameters that may be used to customize its behavior |
| further. Firstly there are a set of parameters which control the dataset description provided |
| via the SPARQL protocol:</p> |
| <ul> |
| <li><code>default-graph-uri</code> - Sets a default graph for queries</li> |
| <li><code>named-graph-uri</code> - Sets a named graph for queries</li> |
| <li><code>using-graph-uri</code> - Sets a default graph for updates</li> |
| <li><code>using-named-graph-uri</code> - Sets a named graph for updates</li> |
| </ul> |
| <p>All of these may be specified multiple times to specify multiple graph URIs for each.</p> |
| <p>Then you have the <code>select-results-type</code> and <code>model-results-type</code> which are used to set the MIME |
| type you’d prefer to have the driver retrieve SPARQL results from the remote endpoints in. If used |
| you must set them to formats that ARQ supports, the ARQ <a href="/documentation/javadoc/arq/org.apache.jena.arq/org/apache/jena/riot/WebContent.html">WebContent</a> |
| class has constants for the various supported formats.</p> |
| <h4 id="authentication">Authentication</h4> |
| <p>There is also comprehensive support for authentication using this driver, the standard JDBC <code>user</code> |
| and <code>password</code> parameters are used for credentials and then a selection of driver specific |
| parameters are used to configure how you wish the driver to authenticate.</p> |
| <p>Under the hood authentication uses the new <code>HttpAuthenticator</code> framework introduced in the same |
| release as Jena JDBC, see <a href="/documentation/query/http-auth.html">HTTP Authentication in ARQ</a>. This means |
| that it can support standard HTTP auth methods (Basic, Digest etc) or can use more complex schemes |
| such as forms based auth with session cookies.</p> |
| <p>To set up standard HTTP authentication it is sufficient to specify the <code>user</code> and <code>password</code> fields. As |
| with any JDBC application we <strong>strongly</strong> recommend that you do not place these in the connection URL |
| directly but rather use the <code>Properties</code> object to pass these in. One option you may wish to include |
| if your endpoints use HTTP Basic authentication is the <code>preemptive-auth</code> parameter which when set to |
| true will enable preemptive authentication. While this is less secure it can be more performant if |
| you are making lots of queries.</p> |
| <p>Setting up form based authentication is somewhat more complex, at a minimum you need to provide the |
| <code>form-url</code> parameter with a value for the URL that user credentials should be POSTed to in order to |
| login. You may need to specify the <code>form-user-field</code> and <code>form-password-field</code> parameters to provide |
| the name of the fields for the login request, by default these assume you are using an Apache <code>mod_auth_form</code> |
| protected server and use the appropriate default values.</p> |
| <p>The final option for authenticator is to use the <code>authenticator</code> parameter via the <code>Properties</code> object |
| to pass in an actual instance of a <code>HttpAuthenticator</code> that you wish to use. This method is the most |
| powerful in that it allows you to use any authentication method that you need.</p> |
| |
| </article> |
| |
| <aside class="text-muted align-self-start mb-3 mb-xl-5 p-0 d-none d-xl-flex flex-column sticky-top"> |
| <h2 class="h6 sticky-top m-0 p-2 bg-body-tertiary">On this page</h2> |
| <nav id="TableOfContents"> |
| <ul> |
| <li><a href="#connection-url-basics">Connection URL Basics</a> |
| <ul> |
| <li><a href="#common-parameters">Common Parameters</a> |
| <ul> |
| <li><a href="#jdbc-compatibility-level">JDBC Compatibility Level</a></li> |
| <li><a href="#pre-processors">Pre-Processors</a></li> |
| <li><a href="#post-processors">Post-Processors</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li><a href="#available-drivers">Available Drivers</a> |
| <ul> |
| <li><a href="#in-memory">In-Memory</a></li> |
| <li><a href="#tdb">TDB</a></li> |
| <li><a href="#remote-endpoint">Remote Endpoint</a> |
| <ul> |
| <li><a href="#authentication">Authentication</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </aside> |
| </main> |
| |
| </div> |
| </div> |
| </div> |
| |
| <footer class="bd-footer py-4 py-md-5 mt-4 mt-lg-5 bg-body-tertiary"> |
| <div class="container" style="font-size:80%" > |
| <p> |
| Copyright © 2011–2024 The Apache Software Foundation, Licensed under the |
| <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. |
| </p> |
| <p> |
| Apache Jena, Jena, the Apache Jena project logo, Apache and the Apache feather logos are trademarks of |
| The Apache Software Foundation. |
| <br/> |
| <a href="https://privacy.apache.org/policies/privacy-policy-public.html" |
| >Apache Software Foundation Privacy Policy</a>. |
| </p> |
| </div> |
| </footer> |
| |
| <script src="/js/popper.min.js.js" type="text/javascript"></script> |
| <script src="/js/bootstrap.min.js" type="text/javascript"></script> |
| <script src="/js/improve.js" type="text/javascript"></script> |
| |
| <script type="text/javascript"> |
| (function() { |
| 'use strict' |
| |
| |
| |
| const links = document.querySelectorAll(`a[href="${window.location.pathname}"]`) |
| if (links !== undefined && links !== null) { |
| for (const link of links) { |
| |
| link.classList.add('active') |
| let parentElement = link.parentElement |
| let count = 0 |
| const levelsLimit = 4 |
| |
| |
| |
| |
| |
| while (['UL', 'LI'].includes(parentElement.tagName) && count <= levelsLimit) { |
| if (parentElement.tagName === 'LI') { |
| |
| |
| |
| parentElement.querySelector('a:first-child').classList.add('active') |
| } |
| parentElement = parentElement.parentElement |
| count++ |
| } |
| } |
| } |
| })() |
| </script> |
| |
| </body> |
| </html> |
