[GNUnet-SVN] r32899 - gnunet-java/doc

[gnunet]

Author: dold
Date: 2014-04-07 03:14:28 +0200 (Mon, 07 Apr 2014)
New Revision: 32899

Modified:
   gnunet-java/doc/gnunet-java-tutorial.pdf
   gnunet-java/doc/gnunet-java-tutorial.tex
Log:
tutorial work in progress

Modified: gnunet-java/doc/gnunet-java-tutorial.pdf
===================================================================
(Binary files differ)

Modified: gnunet-java/doc/gnunet-java-tutorial.tex
===================================================================
--- gnunet-java/doc/gnunet-java-tutorial.tex    2014-04-07 00:26:06 UTC (rev 
32898)
+++ gnunet-java/doc/gnunet-java-tutorial.tex    2014-04-07 01:14:28 UTC (rev 
32899)
@@ -59,13 +59,13 @@
 the template extension project,  which already contains a build system
 and sample code.
 
-Obtain the extension template from the SVN repository:
+Obtain the extension template from the subversion repository:
 \begin{lstlisting}[language=bash,deletekeywords={export}]
 \$ svn export https://gnunet.org/svn/gnunet-java-ext/ my-extension
 \$ cd my-extension
 \end{lstlisting}
 
-The template project uses Gradle\footnote{\url{http://gradle.org}} as the 
build system.  Simply use the \texttt{./gradlew}
+The template project uses Gradle\footnote{\url{http://gradle.org}} as a build 
system.  Simply use the \texttt{./gradlew}
 script to run build tasks.  The wrapper script will automatically download the 
correct version
 of Gradle on the first run.  Alternatively, download Gradle$\ge$1.11 yourself, 
and use the \texttt{gradle} command
 directly instead of the wrapper.
@@ -106,10 +106,10 @@
 
 Calling {\tt start} initializes GNUnet-Java, parses the command line,
 loads configuration files and starts the task scheduler, with the code
-in the {\tt run} method as initial task.
+in the {\tt run} method executed in the initial task.
 
 \exercise{%
-  Try to get the code above running by placing it in a \texttt{*.java} file
+  Get the code above to execute by placing it in a \texttt{*.java} file
   in \texttt{src/main/java/}, running the \texttt{assemble} task from Gradle,
   and invoking \texttt{java} with the right parameters.
 }
@@ -136,9 +136,9 @@
 line, either by the long name with two dashes ({\tt --name=Foo} / {\tt
   --name FOO}) or the short name ({\tt -n FOO}) with one dash.
 
-Inside of the {\tt run} method, the field {\tt name} will then be
-initialized with the given argument, or {\tt null} if the option has
-not been specified on the command line.
+Before the \texttt{run} method is called, the field {\tt name} will
+be set to the given argument.  If the \texttt{name} option is missing,
+the field will keep the value specified in the constructor or the field's 
initializer.
 
 The address@hidden annotation can not only be used with Strings, but also
 with booleans and numbers. These are a few of the available options:
@@ -167,14 +167,15 @@
 
 \subsection{Shell Wrappers}
 It is usually more convenient to have a shell wrapper for each entry point than
-it is to pass the main class and classpath to the JVM manually every time.  
The shell wrappers
-in the \texttt{bin/} directory of the template use a classpath relative to 
their location.
-Thus they only work if in the right location.
+it is to pass the main class and classpath to the JVM manually every time.  The
+shell wrappers in the \texttt{bin/} directory of the template set the JVM
+classpath classpath relative to the location of the script file.  The shell 
wrappers
+should therefore always be kept in the \texttt{bin/} directory.
 
-\exercise{Copy the wrapper \textt{bin/my-ext} and modify it so that
+\exercise{Copy the wrapper \texttt{bin/my-ext} and modify it so that
 calls your \texttt{HelloGnuNet} class.}
 
-\subsection{Documentation}
+\subsection{More Documentation}
 The documentation for \emph{gnunet-java} generated by Javadoc is available
 at \url{https://gnunet.org/javadoc/}.
 
@@ -201,16 +202,19 @@
 returns, and GNUnet-Java keeps the system running until all work is done.
 
 Always remember that you always explicitly have to destroy your {\tt
-  Statistics} instance with the {\tt destroy()}
+  Statistics} instance by calling its {\tt destroy()}
 method. Otherwise there might be pending operations that prevent the
 termination of your program.
 
 \subsection{Setting statistics}
 
-You can use the newly created {\tt statistics} handle like this to set a value:
+You can use the newly created {\tt statistics} handle to, for instance,
+set the value named ``\# bytes sent'' to the value 42. The \texttt{true}
+indicates that the value should be stored persistently.
+Persistent values are kept even if the statistics service restarts.
 
 \begin{lstlisting}[language=java]
-statistics.set("gnunet-java-hello", "the answer", 42);
+statistics.set("gnunet-java-hello", "# bytes sent", 42, true);
 \end{lstlisting}
 
 \subsection{Retrieving statistics}
@@ -239,7 +243,8 @@
 \end{lstlisting}
 
 \exercise{Write a program that sets statistics values, and check the result 
with the {\tt gnunet-statistics} command line tool.}
-\exercise{Write a program to read and print statistics values.}
+\exercise{Read the Javadoc of the statistics service.  What other operations 
can be done on statistics values, other
+than reading and writing them?}
 
 
 \section{The core API}
@@ -297,7 +302,8 @@
 
 \exercise{Define a message that contains a 32-bit signed integer.}
 \exercise{%
-  Look at the class {\tt  org.gnunet.dht.MonitorPutMessage} in the GNUnet-Java 
source code.
+  Look at the class {\tt  org.gnunet.dht.messages.MonitorPutMessage} in the 
GNUnet-Java source
+  code\footnote{\url{https://gnunet.org/svn/gnunet-java/}}.
   This message uses a variety of different annotations, try to understand the 
purpose
   of each member's annotation.
 }
@@ -351,16 +357,19 @@
     public transmit(Connection.MessageSink sink) {
         sink.transmit(myMessage);
     }
-    public onError() {
+    public handleError() {
         // do something
     }
 \end{lstlisting}
 
 You can use {\tt Construct.getSize} to calculate the size of a
-message, or just do it manually.
+message, or compute it manually.
 
 \exercise{Write an echo program for core: Send a message to the local peer and 
receive it!}
 
+\section{The Distributed Hash Table (DHT) API}
+
+
 \section{Other useful APIs}
 Some other useful service APIs currently implemented are NSE (in {\tt
   org.gnunet.nse.NetworkSizeEstimation}), a service that gives an
@@ -447,7 +456,10 @@
   another message type.}
 \exercise{Write an API for a GNUnet service that has not been implemented yet 
in gnunet-java and contribute it back to the project.}
 
+\section{MESH}
+TODO
 
+
 \section{The state of GNUnet-Java}
 
 The GNUnet-Java project is still somewhat unstable and under development, 
expect