You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by mj...@apache.org on 2016/05/05 23:36:41 UTC
[06/51] [abbrv] [partial] incubator-guacamole-website git commit:
Deploy first version of the Apache Guacamole website (reworded and restyled
from the old guac-dev.org).
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/af9b9c05/content/doc/0.8.3/gug/guacamole-common-js.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/guacamole-common-js.html b/content/doc/0.8.3/gug/guacamole-common-js.html
new file mode 100644
index 0000000..3f6b45f
--- /dev/null
+++ b/content/doc/0.8.3/gug/guacamole-common-js.html
@@ -0,0 +1,401 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter�12.�guacamole-common-js</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="developers-guide.html" title="Part�II.�Developer's Guide" /><link rel="prev" href="guacamole-common.html" title="Chapter�11.�guacamole-common" /><link rel="next" href="guacamole-ext.html" title="Chapter�13.�guacamole-ext" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/>
+ </head><body>
+ <!-- CONTENT -->
+
+ <div id="page"><div id="content">
+ <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter�12.�guacamole-common-js</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="guacamole-common.html">Prev</a>�</td><th width="60%" align="center">Part�II.�Developer's Guide</th><td width="20%" align="right">�<a accesskey="n" href="guacamole-ext.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter�12.�guacamole-common-js" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="guacamole-common-js"></a>Chapter�12.�guacamole-common-js</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="guacamole-common-js.html#guacamole-client">Guacamole client</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#http-tunnel">HTTP tunnel</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#input-abstr
action">Input abstraction</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-common-js.html#guacamole-mouse">Mouse</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#guacamole-touch">Touch</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#guacamole-keyboard">Keyboard</a></span></dt></dl></dd><dt><span class="section"><a href="guacamole-common-js.html#on-screen-keyboard">On-screen keyboard</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-common-js.html#keyboard-layouts">Keyboard layouts</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#displaying-osk">Displaying the keyboard</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#styling-the-keyboard">Styling the keyboard</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#osk-event-handling">Handling key events</a></span></dt></dl></dd></dl></div>
+
+ <a id="idp1586768" class="indexterm"></a>
+ <a id="idp1588192" class="indexterm"></a>
+ <p>The Guacamole project provides a JavaScript API for interfacing with
+ other components that conform to the design of Guacamole, such as
+ projects using libguac or guacamole-common. This API is called
+ guacamole-common-js.</p>
+ <p>guacamole-common-js provides a JavaScript implementation of a
+ Guacamole client, as well as tunneling mechanisms for getting protocol
+ data out of JavaScript and into guacd or the server side of a web
+ application.</p>
+ <p>For convenience, it also provides mouse and keyboard abstraction objects that translate
+ JavaScript mouse, touch, and keyboard events into consistent data that Guacamole can more
+ easily digest. The extendable on-screen keyboard that was developed for the Guacamole web
+ application is also included.</p>
+ <div class="section" title="Guacamole client"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacamole-client"></a>Guacamole client</h2></div></div></div>
+
+ <p>The main benefit to using the JavaScript API is the full Guacamole
+ client implementation, which implements all Guacamole instructions,
+ and makes use of the tunnel implementations provided by both the
+ JavaScript and Java APIs.</p>
+ <p>Using the Guacamole client is straightforward. The client, like
+ all other objects within the JavaScript API, is within the
+ <code class="code">Guacamole</code> namespace. It is instantiated given an
+ existing, unconnected tunnel:</p>
+ <div class="informalexample">
+ <pre class="programlisting">var client = new Guacamole.Client(tunnel);</pre>
+ </div>
+ <p>Once you have the client, it won't immediately appear within the
+ DOM. You need to add its display element manually:</p>
+ <div class="informalexample">
+ <pre class="programlisting">document.body.appendChild(client.getDisplay());</pre>
+ </div>
+ <p>At this point, the client will be visible, rendering all updates
+ as soon as they are received through the tunnel.</p>
+ <div class="informalexample">
+ <pre class="programlisting">client.connect();</pre>
+ </div>
+ <p>It is possible to pass arbitrary data to the tunnel during
+ connection which can be used for authentication or for choosing a
+ particular connection. When the <code class="methodname">connect()</code>
+ function of the Guacamole client is called, it in turn calls the
+ <code class="methodname">connect()</code> function of the tunnel
+ originally given to the client, establishing a connection.</p>
+ <div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
+ <p>When creating the <code class="classname">Guacamole.Client</code>, the
+ tunnel used must not already be connected. The
+ <code class="classname">Guacamole.Client</code> will call the
+ <code class="methodname">connect()</code> function for you when its
+ own <code class="methodname">connect()</code> function is invoked. If
+ the tunnel is already connected when it is given to the
+ <code class="classname">Guacamole.Client</code>, connection may not
+ work at all.</p>
+ </div>
+ <p>In general, all instructions available within the Guacamole
+ protocol are automatically handled by the Guacamole client,
+ including instructions related to audio and video. The only
+ instructions which you must handle yourself are "name" (used to name
+ the connection), "clipboard" (used to update clipboard data on the
+ client side), and "error" (used when something goes wrong
+ server-side). Each of these instructions has a corresponding event
+ handler; you need only supply functions to handle these events. If
+ any of these event handlers are left unset, the corresponding
+ instructions are simply ignored.</p>
+ </div>
+ <div class="section" title="HTTP tunnel"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="http-tunnel"></a>HTTP tunnel</h2></div></div></div>
+
+ <p>Both the Java and JavaScript API implement corresponding ends of
+ an HTTP tunnel, based on
+ <code class="classname">XMLHttpRequest</code>.</p>
+ <p>The tunnel is a true stream - there is no polling. An initial
+ request is made from the JavaScript side, and this request is
+ handled on the Java side. While this request is open, data is
+ streamed along the connection, and instructions within this stream
+ are handled as soon as they are received by the client.</p>
+ <p>While data is being streamed along this existing connection, a
+ second connection attempt is made. Data continues to be streamed
+ along the original connection until the server receives and handles
+ the second request, at which point the original connection closes
+ and the stream is transferred to the new connection.</p>
+ <p>This process repeats, alternating between active streams, thus
+ creating an unbroken sequence of instructions, while also allowing
+ JavaScript to free any memory used by the previously active
+ connection.</p>
+ <p>The tunnel is created by supplying the relative URL to the
+ server-side tunnel servlet:</p>
+ <div class="informalexample">
+ <pre class="programlisting">var tunnel = new Guacamole.Tunnel("tunnel");</pre>
+ </div>
+ <p>Once created, the tunnel can be passed to a
+ <code class="classname">Guacamole.Client</code> for use in a Guacamole
+ connection.</p>
+ <p>The tunnel actually takes care of the Guacamole protocol parsing
+ on behalf of the client, triggering "oninstruction" events for every
+ instruction received, splitting each element into elements of an
+ array so that the client doesn't have to.</p>
+ </div>
+ <div class="section" title="Input abstraction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="input-abstraction"></a>Input abstraction</h2></div></div></div>
+
+ <p>Browsers can be rather finicky when it comes to keyboard and mouse
+ input, not to mention touch events. There is little agreement on
+ which keyboard events get fired when, and what detail about the
+ event is made available to JavaScript. Touch and mouse events can
+ also cause confusion, as most browsers will generate
+ <span class="emphasis"><em>both</em></span> events when the user touches the
+ screen (for compatibility with JavaScript code that only handles
+ mouse events), making it more difficult for applications to support
+ both mouse and touch independently.</p>
+ <p>The Guacamole JavaScript API abstracts mouse, keyboard, and touch
+ interaction, providing several helper objects which act as an
+ abstract interface between you and the browser events.</p>
+ <div class="section" title="Mouse"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-mouse"></a>Mouse</h3></div></div></div>
+
+ <p>Mouse event abstraction is provided by the
+ <code class="classname">Guacamole.Mouse</code> object. Given an
+ arbitrary DOM element, <code class="classname">Guacamole.Mouse</code>
+ triggers <span class="property">onmousedown</span>,
+ <span class="property">onmousemove</span>, and
+ <span class="property">onmouseup</span> events which are consistent
+ across browsers. This object only response. to true mouse
+ events. Mouse events which are actually the result of touch
+ events are ignored.</p>
+ <div class="informalexample">
+ <pre class="programlisting">var element = document.getElementById("some-arbitrary-id");
+var mouse = new Guacamole.Mouse(element);
+
+mouse.onmousedown =
+mouse.onmousemove =
+mouse.onmouseup = function(state) {
+
+ // Do something with the mouse state received ...
+
+};</pre>
+ </div>
+ <p>The handles of each event are given an instance of
+ <code class="classname">Guacamole.Mouse.State</code> which
+ represents the current state of the mouse, containing the state
+ of each button (including the scroll wheel) as well as the X and
+ Y coordinates of the pointer in pixels.</p>
+ </div>
+ <div class="section" title="Touch"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-touch"></a>Touch</h3></div></div></div>
+
+ <p>Touch event abstraction is provided by either
+ <code class="classname">Guacamole.Touchpad</code> (emulates a
+ touchpad to generate artificial mouse events) or
+ <code class="classname">Guacamole.Touchscreen</code> (emulates a
+ touchscreen, again generating artificial mouse events).
+ Guacamole uses the touchpad emulation, as this provides the most
+ flexibility and mouse-like features, including scrollwheel and
+ clicking with different buttons, but your preferences may
+ differ.</p>
+ <div class="informalexample">
+ <pre class="programlisting">var element = document.getElementById("some-arbitrary-id");
+var touch = new Guacamole.Touchpad(element); // or Guacamole.Touchscreen
+
+touch.onmousedown =
+touch.onmousemove =
+touch.onmouseup = function(state) {
+
+ // Do something with the mouse state received ...
+
+};</pre>
+ </div>
+ <p>Note that even though these objects are touch-specific, they
+ still provide mouse events. The state object given to the event
+ handlers of each event is still an instance of
+ <code class="classname">Guacamole.Mouse.State</code>.</p>
+ <p>Ultimately, you could assign the same event handler to all the
+ events of both an instance of
+ <code class="classname">Guacamole.Mouse</code> as well as
+ <code class="classname">Guacamole.Touchscreen</code> or
+ <code class="classname">Guacamole.Touchpad</code>, and you would
+ magically gain mouse and touch support. This support, being
+ driven by the needs of remote desktop, is naturally geared
+ around the mouse and providing a reasonable means of interacting
+ with it. For an actual mouse, events are translated simply and
+ literally, while touch events go through additional emulation
+ and heuristics. From the perspective of the user and the code,
+ this is all transparent.</p>
+ </div>
+ <div class="section" title="Keyboard"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-keyboard"></a>Keyboard</h3></div></div></div>
+
+ <p>Keyboard events in Guacamole are abstracted with the
+ <code class="classname">Guacamole.Keyboard</code> object as only
+ keyup and keydown events; there is no keypress like there is in
+ JavaScript. Further, all the craziness of keycodes vs. scancodes
+ vs. key identifiers normally present across browsers is
+ abstracted away. All your event handlers will see is an X11
+ keysym, which represent every key unambiguously. Conveniently,
+ X11 keysyms are also what the Guacamole protocol requires, so if
+ you want to use <code class="classname">Guacamole.Keyboard</code> to
+ drive key events sent over the Guacamole protocol, everything
+ can be connected directly.</p>
+ <p>Just like the other input abstraction objects,
+ <code class="classname">Guacamole.Keyboard</code> requires a DOM
+ element as an event target. Only key events directed at this
+ element will be handled.</p>
+ <div class="informalexample">
+ <pre class="programlisting">var keyboard = new Guacamole.Keyboard(document);
+
+keyboard.onkeydown = function(keysym) {
+ // Do something ...
+};
+
+keyboard.onkeyup = function(keysym) {
+ // Do something ...
+};</pre>
+ </div>
+ <p>In this case, we are using <code class="classname">document</code> as
+ the event target, thus receiving all key events while the
+ browser window (or tab) has focus.</p>
+ </div>
+ </div>
+ <div class="section" title="On-screen keyboard"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="on-screen-keyboard"></a>On-screen keyboard</h2></div></div></div>
+
+ <p>The Guacamole JavaScript API also provides an extendable on-screen
+ keyboard, <code class="classname">Guacamole.OnScreenKeyboard</code>, which
+ requires the URL of an XML file describing the keyboard layout. The
+ on-screen keyboard object provides no hard-coded layout information;
+ the keyboard layout is described entirely within the XML layout
+ file.</p>
+ <div class="section" title="Keyboard layouts"><div class="titlepage"><div><div><h3 class="title"><a id="keyboard-layouts"></a>Keyboard layouts</h3></div></div></div>
+
+ <p>The keyboard layout XML included in the Guacamole web
+ application would be a good place to start regarding how these
+ layout files are written, but in general, the keyboard is simply
+ a set of rows or columns, denoted with <code class="code"><row></code> and
+ <code class="code"><column></code> tags respectively, where each can
+ be nested within the other as desired.</p>
+ <p>Each key is represented with a <code class="code"><key></code> tag, but
+ this is not what the user sees, nor what generates the key
+ event. Each key contains any number of <code class="code"><cap></code>
+ tags, which represent the visible part of the key. The cap
+ describes which X11 keysym will be sent when the key is pressed.
+ Each cap can be associated with any combination of arbitrary
+ modifier flags which dictate when that cap is active.</p>
+ <p>For example:</p>
+ <div class="informalexample">
+ <pre class="programlisting"><keyboard lang="en_US" layout="example" size="5">
+ <row>
+ <key size="4">
+ <cap modifier="shift" keysym="0xFFE1">Shift</cap>
+ </key>
+ <key>
+ <cap>a</cap>
+ <cap if="shift">A</cap>
+ </key>
+ </row>
+</keyboard></pre>
+ </div>
+ <p>Here we have a very simple keyboard which defines only two
+ keys: "shift" (a modifier) and the letter "a". When "shift" is
+ pressed, it sets the "shift" modifier, affecting other keys in
+ the keyboard. The "a" key has two caps: one lowercase (the
+ default) and one uppercase (which requires the shift modifier to
+ be active).</p>
+ <p>Notice that the shift key needed the keysym explicitly
+ specified, while the "a" key did not. This is because the
+ on-screen keyboard will automatically derive the correct keysym
+ from the text of the key cap if the text contains only a single
+ character.</p>
+ </div>
+ <div class="section" title="Displaying the keyboard"><div class="titlepage"><div><div><h3 class="title"><a id="displaying-osk"></a>Displaying the keyboard</h3></div></div></div>
+
+ <p>Once you have a keyboard layout available, adding an on-screen
+ keyboard to your application is simple:</p>
+ <div class="informalexample">
+ <pre class="programlisting">// Add keyboard to body
+var keyboard = new Guacamole.OnScreenKeyboard("path/to/layout.xml");
+document.body.appendChild(keyboard.getElement());
+
+// Set size of keyboard to 100 pixels
+keyboard.resize(100);</pre>
+ </div>
+ <p>Here, we have explicitly specified the width of the keyboard
+ as 100 pixels. Normally, you would determine this by inspecting
+ the width of the containing component, or by deciding on a
+ reasonable width beforehand. Once the width is given, the height
+ of the keyboard is determined based on the arrangement of each
+ row.</p>
+ </div>
+ <div class="section" title="Styling the keyboard"><div class="titlepage"><div><div><h3 class="title"><a id="styling-the-keyboard"></a>Styling the keyboard</h3></div></div></div>
+
+ <p>While the <code class="classname">Guacamole.OnScreenKeyboard</code>
+ object will handle most of the layout, you will still need to
+ style everything yourself with CSS to get the elements to render
+ properly and the keys to change state when clicked or activated.
+ It defines several CSS classes, which you will need to manually
+ style to get things looking as desired:</p>
+ <div class="variablelist"><dl><dt><span class="term"><code class="classname">guac-keyboard</code></span></dt><dd>
+ <p>This class is assigned to the root element
+ containing the entire keyboard, returned by
+ <code class="methodname">getElement()</code>,</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-row</code></span></dt><dd>
+ <p>Assigned to the <code class="code">div</code> elements which
+ contain each row.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-column</code></span></dt><dd>
+ <p>Assigned to the <code class="code">div</code> elements which
+ contain each column.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-gap</code></span></dt><dd>
+ <p>Assigned to any <code class="code">div</code> elements created
+ as a result of <code class="code"><gap></code> tags in the
+ keyboard layout. <code class="code"><gap></code> tags are
+ intended to behave as keys with no visible styling
+ or caps.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-key-container</code></span></dt><dd>
+ <p>Assigned to the <code class="code">div</code> element which
+ contains a key, and provides that key with its
+ required dimensions. It is this element that will be
+ scaled relative to the size specified in the layout
+ XML and the size given to the <code class="code">resize()</code>
+ function.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-key</code></span></dt><dd>
+ <p>Assigned to the <code class="code">div</code> element which
+ represents the actual key, not the cap. This element
+ will not directly contain text, but it will contain
+ all caps that this key can have. With clever CSS
+ rules, you can take advantage of this and cause
+ inactive caps to appear on the key in a corner (for
+ example), or hide them entirely.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-cap</code></span></dt><dd>
+ <p>Assigned to the <code class="code">div</code> element
+ representing a key cap. Each cap is a child of its
+ corresponding key, and it is up to the author of the
+ CSS rules to hide or show or reposition each cap
+ appropriately. Each cap will contain the display
+ text defined within the <code class="code"><cap></code>
+ element in the layout XML.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-requires-<em class="replaceable"><code>MODIFIER</code></em></code></span></dt><dd>
+ <p>Added to the cap element when that cap requires a
+ specific modifier.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-uses-<em class="replaceable"><code>MODIFIER</code></em></code></span></dt><dd>
+ <p>Added to the key element when any cap contained
+ within it requires a specific modifier.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-modifier-<em class="replaceable"><code>MODIFIER</code></em></code></span></dt><dd>
+ <p>Added to and removed from the root keyboard
+ element when a modifier key is activated or
+ deactivated respectively.</p>
+ </dd><dt><span class="term"><code class="classname">guac-keyboard-pressed</code></span></dt><dd>
+ <p>Added to and removed from any key element as it is
+ pressed and released respectively.</p>
+ </dd></dl></div>
+ <div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
+ <p>The CSS rules required for the on-screen keyboard to work
+ as expected can be quite complex. Looking over the CSS rules
+ used by the on-screen keyboard in the Guacamole web
+ application would be a good place to start to see how the
+ appearance of each key can be driven through the simple
+ class changes described above.</p>
+ <p>Inspecting the elements of an active on-screen keyboard
+ within the Guacamole web application with the developer
+ tools of your favorite browser is also a good idea.</p>
+ </div>
+ </div>
+ <div class="section" title="Handling key events"><div class="titlepage"><div><div><h3 class="title"><a id="osk-event-handling"></a>Handling key events</h3></div></div></div>
+
+ <p>Key events generated by the on-screen keyboard are identical
+ to those of <code class="classname">Guacamole.Keyboard</code> in that
+ they consist only of a single X11 keysym. Only keyup and keydown
+ events exist, as before; there is no keypress event.</p>
+ <div class="informalexample">
+ <pre class="programlisting">// Assuming we have an instance of Guacamole.OnScreenKeyboard already
+// called "keyboard"
+
+keyboard.onkeydown = function(keysym) {
+ // Do something ...
+};
+
+keyboard.onkeyup = function(keysym) {
+ // Do something ...
+};</pre>
+ </div>
+ </div>
+ </div>
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="guacamole-common.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="guacamole-ext.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�11.�<span class="package">guacamole-common</span>�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�13.�guacamole-ext</td></tr></table></div>
+
+ </div></div>
+
+
+<!-- Google Analytics -->
+<script type="text/javascript">
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-75289145-1', 'auto');
+ ga('send', 'pageview');
+
+</script>
+<!-- End Google Analytics -->
+ </body></html>
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/af9b9c05/content/doc/0.8.3/gug/guacamole-common.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/guacamole-common.html b/content/doc/0.8.3/gug/guacamole-common.html
new file mode 100644
index 0000000..b15741b
--- /dev/null
+++ b/content/doc/0.8.3/gug/guacamole-common.html
@@ -0,0 +1,281 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter�11.�guacamole-common</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="developers-guide.html" title="Part�II.�Developer's Guide" /><link rel="prev" href="libguac.html" title="Chapter�10.�libguac" /><link rel="next" href="guacamole-common-js.html" title="Chapter�12.�guacamole-common-js" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/>
+ </head><body>
+ <!-- CONTENT -->
+
+ <div id="page"><div id="content">
+ <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter�11.�<span class="package">guacamole-common</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="libguac.html">Prev</a>�</td><th width="60%" align="center">Part�II.�Developer's Guide</th><td width="20%" align="right">�<a accesskey="n" href="guacamole-common-js.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter�11.�guacamole-common" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="guacamole-common"></a>Chapter�11.�<span class="package">guacamole-common</span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="guacamole-common.html#java-http-tunnel">HTTP tunnel</a></span></dt><dt><span class="section"><a href="guacamole-common.html#java-protocol-usage">Using the Guacamole protocol</a></span></dt><dd><dl><dt><s
pan class="section"><a href="guacamole-common.html#java-reading-protocol"><code class="classname">GuacamoleReader</code></a></span></dt><dt><span class="section"><a href="guacamole-common.html#java-writing-protocol"><code class="classname">GuacamoleWriter</code></a></span></dt></dl></dd><dt><span class="section"><a href="guacamole-common.html#reading-properties">Reading properties</a></span></dt></dl></div>
+
+ <a id="idp1520176" class="indexterm"></a>
+ <a id="idp1521552" class="indexterm"></a>
+ <p>The Java API provided by the Guacamole project is called
+ guacamole-common. It provides a basic means of tunneling data between
+ the JavaScript client provided by guacamole-common-js and the native
+ proxy daemon, guacd. There are other classes provided as well which make
+ dealing with the Guacamole protocol and reading from
+ <code class="filename">guacamole.properties</code> easier, but in general,
+ the purpose of this library is to facilitate the creation of custom
+ tunnels between the JavaScript client and guacd.</p>
+ <div class="section" title="HTTP tunnel"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="java-http-tunnel"></a>HTTP tunnel</h2></div></div></div>
+
+ <p>The Guacamole Java API implements the HTTP tunnel using a servlet
+ called <code class="classname">GuacamoleHTTPTunnelServlet</code>. This
+ servlet handles all requests coming to it over HTTP from the
+ JavaScript client, and translated them into connect, read, or write
+ requests, which each get dispatched to the
+ <code class="methodname">doConnect()</code>,
+ <code class="methodname">doRead()</code>, and
+ <code class="methodname">doWrite()</code> functions accordingly.</p>
+ <p>Normally, you wouldn't touch the <code class="methodname">doRead()</code>
+ and <code class="methodname">doWrite()</code> functions, as these have
+ already been written to properly handle the requests of the
+ JavaScript tunnel, and if you feel the need to touch these
+ functions, you are probably better off writing your own tunnel
+ implementation, although such a thing is difficult to do in a
+ performant way.</p>
+ <p>When developing an application based on the Guacamole API, you
+ should use <code class="classname">GuacamoleHTTPTunnelServlet</code> by
+ extending it, implementing your own version of
+ <code class="methodname">doConnect()</code>, which is the only abstract
+ function it defines. The tutorial later in this book demonstrating
+ how to write a Guacamole-based web application shows the basics of
+ doing this, but generally, <code class="methodname">doConnect()</code> is
+ an excellent place for authentication or other validation, as it is
+ the responsibility of <code class="methodname">doConnect()</code> to create
+ (or not create) the actual tunnel. If
+ <code class="methodname">doConnect()</code> does not create the tunnel,
+ communication between the JavaScript client and guacd cannot take
+ place, which is an ideal power to have as an authenticator.</p>
+ <p>The <code class="methodname">doConnect()</code> function is expected to
+ "attach" a <code class="classname">GuacamoleTunnel</code> to the web
+ session, abstracted by <code class="classname">GuacamoleSession</code>.
+ Attaching a tunnel to the session allows future tunnel requests to
+ retrieve the same tunnel and use it, thus allowing one tunnel to be
+ split across multiple requests. Assuming the
+ <code class="methodname">doConnect()</code> function successfully
+ creates the tunnel, it must then return the created tunnel. The
+ already-implemented parts of
+ <code class="classname">GuacamoleHTTPTunnelServlet</code> then return
+ the unique identifier of this tunnel to the JavaScript client,
+ allowing its own tunnel implementation to continue to communicate
+ with the tunnel existing on the Java side.</p>
+ <p>Instances of <code class="classname">GuacamoleTunnel</code> are created
+ associated with a <code class="classname">GuacamoleSocket</code>, which is
+ the abstract interface surrounding the low-level connection to
+ guacd. Overall, there is a socket
+ (<code class="classname">GuacamoleSocket</code>) which provides a TCP
+ connection to guacd. This socket is exposed to
+ <code class="classname">GuacamoleTunnel</code>, which provides abstract
+ protocol access around what is actually (but secretly, through the
+ abstraction of the API) a TCP socket. The
+ <code class="classname">GuacamoleSession</code> allows instances of
+ <code class="classname">GuacamoleTunnel</code> to be shared across
+ requests, and <code class="classname">GuacamoleHTTPTunnelServlet</code>
+ pulls these tunnels from the session as necessary to fulfill
+ requests made by the JavaScript client.</p>
+ <p>The Guacamole web application extends this tunnel servlet in order
+ to implement authentication at the lowest possible level,
+ effectively prohibiting communication between the client and any
+ remote desktops unless they have properly authenticated. Your own
+ implementation can be considerably simpler, especially if you don't
+ need authentication:</p>
+ <div class="informalexample">
+ <pre class="programlisting">public class MyGuacamoleTunnelServlet
+ extends GuacamoleHTTPTunnelServlet {
+
+ @Override
+ protected GuacamoleTunnel doConnect(HttpServletRequest request)
+ throws GuacamoleException {
+
+ // Connect to guacd here (this is a STUB)
+ GuacamoleSocket socket;
+
+ // Establish the tunnel using the connected socket
+ GuacamoleTunnel tunnel = new GuacamoleTunnel(socket);
+
+ // Attach tunnel to session
+ GuacamoleSession session = new GuacamoleSession(httpSession);
+ session.attachTunnel(tunnel);
+
+ // Return pre-attached tunnel
+ return tunnel;
+
+ }
+
+}</pre>
+ </div>
+ </div>
+ <div class="section" title="Using the Guacamole protocol"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="java-protocol-usage"></a>Using the Guacamole protocol</h2></div></div></div>
+
+ <p>guacamole-common provides basic low-level support for the
+ Guacamole protocol. This low-level support is leveraged by the HTTP
+ tunnel implementation to satisfy the requirements of the JavaScript
+ client implementation, as the JavaScript client expects the
+ handshake procedure to have already taken place. This support exists
+ through the <code class="classname">GuacamoleReader</code> and
+ <code class="classname">GuacamoleWriter</code> classes, which are
+ similar to Java's <code class="classname">Reader</code> and
+ <code class="classname">Writer</code> classes, except that they deal
+ with the Guacamole protocol specifically, and thus have slightly
+ different contracts.</p>
+ <div class="section" title="GuacamoleReader"><div class="titlepage"><div><div><h3 class="title"><a id="java-reading-protocol"></a><code class="classname">GuacamoleReader</code></h3></div></div></div>
+
+ <p><code class="classname">GuacamoleReader</code> provides a very basic
+ <code class="methodname">read()</code> function which is required
+ to return one or more complete instructions in a
+ <span class="type">char</span> array. It also provides the typical
+ <code class="methodname">available()</code> function, which informs
+ you whether <code class="methodname">read()</code> is likely to block
+ the next time it is called, and an even more abstract version of
+ <code class="methodname">read()</code> called
+ <code class="methodname">readInstruction()</code> which returns one
+ instruction at a time, wrapped within a
+ <code class="classname">GuacamoleInstruction</code> instance.</p>
+ <p>Normally, you would not need to use this class yourself. It is
+ used by <code class="classname">ConfiguredGuacamoleSocket</code> to
+ complete the Guacamole protocol handshake procedure, and it is
+ used by <code class="classname">GuacamoleHTTPTunnelServlet</code> within
+ <code class="methodname">doRead()</code> to implement the reading
+ half of the tunnel.</p>
+ <p>The only concrete implementation of
+ <code class="classname">GuacamoleReader</code> is
+ <code class="classname">ReaderGuacamoleReader</code>, which wraps a
+ Java <code class="classname">Reader</code>, using that as the source for
+ data to parse into Guacamole instructions. Again, you would not
+ normally directly use this class, nor instantiate it yourself. A
+ working, concrete instance of
+ <code class="classname">GuacamoleReader</code> can be retrieved from
+ any <code class="classname">GuacamoleSocket</code> or
+ <code class="classname">GuacamoleTunnel</code>.</p>
+ </div>
+ <div class="section" title="GuacamoleWriter"><div class="titlepage"><div><div><h3 class="title"><a id="java-writing-protocol"></a><code class="classname">GuacamoleWriter</code></h3></div></div></div>
+
+ <p><code class="classname">GuacamoleWriter</code> provides a very basic
+ <code class="methodname">write()</code> function and a more
+ abstract version called
+ <code class="methodname">writeInstruction()</code> which writes
+ instances of <code class="classname">GuacamoleInstruction</code>. These
+ functions are analogous to the <code class="methodname">read()</code>
+ and <code class="methodname">readInstruction()</code> functions
+ provided by <code class="classname">GuacamoleReader</code>, and have
+ similar restrictions: the contract imposed by
+ <code class="methodname">write()</code> requires that written
+ instructions be complete</p>
+ <p>The only concrete implementation of
+ <code class="classname">GuacamoleWriter</code> is
+ <code class="classname">WriterGuacamoleWriter</code>, which wraps a
+ Java <code class="classname">Writer</code>, using that as the
+ destination for Guacamole instruction data, but you would not
+ normally directly use this class, nor instantiate it yourself.
+ It is used by <code class="classname">ConfiguredGuacamoleSocket</code>
+ to complete the Guacamole protocol handshake procedure, and it
+ is used by <code class="classname">GuacamoleHTTPTunnelServlet</code>
+ within <code class="methodname">doWrite()</code> to implement the
+ writing half of the tunnel.</p>
+ <p>If necessary, a <code class="classname">GuacamoleWriter</code> can be
+ retrieved from any <code class="classname">GuacamoleSocket</code> or
+ <code class="classname">GuacamoleTunnel</code>, but in most cases,
+ the classes provided by the Guacamole Java API which already use
+ <code class="classname">GuacamoleWriter</code> will be
+ sufficient.</p>
+ </div>
+ </div>
+ <div class="section" title="Reading properties"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="reading-properties"></a>Reading properties</h2></div></div></div>
+
+ <p>The Guacamole Java API provides simple access to
+ <code class="filename">guacamole.properties</code> for convenience,
+ although such support is not strictly required. This support is
+ provided through the <code class="classname">GuacamoleProperies</code>
+ utility class, which cannot be instantiated and provides two simple
+ property retrieval functions: <code class="methodname">getProperty()</code>
+ and <code class="methodname">getRequiredProperty()</code>, the difference
+ being that the former can return <code class="constant">null</code> if a
+ property is not defined, while the latter will throw an exception
+ instead. These functions are generic and typesafe and will return
+ the correct Java class or type when given an instance of a
+ property.</p>
+ <p>In Guacamole, each property is declared as an implementation of
+ <code class="classname">GuacamoleProperty</code>, and must provide an
+ implementation of <code class="methodname">getName()</code>, which returns
+ the name of the property as it should exist within
+ <code class="filename">guacamole.properties</code>, and
+ <code class="methodname">parseValue()</code>, which is given the
+ <code class="classname">String</code> value of the property as read from
+ <code class="filename">guacamole.properties</code>, and must return the
+ declared type of the <code class="classname">GuacamoleProperty</code>
+ implementation. A good example of how this works is the
+ <code class="classname">IntegerGuacamoleProperty</code> implementation
+ included within guacamole-common:</p>
+ <div class="informalexample">
+ <pre class="programlisting">public abstract class IntegerGuacamoleProperty implements GuacamoleProperty<Integer> {
+
+ @Override
+ public Integer parseValue(String value) throws GuacamoleException {
+
+ // If no property provided, return null.
+ if (value == null)
+ return null;
+
+ try {
+ Integer integer = new Integer(value);
+ return integer;
+ }
+ catch (NumberFormatException e) {
+ throw new GuacamoleServerException("Property \"" + getName() +
+ "\" must be an integer.", e);
+ }
+
+ }
+
+}</pre>
+ </div>
+ <p>Notice that this implementation does not actually provide
+ <code class="methodname">getName()</code>. Instead, it only implements
+ <code class="methodname">parseValue()</code>, the intent being to make
+ other developers' lives easier when they need to retrieve an integer
+ property from <code class="filename">guacamole.properties</code>. Using this
+ class, retrieving an integer property is simple:</p>
+ <div class="informalexample">
+ <pre class="programlisting">public class MyClass {
+
+ public static final IntegerGuacamoleProperty IMPORTANT_INT =
+ new IntegerGuacamoleProperty() {
+
+ @Override
+ public String getName() { return "important-int"; }
+
+ };
+
+}
+
+... later on within MyClass ...
+
+int important = GuacamoleProperties.getRequiredProperty(IMPORTANT_INT);</pre>
+ </div>
+ <p>guacamole-common provides a couple of similar classes for
+ retrieving common types of properties, such as a
+ <code class="classname">String</code> or <code class="classname">File</code>,
+ and implementing your own to facilitate properties that parse into
+ arrays or a <code class="classname">List</code>, etc. should be reasonably
+ simple.</p>
+ </div>
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libguac.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="guacamole-common-js.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�10.�libguac�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�12.�guacamole-common-js</td></tr></table></div>
+
+ </div></div>
+
+
+<!-- Google Analytics -->
+<script type="text/javascript">
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-75289145-1', 'auto');
+ ga('send', 'pageview');
+
+</script>
+<!-- End Google Analytics -->
+ </body></html>
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/af9b9c05/content/doc/0.8.3/gug/guacamole-ext.html
----------------------------------------------------------------------
diff --git a/content/doc/0.8.3/gug/guacamole-ext.html b/content/doc/0.8.3/gug/guacamole-ext.html
new file mode 100644
index 0000000..78eb570
--- /dev/null
+++ b/content/doc/0.8.3/gug/guacamole-ext.html
@@ -0,0 +1,435 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter�13.�guacamole-ext</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="developers-guide.html" title="Part�II.�Developer's Guide" /><link rel="prev" href="guacamole-common-js.html" title="Chapter�12.�guacamole-common-js" /><link rel="next" href="custom-protocols.html" title="Chapter�14.�Adding new protocols" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/>
+ </head><body>
+ <!-- CONTENT -->
+
+ <div id="page"><div id="content">
+ <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter�13.�guacamole-ext</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="guacamole-common-js.html">Prev</a>�</td><th width="60%" align="center">Part�II.�Developer's Guide</th><td width="20%" align="right">�<a accesskey="n" href="custom-protocols.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter�13.�guacamole-ext" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="guacamole-ext"></a>Chapter�13.�guacamole-ext</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="guacamole-ext.html#idp1691712">Common configuration</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-ext.html#idp1694112"><code class="classname">GuacamoleProperties</code></a></span></dt><dt><span class="section"><a href="guacamole-ext.html#idp
1697744"><code class="classname">GuacamoleHome</code></a></span></dt></dl></dd><dt><span class="section"><a href="guacamole-ext.html#auth-providers">Authentication providers</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-ext.html#idp1709904"><code class="classname">SimpleAuthenticationProvider</code></a></span></dt><dt><span class="section"><a href="guacamole-ext.html#idp1717856">The <code class="classname">UserContext</code></a></span></dt><dt><span class="section"><a href="guacamole-ext.html#idp1724304"><code class="classname">Directory</code> classes</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#idp1733904">Permissions</a></span></dt><dt><span class="section"><a href="guacamole-ext.html#idp1795776">Connections and history</a></span></dt></dl></dd><dt><span class="section"><a href="guacamole-ext.html#event-listeners">Event listeners</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-ext.html#tunnel-connect-listener"><cod
e class="classname">TunnelConnectListener</code></a></span></dt><dt><span class="section"><a href="guacamole-ext.html#tunnel-close-listener"><code class="classname">TunnelCloseListener</code></a></span></dt><dt><span class="section"><a href="guacamole-ext.html#authentication-success-listener"><code class="classname">AuthenticationSuccessListener</code></a></span></dt><dt><span class="section"><a href="guacamole-ext.html#authentication-failure-listener"><code class="classname">AuthenticationFailureListener</code></a></span></dt></dl></dd></dl></div>
+
+ <a id="idp1688720" class="indexterm"></a>
+ <a id="idp1689920" class="indexterm"></a>
+ <p>While not strictly part of the Java API provided by the Guacamole
+ project, guacamole-ext is a subset of the API used by the Guacamole web
+ application, exposed within a separate project such that extensions,
+ specifically authentication providers, can be written to tweak Guacamole
+ to fit well in existing deployments.</p>
+ <div class="section" title="Common configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp1691712"></a>Common configuration</h2></div></div></div>
+
+ <p>For the sake of ease of development and providing a common
+ location for configuration of both Guacamole and its extensions,
+ guacamole-ext provides utility classes for accessing the main
+ configuration file, <code class="filename">guacamole.properties</code>, and
+ for accessing the main root directory for housing configuration
+ files: <code class="varname">GUACAMOLE_HOME</code>.</p>
+ <div class="section" title="GuacamoleProperties"><div class="titlepage"><div><div><h3 class="title"><a id="idp1694112"></a><code class="classname">GuacamoleProperties</code></h3></div></div></div>
+
+ <p><code class="classname">GuacamoleProperties</code> is a utility class
+ for accessing the properties declared within
+ <code class="filename">guacamole.properties</code>. Each property is
+ typesafe and handles its own parsing - retrieving a property is
+ as simple as calling <code class="methodname">getProperty()</code> or
+ <code class="methodname">getRequiredProperty()</code>.</p>
+ <p>Because of this ease-of-access to guacamole.properties within
+ Guacamole and all extensions, the
+ <code class="filename">guacamole.properties</code> file is an ideal
+ place to store unstructured, extension-specific configuration
+ information.</p>
+ </div>
+ <div class="section" title="GuacamoleHome"><div class="titlepage"><div><div><h3 class="title"><a id="idp1697744"></a><code class="classname">GuacamoleHome</code></h3></div></div></div>
+
+ <p>If you need more structured data than provided by simple
+ properties, placing XML or some other separate file within
+ <code class="varname">GUACAMOLE_HOME</code> (or a subdirectory
+ thereof) is a decent way to achieve this. The
+ <code class="classname">GuacamoleHome</code> class provides access
+ to the <code class="varname">GUACAMOLE_HOME</code> directory, abstracting
+ away the decision process that determines which directory is
+ considered <code class="varname">GUACAMOLE_HOME</code>.</p>
+ </div>
+ </div>
+ <div class="section" title="Authentication providers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="auth-providers"></a>Authentication providers</h2></div></div></div>
+
+ <p>The main use of guacamole-ext is to provide custom authentication
+ for Guacamole through the implementation of authentication
+ providers. An authentication provider is any class which implements
+ the <code class="classname">AuthenticationProvider</code> interface,
+ implementing the only function defined by that interface:
+ <code class="methodname">getUserContext()</code>. This function is
+ required to return a "context" which provides access to only those
+ users and configurations accessible with the given credentials, and
+ enforces its own security model.</p>
+ <p>The credentials given are abstract and while Guacamole the web
+ application implements a username/password driven login screen, you
+ are not required to user usernames and passwords; the
+ <code class="classname">Credentials</code> class given to the
+ authentication provider provides access to all HTTP parameters in
+ general, as well as cookies and SSL information.</p>
+ <p>The Guacamole web application includes a basic authentication
+ provider implementation which parses an XML file to determine which
+ users exist, their corresponding passwords, and what configurations
+ those users have access to. This is the part of Guacamole that reads
+ the <code class="filename">user-mapping.xml</code> file. If you use a custom
+ authentication provider for your authentication, this file will
+ probably not be required.</p>
+ <p>The community has implemented authentication providers which
+ access databases, use LDAP, or even perform no authentication at
+ all, redirecting all users to a single configuration specified in
+ <code class="filename">guacamole.properties</code>.</p>
+ <p>A minimal authentication provider is implemented in the tutorials
+ later, and the upstream authentication provider implemented within
+ Guacamole, as well as the authentication providers implemented by
+ the community, are good examples for how authentication can be
+ extended without having to implement a whole new web
+ application.</p>
+ <div class="section" title="SimpleAuthenticationProvider"><div class="titlepage"><div><div><h3 class="title"><a id="idp1709904"></a><code class="classname">SimpleAuthenticationProvider</code></h3></div></div></div>
+
+ <p>The <code class="classname">SimpleAuthenticationProvider</code> class
+ provides a much simpler means of implementing authentication
+ when you do not require the ability to add and remove users and
+ connections. It is an abstract class and requires only one
+ function implementation:
+ <code class="methodname">getAuthorizedConfigurations()</code>.</p>
+ <p>This function is required to return a
+ <code class="classname">Map</code> of unique IDs to configurations,
+ where these configurations are all configurations accessible
+ with the provided credentials. As before, the credentials given
+ are abstract. You are not required to use usernames and
+ passwords.</p>
+ <p>The configurations referred to by the function name are
+ instances of <code class="classname">GuacamoleConfiguration</code> (part
+ of guacamole-common), which is just a wrapper around a protocol
+ name and set of parameter name/value pairs. The name of the
+ protocol to use and a set of parameters is the minimum
+ information required for other parts of the Guacamole API to
+ complete the handshake required by the Guacamole
+ protocol.</p>
+ <p>When a class that extends
+ <code class="classname">SimpleAuthenticationProvider</code> is asked
+ for more advanced operations by the web application,
+ <code class="classname">SimpleAuthenticationProvider</code> simply
+ returns that there is no permission to do so. This effectively
+ disables all administrative functionality within the web
+ interface.</p>
+ <p>If you choose to go the simple route, most of the rest of this
+ chapter is irrelevant. Permissions, security model, and various
+ classes will be discussed that are all handled for you
+ automatically by
+ <code class="classname">SimpleAuthenticationProvider</code>.</p>
+ </div>
+ <div class="section" title="The UserContext"><div class="titlepage"><div><div><h3 class="title"><a id="idp1717856"></a>The <code class="classname">UserContext</code></h3></div></div></div>
+
+ <p>The <code class="classname">UserContext</code> is the root of all
+ operations. It is used to list, create, modify, or delete users
+ and connections, as well as to query available
+ permissions.</p>
+ <p>The Guacamole web application uses permissions queries against
+ the <code class="classname">UserContext</code> to determine what
+ operations to present, but <span class="emphasis"><em>beware that it is up to the
+ <code class="classname">UserContext</code> to actually enforce
+ these restrictions</em></span>. The Guacamole web application
+ will not enforce restrictions on behalf of the
+ <code class="classname">UserContext</code>.</p>
+ <p>The <code class="classname">UserContext</code> is the sole means of
+ entry and the sole means of modification available to a
+ logged-in user. If the <code class="classname">UserContext</code>
+ refuses to perform an operation (by throwing an exception), the
+ user cannot perform the operation at all.</p>
+ </div>
+ <div class="section" title="Directory classes"><div class="titlepage"><div><div><h3 class="title"><a id="idp1724304"></a><code class="classname">Directory</code> classes</h3></div></div></div>
+
+ <p>Access to users and connections is given through
+ <code class="classname">Directory</code> classes. These
+ <code class="classname">Directory</code> classes are similar to Java
+ collections, but they also embody object update semantics.
+ Objects can be retrieved from a <code class="classname">Directory</code>
+ using its <code class="methodname">get()</code> function and added or
+ removed with <code class="methodname">add()</code> and
+ <code class="methodname">remove()</code> respectively, but objects
+ already in the set can also be updated by passing an updated
+ object to its <code class="methodname">update()</code> function.</p>
+ <p>An implementation of a <code class="classname">Directory</code> can
+ rely on these functions to define the semantics surrounding all
+ operations. The <code class="methodname">add()</code> function is
+ called only when creating new objects, the
+ <code class="methodname">update()</code> function is called only
+ when updating an object previously retrieved with
+ <code class="methodname">get()</code>, and
+ <code class="methodname">remove()</code> is called only when
+ removing an existing object by its identifier.</p>
+ <p>When implementing an
+ <code class="classname">AuthenticationProvider</code>, you must
+ ensure that the <code class="classname">UserContext</code> will only
+ return <code class="classname">Directory</code> classes that
+ automatically enforce the permissions associated with all
+ objects and the associated user.</p>
+ </div>
+ <div class="section" title="Permissions"><div class="titlepage"><div><div><h3 class="title"><a id="idp1733904"></a>Permissions</h3></div></div></div>
+
+ <p>The permissions system within guacamole-ext is the means with
+ which an authentication module communicates with the web
+ application, informing it of what the user is allowed to do. The
+ presence or lack of permissions for certain operations dictates
+ how the web interface displays itself: whether the "Manage"
+ button is displayed, whether the user or connection management
+ sections (or both) are displayed, etc.</p>
+ <p><span class="emphasis"><em>Permissions are not the means through which access
+ is restricted</em></span>. An implementation may use the
+ permission objects to define restrictions, but this is not
+ required. It is up to the implementation to enforce its own
+ restrictions by throwing exceptions when an operation is not
+ allowed.</p>
+ <div class="section" title="System permissions"><div class="titlepage"><div><div><h4 class="title"><a id="idp1737152"></a>System permissions</h4></div></div></div>
+
+ <p>System permissions grant access to operations that
+ manipulate the system as a whole, rather than specific
+ objects. This includes the creation of new objects, as
+ object creation directly affects the system, and per-object
+ controls cannot exist before the object is actually
+ created.</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="type">ADMINISTER</span></span></dt><dd>
+ <p>Allows manipulation of system-level
+ permissions. The semantics of the system-level
+ <span class="type">ADMINISTER</span> permission are up to
+ the implementor of the authentication module,
+ but in general this permission implies all other
+ permissions. A user having this permission can
+ implicitly create and manage any object.</p>
+ </dd><dt><span class="term"><span class="type">CREATE_CONNECTION</span></span></dt><dd>
+ <p>Allows creation of new connections. If a user has this permission,
+ they will see the connection management interface and the "Manage"
+ button. Within this interface, they will be able to create new
+ connections.</p>
+ </dd><dt><span class="term"><span class="type">CREATE_CONNECTION_GROUP</span></span></dt><dd>
+ <p>Allows creation of new connections groups. If a user has this
+ permission, they will see the connection management interface and
+ the "Manage" button. Within this interface, they will be able to
+ create new connection groups.</p>
+ </dd><dt><span class="term"><span class="type">CREATE_USER</span></span></dt><dd>
+ <p>Allows creation of new users. If a user has
+ this permission, they will see the user
+ management interface and the "Manage"
+ button.</p>
+ </dd></dl></div>
+ </div>
+ <div class="section" title="User permissions"><div class="titlepage"><div><div><h4 class="title"><a id="idp1748224"></a>User permissions</h4></div></div></div>
+
+ <p>User permissions grant access to operations that affect a
+ specific user. Each user permission has a definite and
+ single associated user that is the object of the
+ operation.</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="type">ADMINISTER</span></span></dt><dd>
+ <p>Allows changing visibility of the user. A user
+ with <span class="type">ADMINISTER</span> permission on
+ another user can add and remove permissions
+ related to that user. Note that adding or
+ removing permissions on a user implicitly
+ requires <span class="type">UPDATE</span> permission on that
+ user.</p>
+ </dd><dt><span class="term"><span class="type">DELETE</span></span></dt><dd>
+ <p>Allows deletion of the associated user. This
+ is distinct from the <span class="type">ADMINISTER</span>
+ permission which deals only with modification to
+ the permissions associated with a user. A user
+ with this permission will see the "Delete"
+ button when editing the corresponding
+ user.</p>
+ </dd><dt><span class="term"><span class="type">READ</span></span></dt><dd>
+ <p>Allows the user to be read. A particular user
+ will not appear in the user management section
+ unless the user viewing it has <span class="type">READ</span>
+ permission on that specific user.</p>
+ </dd><dt><span class="term"><span class="type">UPDATE</span></span></dt><dd>
+ <p>Allows the user to be updated. This means altering the user's
+ password or adding or removing permissions from that user. Note the
+ difference between <span class="type">UPDATE</span> and <span class="type">ADMINISTER</span>:
+ the <span class="type">UPDATE</span> permission allows the permissions
+ <span class="emphasis"><em>of</em></span> a user to be changed, while
+ <span class="type">ADMINISTER</span> permission allows permissions
+ <span class="emphasis"><em>relating to</em></span> a user to be changed. A user
+ with this permission will see the "Manage" button.</p>
+ </dd></dl></div>
+ </div>
+ <div class="section" title="Connection permissions"><div class="titlepage"><div><div><h4 class="title"><a id="idp1765520"></a>Connection permissions</h4></div></div></div>
+
+ <p>Connection permissions grant access to operations that
+ affect a specific connection. Each connection permission has
+ a definite and single associated connection that is the
+ object of the operation. The semantics of each operation
+ differ slightly from the similar user permissions, but the
+ general principles behind them are the same.</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="type">ADMINISTER</span></span></dt><dd>
+ <p>Allows changing visibility of the connection. A user with
+ <span class="type">ADMINISTER</span> permission on a connection can add and
+ remove permissions related to that connection, and will see the
+ "Manage" button.</p>
+ </dd><dt><span class="term"><span class="type">DELETE</span></span></dt><dd>
+ <p>Allows deletion of the associated connection.
+ This is distinct from the
+ <span class="type">ADMINISTER</span> permission which
+ deals only with modification to the permissions
+ associated with a connection. A user with this
+ permission will see the "Delete" button when
+ editing the corresponding connection.</p>
+ </dd><dt><span class="term"><span class="type">READ</span></span></dt><dd>
+ <p>Allows the connection to be read. A particular connection will not
+ appear in the connection list nor in the connection management
+ section unless the user viewing it has <span class="type">READ</span> permission
+ on that specific connection. <span class="type">READ</span> permission is
+ required for a user to have permission to actually use a connection,
+ unless that connection is part of a balancing connection group for
+ which the user has <span class="type">READ</span> permission.</p>
+ </dd><dt><span class="term"><span class="type">UPDATE</span></span></dt><dd>
+ <p>Allows the connection to be updated. This means editing the
+ connection's parameters or changing the connection's protocol. A
+ user with this permission will see the "Manage" button.</p>
+ </dd></dl></div>
+ </div>
+ <div class="section" title="Connection group permissions"><div class="titlepage"><div><div><h4 class="title"><a id="idp1778912"></a>Connection group permissions</h4></div></div></div>
+
+ <p>Connection group permissions grant access to operations that affect a specific
+ connection group. Connection group permissions are extremely similar to
+ connection permissions, with some minor differences.</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="type">ADMINISTER</span></span></dt><dd>
+ <p>Allows changing visibility of the connection group. A user with
+ <span class="type">ADMINISTER</span> permission on a connection group can add
+ and remove permissions related to that connection group, and will
+ see the "Manage" button. Users with <span class="type">ADMINISTER</span>
+ permission on a balancing connection group can see the contents of
+ that group. To users without <span class="type">ADMINISTER</span> permission, a
+ balancing group looks like a connection.</p>
+ </dd><dt><span class="term"><span class="type">DELETE</span></span></dt><dd>
+ <p>Allows deletion of the associated connection group. This is
+ distinct from the <span class="type">ADMINISTER</span> permission which deals
+ only with modification to the permissions associated with a
+ connection group. A user with this permission will see the "Delete"
+ button when editing the corresponding connection group.</p>
+ </dd><dt><span class="term"><span class="type">READ</span></span></dt><dd>
+ <p>Allows the connection group to be read. A particular connection
+ group will not appear in the connection list nor in the connection
+ management section unless the user viewing it has <span class="type">READ</span>
+ permission on that specific connection group. <span class="type">READ</span>
+ permission is required for a user to have permission to actually use
+ a connection.</p>
+ <p>A user with <span class="type">READ</span> permission on a group will also be
+ able to see any contained connections or groups for which they also
+ have <span class="type">READ</span> permission. <span class="type">READ</span> permission is
+ not sufficient to see the contents of a balancing group.</p>
+ </dd><dt><span class="term"><span class="type">UPDATE</span></span></dt><dd>
+ <p>Allows the connection group to be updated. This means editing the
+ connection group's name, type, or contents. A user with this
+ permission will see the "Manage" button.</p>
+ </dd></dl></div>
+ </div>
+ </div>
+ <div class="section" title="Connections and history"><div class="titlepage"><div><div><h3 class="title"><a id="idp1795776"></a>Connections and history</h3></div></div></div>
+
+ <p>Authentication modules must return <code class="classname">Connection</code> objects which
+ each implement a <code class="methodname">connect()</code> function. When this function is
+ called, the connection must be made if permission is available.</p>
+ <p>This new separation of concerns makes more sense when you
+ consider that as connecting is an operation on a
+ <code class="classname">Connection</code>, access to performing that
+ operation must be restricted through the
+ <code class="classname">AuthenticationProvider</code>, and thus must
+ be enforced within the
+ <code class="classname">AuthenticationProvider</code>. This
+ separation also opens the door for things like load balancing of
+ connections and restricting concurrent access to
+ connections.</p>
+ <p>When a connection is made or terminated, it is also the duty
+ of the authentication module to maintain the connection history.
+ Each connection has a corresponding list of
+ <code class="classname">ConnectionRecord</code> objects, each of
+ which is associated with a past connection or a currently-active
+ connection. This information will ultimately be exposed to the
+ user as a history list when they view a connection in the
+ management interface or as a simple active user count on the
+ connection, advising the user of existing activity.</p>
+ </div>
+ </div>
+ <div class="section" title="Event listeners"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="event-listeners"></a>Event listeners</h2></div></div></div>
+
+ <p>Although not used internally by the web application, the web
+ application provides an event system which can be hooked into with
+ listener objects, such that a class within the classpath of
+ Guacamole can receive events when something noteworthy happens in
+ the application layer, and take some sort of action.</p>
+ <p>Currently, the web application provides events for when the tunnel
+ is opened or closed, and when an authentication attempt succeeds or
+ fails. In most cases, the class listening for these events can also
+ cancel whatever action just occurred.</p>
+ <div class="section" title="TunnelConnectListener"><div class="titlepage"><div><div><h3 class="title"><a id="tunnel-connect-listener"></a><code class="classname">TunnelConnectListener</code></h3></div></div></div>
+
+ <p>When a tunnel is connected to by the JavaScript client,
+ Guacamole informs all installed instances of
+ <code class="classname">TunnelConnectListener</code> by calling
+ their <code class="methodname">tunnelConnected()</code> function with a
+ new <code class="classname">TunnelConnectEvent</code>, which contains
+ the tunnel that was just connected, as well as any associated
+ credentials. If <code class="methodname">tunnelConnected()</code>
+ returns <code class="constant">false</code>, the connect attempt will be
+ overridden and denied.</p>
+ </div>
+ <div class="section" title="TunnelCloseListener"><div class="titlepage"><div><div><h3 class="title"><a id="tunnel-close-listener"></a><code class="classname">TunnelCloseListener</code></h3></div></div></div>
+
+ <p>When a tunnel is connected to by the JavaScript client,
+ Guacamole informs all installed instances of
+ <code class="classname">TunnelCloseListener</code> by calling their
+ <code class="methodname">tunnelClosed()</code> function with a new
+ <code class="classname">TunnelCloseEvent</code>, which contains the
+ tunnel that is about to be closed, as well as any associated
+ credentials. If <code class="methodname">tunnelClosed()</code> returns
+ <code class="constant">false</code>, the attempt close the tunnel
+ will be overridden and denied, and the tunnel will remain
+ open.</p>
+ </div>
+ <div class="section" title="AuthenticationSuccessListener"><div class="titlepage"><div><div><h3 class="title"><a id="authentication-success-listener"></a><code class="classname">AuthenticationSuccessListener</code></h3></div></div></div>
+
+ <p>If a user successfully authenticates with the web application,
+ Guacamole informs all installed instances of
+ <code class="classname">AuthenticationSuccessListener</code> by
+ calling their <code class="methodname">authenticationSucceeded()</code>
+ function with a new
+ <code class="classname">AuthenticationSuccessEvent</code> which
+ contains the credentials used. The implementation of this
+ function has the opportunity to cancel the authentication
+ attempt, effectively denying access despite being otherwise
+ valid, by returning <code class="constant">false</code>.</p>
+ </div>
+ <div class="section" title="AuthenticationFailureListener"><div class="titlepage"><div><div><h3 class="title"><a id="authentication-failure-listener"></a><code class="classname">AuthenticationFailureListener</code></h3></div></div></div>
+
+ <p>If a user fails to authenticate with the web application,
+ Guacamole informs all installed instances of
+ <code class="classname">AuthenticationFailureListener</code> by
+ calling their <code class="methodname">authenticationFailed()</code>
+ function with a new
+ <code class="classname">AuthenticationFailureEvent</code> which
+ contains the credentials used. Unlike other listeners, this
+ event cannot be canceled by returning
+ <code class="constant">false</code>. All failed authentication attempts
+ "succeed" in failing, and an implementation of
+ <code class="classname">AuthenticationFailureListener</code> cannot
+ force an authentication attempt to succeed by denying that
+ failure.</p>
+ </div>
+ </div>
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="guacamole-common-js.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="custom-protocols.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�12.�guacamole-common-js�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�14.�Adding new protocols</td></tr></table></div>
+
+ </div></div>
+
+
+<!-- Google Analytics -->
+<script type="text/javascript">
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-75289145-1', 'auto');
+ ga('send', 'pageview');
+
+</script>
+<!-- End Google Analytics -->
+ </body></html>