<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="16. Runtime Hosting" />
<meta name="dc.subject" content="16. Runtime Hosting" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="runtimehosting.html" title="Chapter Contents" />
<link rel="prev" href="rthclrmono.html" title="CLR & Mono" />
<link rel="next" href="cinterface.html" title="Virtuoso Server Extension Interface (VSEI) (C Interface)" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>16. Runtime Hosting</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="javaextvm" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>16. Runtime Hosting</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="runtimehosting.html">Chapter Contents</a> | <a class="link" href="rthclrmono.html" title="CLR & Mono">Prev</a> | <a class="link" href="cinterface.html" title="Virtuoso Server Extension Interface (VSEI) (C Interface)">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div class="selected">
<a href="runtimehosting.html">Runtime Hosting</a>
</div>
<br />
<div>
<a href="rthactivation.html">Runtime Environments</a>
</div>
<div>
<a href="rthclr.html">CLR, .Net & ASPX Host</a>
</div>
<div>
<a href="rthclrmono.html">CLR & Mono</a>
</div>
<div class="selected">
<a href="javaextvm.html">Embedded Java VM API</a>
<div>
<a href="#virtvsjvmthreads" title="Correspondence Between Virtuoso & Java VM Threads">Correspondence Between Virtuoso & Java VM Threads</a>
<a href="#virtpljvmtypemapp" title="Virtuoso/PL <-> Java VM Type Mapping Schema">Virtuoso/PL <-> Java VM Type Mapping Schema</a>
<a href="#referencestojvminvpl" title="References to Java VM Class Instances in Virtuoso/PL">References to Java VM Class Instances in Virtuoso/PL</a>
<a href="#correctjavatype" title="Specifying the Correct Java Type When Passing Values from Virtuoso/PL">Specifying the Correct Java Type When Passing Values from Virtuoso/PL</a>
<a href="#virtjavabifs" title="Virtuoso Java PL API VSEs">Virtuoso Java PL API VSEs</a>
<a href="#jvmapisecurity" title="Java Security">Java Security</a>
</div>
</div>
<div>
<a href="cinterface.html">Virtuoso Server Extension Interface (VSEI) (C Interface)</a>
</div>
<div>
<a href="vseplugins.html">VSEI Plugins</a>
</div>
<br />
</div>
<div id="text">
<a name="javaextvm" />
<h2>16.4. Embedded Java VM API</h2>
<p>The Java VM is an embedded system within Virtuoso that allows the
calling of class Java methods and getting class properties. It uses the
JAVA JNI API to interact with the JAVA VM.</p>
<a name="virtvsjvmthreads" />
<h3>16.4.1. Correspondence Between Virtuoso & Java VM Threads</h3>
<p>At maximum one Java VM will be started on demand. If a function from the
Java VM API is called and no JVM is running, one will be started, as required.
Since Virtuoso is multithreaded it requires JDK version 1.3 or above in order
to make better use of it's multithreading support. If the Java VM is already
running the API VSEs attaches the current Virtuoso working thread, if not
already attached, as a Java VM thread to the running VM. The Virtuoso
worker thread does not automatically detached itself from the Java VM after
use, therefore, in order to prevent leaving redundant Virtuoso worker threads
being left attached to the Java VM the
<a href="fn_java_vm_detach.html">java_vm_detach()</a>
VSE should be used.</p>
<p>The following require access to the Java VM:</p>
<ul>
<li>all Virtuoso JAVA PL API (JVM VSEs)</li>
<li>allocating/deallocating/copying of the Virtuoso/PL Java VM class
reference values.</li>
</ul>
<p>If no subsequent JVM VSEs are called after calling
<span class="computeroutput">java_vm_detach()</span>, the worker thread can still attach to
the VM in order to deallocate or copy Java VM class reference values.
In order to ensure that the worker thread is properly detached it is
advisable to set all the variables that may hold Java VM class reference
values to NULL, which deallocates their current value, before calling the
<span class="computeroutput">java_vm_detach()</span> JVM VSE.</p>
<p>Attaching and detaching Virtuoso worker threads is marked as a debug
level message in the Virtuoso Event log, so that these messages can be used to
debug the process.</p>
<br />
<a name="virtpljvmtypemapp" />
<h3>16.4.2. Virtuoso/PL <-> Java VM Type Mapping Schema</h3>
<p>Since the Java language uses a different set of data types than
Virtuoso a type mapping system has been established to allow the passage of data
to and from Java. All Java simple types are mapped to a corresponding
Virtuoso type as follows:</p>
<table class="data">
<caption>Table: 16.4.2.1. Java - Virtuoso Data Type Mapping</caption>
<tr>
<th class="data">Java Type/Class</th>
<th class="data">Virtuoso Internal Type</th>
</tr>
<tr>
<td class="data">boolean</td>
<td class="data">smallint</td>
</tr>
<tr>
<td class="data">char</td>
<td class="data">smallint</td>
</tr>
<tr>
<td class="data">double</td>
<td class="data">double precision</td>
</tr>
<tr>
<td class="data">float</td>
<td class="data">real</td>
</tr>
<tr>
<td class="data">int</td>
<td class="data">integer</td>
</tr>
<tr>
<td class="data">short</td>
<td class="data">integer</td>
</tr>
<tr>
<td class="data">long</td>
<td class="data">integer</td>
</tr>
<tr>
<td class="data">boolean</td>
<td class="data">smallint</td>
</tr>
<tr>
<td class="data">java.lang.String</td>
<td class="data">NVARCHAR</td>
</tr>
<tr>
<td class="data">java.util.Date</td>
<td class="data">DATETIME</td>
</tr>
</table>
<br />
<p>All other Java objects are represented as a special Virtuoso value,
which contains a reference to the Java object in the VM memory space. When
such a value is returned as a Virtuoso/PL return value or as a result set
column, it calls the <span class="computeroutput">java.lang.Object.toString()</span> method
for the Java VM object it refers to and that result is returned to the
calling client.</p>
<p>Arrays are mapped to a Virtuoso vector of their elements. The array
handling routines are recursive, so each element may be a Java array or a
scalar type.</p>
<p>The above mappings are applied when converting Virtuoso/PL data to
Java data as follows:</p>
<ul>
<li>method parameter values in java_call_method VSE</li>
<li>method parameter values in java_new_object VSE</li>
<li>property values in java_set_property VSE</li>
<li>the instance parameters in
java_call_method/java_get_property/java_set_property VSEs</li>
</ul>
<p>The above mappings are applied in the opposite direction
(Java Data -> Virtuoso/PL data) as follows:</p>
<ul>
<li>method return values in java_call_method VSE</li>
<li>return value of the java_new_object VSE</li>
<li>property values returned from java_get_property VSE</li>
</ul>
<br />
<a name="referencestojvminvpl" />
<h3>16.4.3. References to Java VM Class Instances in Virtuoso/PL</h3>
<p>Java Class instances are represented as a Virtuoso/PL variable values
using a Java VM Global Reference. Each time such a Virtuoso/PL variable
value is created or copied, it adds a Java VM Global Reference. When it is
freed, it removes the Java VM global reference, allowing the Java
Garbage collector (GC) to free it. Each of the API VSEs create a Java VM
local frame upon it's start, and frees it upon exit. This allows for
fast deallocation of the local objects created by mapping Virtuoso/PL native
values to Java objects.</p>
<br />
<a name="correctjavatype" />
<h3>16.4.4. Specifying the Correct Java Type When Passing Values from Virtuoso/PL</h3>
<p>Each method parameter in the
<span class="computeroutput">java_new_object()</span>/<span class="computeroutput">java_call_method()</span>
can be either the value itself or a two-element vector. When it is a
two-element vector it's first element is the JNI type signature string,
e.g.: for integer - I, for array of integers - [I], for
java.lang.String - Ljava/lang/String. The signature is important because
the Java VM JNI API needs it in order to find the appropriate
constructor/method/property.</p>
<br />
<a name="virtjavabifs" />
<h3>16.4.5. Virtuoso Java PL API VSEs</h3>
<p>The API consists of the following VSEs:</p>
<ul>
<li>
<a href="fn_java_call_method.html">java_call_method()</a>
</li>
<li>
<a href="fn_java_set_property.html">java_set_property()</a>
</li>
<li>
<a href="fn_java_get_property.html">java_get_property()</a>
</li>
<li>
<a href="fn_java_load_class.html">java_load_class()</a>
</li>
<li>
<a href="fn_java_new_object.html">java_new_object()</a>
</li>
<li>
<a href="fn_java_vm_attach.html">java_vm_attach()</a>
</li>
<li>
<a href="fn_java_vm_detach.html">java_vm_detach()</a>
</li>
</ul>
<br />
<a name="jvmapisecurity" />
<h3>16.4.6. Java Security</h3>
<p>Java classes are hosted in one of two modes:</p>
<ul>
<li>Restricted</li>
<li>Unrestricted</li>
</ul>
<p>Java class Permissions are managed by security classes that fall into
categories as follows listed with it managing class:</p>
<ul>
<li>File - java.io.FilePermission</li>
<li>Socket - java.net.SocketPermission</li>
<li>Net - java.net.NetPermission</li>
<li>Security - java.security.SecurityPermission</li>
<li>Runtime - java.lang.RuntimePermission</li>
<li>Property - java.util.PropertyPermission</li>
<li>AWT - java.awt.AWTPermission</li>
<li>Reflect - java.lang.reflect.ReflectPermission</li>
<li>Serializable - java.io.SerializablePermission</li>
</ul>
<p>Restricted classes are not allowed any of the above privileges.
Virtuoso returns errors that are returned by the security manager if
breaches in security are attempted by a hosted Java class.</p>
<p>By default all Java classes are imported/created/hosted in restricted
mode. To create Java class based user defined types that are unrestricted
you need to use create type syntax with UNRESTRICTED keyword. The
<a href="fn_import_jar.html">import_jar()</a>
function can also be used to import classes, its third optional parameter
can be used to define the security mode.</p>
<div class="note">
<div class="notetitle">Note:</div>
<p>New behavior since Virtuoso 3.2 provides these two security modes
defaulting to restricted. Prior to this Java classes were hosted in
unrestricted mode.</p>
</div>
<a name="ex_javasecurity" />
<div class="example">
<div class="exampletitle">Java Security</div>
<p>The class Write_file, shown below, will attempt to write to a file on
the file system. This class will be used to create a user defined type first
in unrestricted mode and then in restricted mode to demonstrate how security
exceptions are returned.</p>
<p>Source of Write_file.java:</p>
<div>
<pre class="programlisting">
import java.io.*;
public class Write_file
{
public String write ()
{
String myFile = "foo";
File f = new File(myFile);
DataOutputStream dos;
try
{
dos = new DataOutputStream (new BufferedOutputStream(new FileOutputStream (myFile),128));
dos.writeBytes("ABC\n");
dos.flush();
dos.close();
}
catch (IOException ioe)
{
System.out.println("writeFile: caught i/o exception");
}
return "OK";
}
}
</pre>
</div>
<p>Create the unrestricted type:</p>
<div>
<pre class="programlisting">
create type "Write_file" language JAVA external name 'Write_file'
unrestricted METHOD "write" ()
returns nvarchar external type 'Ljava/lang/String;' external name 'write';
</pre>
</div>
<p>Test calling the method:</p>
<div>
<pre class="programlisting">
SQL> select new Write_file().write();
callret
NVARCHAR
_________________________________________
OK
</pre>
</div>
<p>Now we want to recreate the type in restricted mode, remembering to
drop it first:</p>
<div>
<pre class="programlisting">
drop type DB.DBA.write_file;
create type "Write_file" language JAVA external name 'Write_file'
METHOD "write" ()
returns nvarchar external type 'Ljava/lang/String;' external name 'write';
</pre>
</div>
<p>Test calling the method:</p>
<div>
<pre class="programlisting">
SQL> select new Write_file().write();
*** Error 42000: [Virtuoso Driver][Virtuoso Server]JV001: Java exception
occurred : java.security.AccessControlException : access denied
(java.io.FilePermission foo write)
in __udt_method_call:(BIF),
<Top Level>
at line 1 of Top-Level:
select new Write_file().write()
</pre>
</div>
<p>Another way to import the above class is by use the
<span class="computeroutput">import_jar()</span> such as:</p>
<div>
<pre class="programlisting">
import_jar (NULL, 'Write_file', 1) - will import java classes in unrestricted mode.
import_jar (NULL, 'Write_file') - will import java classes in restricted mode.
</pre>
</div>
</div>
<br />
<table border="0" width="90%" id="navbarbottom">
<tr>
<td align="left" width="33%">
<a href="rthclrmono.html" title="CLR & Mono">Previous</a>
<br />CLR & Mono</td>
<td align="center" width="34%">
<a href="runtimehosting.html">Chapter Contents</a>
</td>
<td align="right" width="33%">
<a href="cinterface.html" title="Virtuoso Server Extension Interface (VSEI) (C Interface)">Next</a>
<br />Virtuoso Server Extension Interface (VSEI) (C Interface)</td>
</tr>
</table>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
790
