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/03/20 03:15:35 UTC
[25/50] incubator-guacamole-manual git commit: GUAC-1436: Remove
inaccurate documentation covering deprecated GuacamoleProperties class.
GUAC-1436: Remove inaccurate documentation covering deprecated GuacamoleProperties class.
Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/commit/636dccdb
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/636dccdb
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/636dccdb
Branch: refs/heads/master
Commit: 636dccdb9db80a0079710f6348c3a6c91f1b93d2
Parents: 9f677b8
Author: Michael Jumper <mi...@guac-dev.org>
Authored: Wed Dec 16 12:51:18 2015 -0800
Committer: Michael Jumper <mi...@guac-dev.org>
Committed: Wed Dec 16 12:51:18 2015 -0800
----------------------------------------------------------------------
src/chapters/guacamole-common.xml | 93 +++-------------------------------
1 file changed, 6 insertions(+), 87 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/636dccdb/src/chapters/guacamole-common.xml
----------------------------------------------------------------------
diff --git a/src/chapters/guacamole-common.xml b/src/chapters/guacamole-common.xml
index 91e0c18..ee362d6 100644
--- a/src/chapters/guacamole-common.xml
+++ b/src/chapters/guacamole-common.xml
@@ -10,14 +10,12 @@
<indexterm>
<primary><package>guacamole-common</package></primary>
</indexterm>
- <para>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
- <filename>guacamole.properties</filename> easier, but in general,
- the purpose of this library is to facilitate the creation of custom
- tunnels between the JavaScript client and guacd.</para>
+ <para>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, and for dealing with the Guacamole protocol. The purpose
+ of this library is to facilitate the creation of custom tunnels between the JavaScript
+ client and guacd, allowing your Guacamole-driven web application to enforce its own security
+ model, if any, and dictate exactly what connections are established.</para>
<section xml:id="java-http-tunnel">
<title>HTTP tunnel</title>
<para>The Guacamole Java API implements the HTTP tunnel using a servlet
@@ -161,83 +159,4 @@
sufficient.</para>
</section>
</section>
- <section xml:id="reading-properties">
- <title>Reading properties</title>
- <para>The Guacamole Java API provides simple access to
- <filename>guacamole.properties</filename> for convenience,
- although such support is not strictly required. This support is
- provided through the <classname>GuacamoleProperies</classname>
- utility class, which cannot be instantiated and provides two simple
- property retrieval functions: <methodname>getProperty()</methodname>
- and <methodname>getRequiredProperty()</methodname>, the difference
- being that the former can return <constant>null</constant> 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.</para>
- <para>In Guacamole, each property is declared as an implementation of
- <classname>GuacamoleProperty</classname>, and must provide an
- implementation of <methodname>getName()</methodname>, which returns
- the name of the property as it should exist within
- <filename>guacamole.properties</filename>, and
- <methodname>parseValue()</methodname>, which is given the
- <classname>String</classname> value of the property as read from
- <filename>guacamole.properties</filename>, and must return the
- declared type of the <classname>GuacamoleProperty</classname>
- implementation. A good example of how this works is the
- <classname>IntegerGuacamoleProperty</classname> implementation
- included within guacamole-common:</para>
- <informalexample>
- <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);
- }
-
- }
-
-}</programlisting>
- </informalexample>
- <para>Notice that this implementation does not actually provide
- <methodname>getName()</methodname>. Instead, it only implements
- <methodname>parseValue()</methodname>, the intent being to make
- other developers' lives easier when they need to retrieve an integer
- property from <filename>guacamole.properties</filename>. Using this
- class, retrieving an integer property is simple:</para>
- <informalexample>
- <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);</programlisting>
- </informalexample>
- <para>guacamole-common provides a couple of similar classes for
- retrieving common types of properties, such as a
- <classname>String</classname> or <classname>File</classname>,
- and implementing your own to facilitate properties that parse into
- arrays or a <classname>List</classname>, etc. should be reasonably
- simple.</para>
- </section>
</chapter>