<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry id="HO-S-1">
  <refmeta>
    <refentrytitle>Java Runtime Hosting</refentrytitle>
    <refmiscinfo>tutorial</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>Integrating Java Objects with Virtuoso</refname>
    <refpurpose>Using Java Objects to extend Virtuoso via User Defined Types.</refpurpose>
  </refnamediv>

    <refsect1 id="HO-S-1a_overview">
    <title>Overview</title>
  <para>The following tutorial demonstrates how Virtuoso can be extended 
  through the use of Java to create User Defined Types (UDTs), Stored Procedures, 
  and Functions. This is an enhancement of its Object-Relational Database functionality. </para>
  <para>The demonstrations in this section highlight transparent integration 
  (hosting) between Virtuoso and the Java Runtime Environment. </para>
  </refsect1>

    <refsect1 id="HO-S-1a_overview_prerequisites">
    <title>Prerequisites</title>
  <para>The following prerequisites ensure the usability of these tutorial demos on any platform with a Java Runtime environment:</para>
<itemizedlist>
  <listitem>Java Runtime (J2EE 1.2 and Higher)</listitem>
  <listitem>Java SDK (if you seek to write your own Objects for integration with Virtuoso)</listitem>
  <listitem>Virtuoso Universal Server with Java Runtime Hosting </listitem>
 </itemizedlist>
</refsect1>

    <refsect1 id="HO-S-1a">
    <title>Tutorial Example</title>
<para>The following tutorial shows how Java Classes are used to create User Defined Types (UDTs), Stored Procedures, and Functions in Virtuoso. </para>
<para>Please follow the steps below to maximize the value of this tutorial:</para>
<orderedlist>
  <listitem>Click on the "Set Initial State" link which registers the Java classes used in this demo with Virtuoso. Click on the "ho_s_1.sql" link to see the code behind this step </listitem>
  <listitem>Click on the "Run" links to actually experience the demo</listitem>
</orderedlist>

<para>Demo Breakdown</para>
<orderedlist>
  <listitem>"ho_s_1.sql" performs the following steps
    <orderedlist>
       <listitem>Registers the "MyFinances" and "Point" Classes with Virtuoso as 
       UDTs. Click on the "MyFinances.java" and "Point.java" links to see the 
       JAVA source code </listitem>
       <listitem>Creates the conventional SQL table "Employee" </listitem>
       <listitem>Creates the Object-Relational table "Supplier" that includes a 
       column named "Location" that is of  Type "Point" (which is a UDT)</listitem>
       <listitem>Populates each of the newly created tables with data</listitem>
       <listitem>Creates the "distance" stored procedure which uses UDT 
       methods to calculate the distance between points.</listitem>
    </orderedlist>
    </listitem>
    <listitem>"vsp1.vsp" uses the static method "tax" of the "MyFinances" 
    class to compute the payroll tax values for each employee via the 
    "salary" column (like a SQL function would). </listitem>
    <listitem>"vsp2.vsp" uses the "distance" method of the UDT based column 
    "location" to test for distance values less than "3". The distance values are return values from the "Point" UDT. Note that "Point" class is computing the distance between two arbitrary points</listitem>
    <listitem>"vsp3.vsp" is a variation of the previous demo, with the UDT based 
    column "location" being used to access and conditionally test the values of 
    data member "x" (shown in "Point.java" as 0)</listitem>
    <listitem>"vsp4.vsp" is another variation of a query on the "Supplier" table, 
    in this particular case the query uses a Stored Procedure (see definition in 
    "ho_s_2.sql") to filter its result set.  It achieves this by using data member 
    values "x" and "y" from column "location", and the arbitrary values 1 &amp; 2 
    as input parameters for the Stored Procedure "distance".  It then tests 
    the return values for those less than 3.</listitem>
</orderedlist>
    </refsect1>
</refentry>
