Author: claude
Date: Fri Dec 20 12:56:52 2019
New Revision: 1871856
URL: http://svn.apache.org/viewvc?rev=1871856&view=rev
Log:
Updated documentation as part of JENA-1755
Modified:
jena/site/trunk/content/documentation/extras/querybuilder/index.mdtext
Modified: jena/site/trunk/content/documentation/extras/querybuilder/index.mdtext
URL:
http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/extras/querybuilder/index.mdtext?rev=1871856&r1=1871855&r2=1871856&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/extras/querybuilder/index.mdtext
(original)
+++ jena/site/trunk/content/documentation/extras/querybuilder/index.mdtext Fri
Dec 20 12:56:52 2019
@@ -1,30 +1,119 @@
Title: Jena Query Builder - A query builder for Jena.
-Query Builder for Jena. Implementations of Ask, Construct and Select builders
that allow
-developers to create queries without resorting to StringBuilders or similar
solutions.
+Query Builder for Jena. Implementations of Ask, Construct, Select and Update
builders that allow developers to create queries without resorting to
StringBuilders or similar solutions.
-Each of the builders has a series of methods to define the query. Each method
returns the
-builder for easy chaining. The example:
+Each of the builders has a series of methods to define the query. Each method
returns the builder for easy chaining. The example:
SelectBuilder sb = new SelectBuilder()
.addVar( "*" )
.addWhere( "?s", "?p", "?o" );
-
+
Query q = sb.build() ;
produces
- SELECT *
- WHERE
+ SELECT *
+ WHERE
{ ?s ?p ?o }
+Constructing Expressions
+========================
+
+Expressions are primarily used in `filter` and `bind` statements as well as in
select clauses. All the standard expressions are implemented in the
`ExprFactory` class. An `ExprFactory` can be retrieved from any Builder by
calling the `getExprFactory()` method. This will create a Factory that has the
same prefix mappings and the query. An alternative is to construct the
`ExprFactory` directly, this factory will not have the prefixes defined in
`PrefixMapping.Extended`.
+
+ SelectBuilder builder = new SelectBuilder();
+ ExprFactory exprF = builder.getExprFactory()
+ .addPrefix( "cf",
+ "http://vocab.nerc.ac.uk/collection/P07/current/CFSN0023/";)
+ builder.addVar( exprF.floor( ?v ), ?floor )
+
+ .addWhere( ?s, "cf:air_temperature", ?v )
+
+
+Update Builder
+==============
+
+The `UpdateBuilder` is used to create `Update`, `UpdateDeleteWhere` or
`UpdateRequest` objects. When an `UpdateRequest` is built is contains a single
`Update` object as defined by the `UpdateBuilder`. `Update` objects can be
added to an UpdateRequest using the `appendTo()` method.
+
+ Var subj = Var.alloc( "s" );
+ Var obj = Var.alloc( "o" );
+
+ UpdateBuilder builder = new UpdateBuilder( PrefixMapping.Standard)
+ .addInsert( subj, "rdfs:comment", obj )
+ .addWhere( subj, "dc:title", obj);
+
+ UpdateRequest req = builder.buildRequest();
+
+ UpdateBuilder builder2 = new UpdateBuilder()
+ .addPrefix( "dc", "http://purl.org/dc/elements/1.1/";)
+ .addDelete( subj, "?p", obj)
+ .where( subj, dc:creator, "me")
+ .appendTo( req );
+
+Where Builder
+=============
+
+In some use cases it is desirable to create a where clause without
constructing an entire query. The `WhereBuilder` is designed to fit this need.
For example to construct the query:
+
+ PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+ PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+ SELECT ?page ?type WHERE
+ {
+ ?s foaf:page ?page .
+ { ?s rdfs:label "Microsoft"@en . BIND ("A" as ?type) }
+ UNION
+ { ?s rdfs:label "Apple"@en . BIND ("B" as ?type) }
+ }
+
+You could use a WhereBuilder to construct the union queries and add them to a
Select or other query builder.
+
+ WhereBuilder whereBuilder = new WhereBuilder()
+ .addPrefix( "rdfs", "http://www.w3.org/2000/01/rdf-schema#"; )
+ addWhere( "?s", "rdfs:label", "'Microsoft'@en" )
+ .addBind( "'A'", "?type")
+ .addUnion( new WhereBuilder()
+ .addPrefix( "rdfs", "http://www.w3.org/2000/01/rdf-schema#"; )
+ .addWhere( "?s", "rdfs:label", "'Apple'@en" )
+ .addBind( "'B'", "?type")
+ );
+
+ SelectBuilder builder = new SelectBuilder()
+ .addPrefix( "rdfs", "http://www.w3.org/2000/01/rdf-schema#"; )
+ .addPrefix( "foaf", "http://xmlns.com/foaf/0.1/"; );
+ .addVar( "?page")
+ .addVar( "?type" )
+ .addWhere( "?s", "foaf:page", "?page" )
+ .addWhere( whereBuilder );
+
+The where clauses could be built inline as:
+
+ SelectBuilder builder = new SelectBuilder()
+ .addPrefixs( PrefixMapping.Standard )
+ .addPrefix( "foaf", "http://xmlns.com/foaf/0.1/"; );
+ .addVar( "?page")
+ .addVar( "?type" )
+ .addWhere( "?s", "foaf:page", "?page" )
+ .addWhere( new WhereBuilder()
+ .addPrefix( "rdfs", "http://www.w3.org/2000/01/rdf-schema#"; )
+ .addWhere( "?s", "rdfs:label", "'Microsoft'@en" )
+ .addBind( "'A'", "?type")
+ .addUnion( new WhereBuilder()
+ .addPrefix( "rdfs", "http://www.w3.org/2000/01/rdf-schema#"; )
+ .addWhere( "?s", "rdfs:label", "'Apple'@en" )
+ .addBind( "'B'", "?type")
+ )
+ );
+
+
+
Template Usage
==============
-In addition to making it easier to build valid queries the QueryBuilder has a
clone method.
+In addition to making it easier to build valid queries the QueryBuilder has a
clone method.
Using this a developer can create as "Template" query and add to it as
necessary.
for example using the above query as the "template" the this code:
@@ -38,26 +127,26 @@ for example using the above query as the
produces
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
- SELECT *
- WHERE
- { ?s ?p ?o .
- ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> foaf:person .
- }
+ SELECT *
+ WHERE
+ { ?s ?p ?o .
+ ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> foaf:person .
+ }
Prepared Statement Usage
========================
-The query builders have the ability to replace variables with other values.
This can be
+The query builders have the ability to replace variables with other values.
This can be
SelectBuilder sb = new SelectBuilder()
.addVar( "*" )
.addWhere( "?s", "?p", "?o" );
-
+
sb.setVar( Var.alloc( "?o" ), NodeFactory.createURI(
"http://xmlns.com/foaf/0.1/Person"; ) ) ;
Query q = sb.build();
produces
- SELECT *
- WHERE
+ SELECT *
+ WHERE
{ ?s ?p <http://xmlns.com/foaf/0.1/Person> }
