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 <[email protected]> Authored: Wed Dec 16 12:51:18 2015 -0800 Committer: Michael Jumper <[email protected]> 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>
