db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rhille...@apache.org
Subject svn commit: r1693991 - in /db/derby/docs/trunk/src/tools: derbytools.ditamap rtoolsoptsimplejson.dita
Date Tue, 04 Aug 2015 01:40:06 GMT
Author: rhillegas
Date: Tue Aug  4 01:40:06 2015
New Revision: 1693991

URL: http://svn.apache.org/r1693991
DERBY-6829: Document the new simpleJson optional tool.

    db/derby/docs/trunk/src/tools/rtoolsoptsimplejson.dita   (with props)

Modified: db/derby/docs/trunk/src/tools/derbytools.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/derbytools.ditamap?rev=1693991&r1=1693990&r2=1693991&view=diff
--- db/derby/docs/trunk/src/tools/derbytools.ditamap (original)
+++ db/derby/docs/trunk/src/tools/derbytools.ditamap Tue Aug  4 01:40:06 2015
@@ -209,6 +209,7 @@ limitations under the License.
 <topicref href="rtoolsoptlucenelist.dita" navtitle="Listing indexes"/>
 <topicref href="rtoolsoptlucenesecman.dita" navtitle="Running the luceneSupport tool with
a security manager"/>
+<topicref href="rtoolsoptsimplejson.dita" navtitle="Using the simpleJson optional tool"></topicref>
 <topicref href="rtoolstrademderby.dita" navtitle="Trademarks"></topicref>

Added: db/derby/docs/trunk/src/tools/rtoolsoptsimplejson.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptsimplejson.dita?rev=1693991&view=auto
--- db/derby/docs/trunk/src/tools/rtoolsoptsimplejson.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptsimplejson.dita Tue Aug  4 01:40:06 2015
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="utf-8"?>
+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      
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+See the License for the specific language governing permissions and  
+limitations under the License.
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptsimplejson" xml:lang="en-us">
+<title>Using the simpleJson optional tool</title>
+<shortdesc>The <codeph>simpleJson</codeph> optional tool creates functions
+and a user-defined type, which can be used to integrate relational data with data represented
in the popular JSON format.</shortdesc>
+<indexterm>optional tools<indexterm>simpleJson</indexterm></indexterm>
+<indexterm>simpleJson optional tool</indexterm>
+<indexterm>tools<indexterm>simpleJson optional tool</indexterm></indexterm>
+<p>The <codeph>simpleJson</codeph> optional tool relies on support classes
provided by the third party
+JSON.simple jar file. That jar file can be obtained from
+<xref format="html" href="http://code.google.com/p/json-simple/" scope="external"/>.
+Before loading the <codeph>simpleJson</codeph> tool, make sure
+that your classpath contains this third party jar file as well as
+<codeph>derby.jar</codeph> and <codeph>derbyoptionaltools.jar</codeph>.
+The <codeph>simpleJson</codeph> tool has been tested with version 1.1
+of JSON.simple (json_simple-1.1.jar).</p>
+<p>You can load and unload the <codeph>simpleJson</codeph> tool by using
+the <codeph>SYSCS_UTIL.SYSCS_REGISTER_TOOL</codeph> system procedure. See the
+<ph conref="../conrefs.dita#pub/citref"></ph> for information about this
+<p>To load the <codeph>simpleJson</codeph> tool, use the following
+<codeblock><b>call syscs_util.syscs_register_tool( 'simpleJson', true )</b></codeblock>
+<p>This command creates a JSONArray user-defined type in the current schema. That
+type is bound to the JSON array abstraction provided by JSON.simple (<codeph>org.json.simple.JSONArray</codeph>).
+The registration command also creates the following functions in the current
+schema. Javadoc for these functions can be found in the public API for <i>org.apache.derby.optional.api.SimpleJsonUtils</i>:</p>
+<li><b>readArrayFromString()</b> - This function turns a JSON document
string into a JSONArray value.</li>
+<li><b>readArrayFromFile()</b> - This function reads a JSON document stored
in a file and turns that document
+into a JSONArray value.</li>
+<li><b>readArrayFromURL()</b> - This function reads a JSON document from
an URL and turns that document
+into a JSONArray value.</li>
+These functions can then be used to turn JSON documents into tabular data sets using
+<i>org.apache.derby.optional.api.SimpleJsonVTI</i>. That class is documented
in Derby's public api too. Using this technique,
+you can join JSON data with other relational data. You can also exploit this technique
+to import JSON data into Derby tables. Here's an example of how to use these functions
+to import data:
+create function thermostatReadings( jsonDocument JSONArray )
+returns table
+  "id" int,
+  "temperature" float,
+  "fanOn" boolean
+language java parameter style derby_jdbc_result_set contains sql
+external name 'org.apache.derby.optional.api.SimpleJsonVTI.readArray';
+insert into thermostatReadings
+ select * from table
+ (
+    thermostatReadings
+    (
+       readArrayFromURL( 'https://thermostat.feed.org', 'UTF-8' )
+    )
+ ) t;
+After running that query, the contents of the target table might look something like this:
+ id         |temperature             |fanOn
+ ------------------------------------------
+ 1          |70.3                    |true 
+ 2          |65.5                    |false
+The <codeph>simpleJson</codeph> tool declares one more function:
+<li><b>toJSON()</b> - This function turns a query result into a JSONArray
+This function has the following signature:
+create function toJSON
+    queryString varchar( 32672 ),
+    queryArgs varchar( 32672 ) ...
+returns JSONArray
+language java parameter style derby reads sql data
+external name 'org.apache.derby.optional.json.SimpleJsonTool.toJSON
+<b>toJSON()</b> prepares the query, plugs the optional queryArgs into the query's
? parameters, executes
+the query, and returns the results packed into a JSONArray. Here's an example of how
+to use this function:
+values( toJSON( 'select * from thermostatReadings where "id" = ?', '1' ) );
+That statement returns a JSONArray which looks something like this:
+    { "id": 1, "temperature": 70.3, "fanOn": true }
+The tool can be unloaded via the following command. This command drops the JSONArray type
+all of the functions discussed above:
+<codeblock><b>call syscs_util.syscs_register_tool( 'simpleJson', false )</b></codeblock>

Propchange: db/derby/docs/trunk/src/tools/rtoolsoptsimplejson.dita
    svn:eol-style = native

View raw message