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

[gnunet]

Author: dold
Date: 2012-04-22 20:09:40 +0200 (Sun, 22 Apr 2012)
New Revision: 21072

Added:
   gnunet-java/doc/gnunet-java-tutorial.tex
Log:
updated the tutorial (still not done)


Added: gnunet-java/doc/gnunet-java-tutorial.tex
===================================================================
--- gnunet-java/doc/gnunet-java-tutorial.tex                            (rev 0)
+++ gnunet-java/doc/gnunet-java-tutorial.tex    2012-04-22 18:09:40 UTC (rev 
21072)
@@ -0,0 +1,238 @@
+\documentclass[10pt]{article}
+\usepackage[ansinew]{inputenc}
+\usepackage{makeidx,amsmath,amssymb,exscale,multicol,epsfig,graphics,verbatim,ulem}
+\usepackage{epsfig,geometry,url,listings}
+\geometry{headsep=3ex,hscale=0.9}
+\usepackage{hyperref}
+\hypersetup{
+  pdftitle={gnunet-java tutorial},
+  pdfsubject={gnunet-java},
+  pdfauthor={Florian Dold <address@hidden>},
+  pdfkeywords={gnunet,java},
+  colorlinks=true, % otherwise the boxes overlap content
+  urlcolor=blue
+}
+
+\title{Tutorial: gnunet-java}
+%\author{Florian Dold\\
+%    address@hidden
+%}
+\date{}
+
+\begin{document}
+
+\maketitle
+
+\lstset{language=bash}
+
+\section{Getting Started}
+\subsection{Installing gnunet}
+This tutorial assumes that you have gnunet$\geq$0.9.2 installed on your 
system. Instructions on how to do this can be found at 
\url{https://gnunet.org/installation}.
+Make sure that you run {\tt configure} with the option {\tt 
--enable-javaports}.
+Start gnunet with the command {\tt gnunet-arm -s}. Convince yourself that the 
default gnunet services are running by typing {\tt gnunet-arm -I}.
+
+\subsection{Installing gnunet-java}
+Check out the latest version of gnunet-java with subversion: \\*
+{\tt svn checkout https://gnunet.org/svn/gnunet-java/} \\*
+Tools for gnunet-java development are located in {\tt tools/}, while the {\tt 
bin/} directory contains
+shell wrappers for java programs using gnunet. Now run the command
+{\tt ./tools/build} to compile {\tt gnunet-java}.
+
+To test whether your gnunet-java installation is working, try to run the 
"gnunet-nse" program (in {\tt bin},
+which should display the current estimated size of the network.
+
+Throughout the tutorial it will be useful to consult the javadocs for 
gnunet-java, either built them yourself with {\tt ./tools/make-javadoc} or use 
the online version at \url{https://gnunet.org/javadoc/}
+
+\section{Creating an extension}
+
+Check out the template directory for gnunet-java extensions with the following 
command: \\*
+{\tt svn checkout https://gnunet.org/svn/gnunet-java-ext/ }
+
+Now edit the file envcfg.sh. This file contains the necessary information so 
that scripts in the
+gnunet-java-ext/tools directory, as well as the shell-wrappers in 
gnunet-java-ext/bin can find your gnunet-java installation. Not that the 
template directory already contains an example extension that will print a 
"hello world" message, we will ignore this in the next section and write our 
own.
+
+
+\section{A simple gnunet-java program}
+\subsection{The Basics}
+\begin{lstlisting}[language=java]
+public class HelloGnunet {
+    public static void main(String[] args) {
+            new Program(args) {
+                public void run() {
+                    System.out.println("Hello, gnunet");
+                }
+            }.start();
+}
+\end{lstlisting}
+
+The Program class takes care of parsing command line arguments (thus it's 
constructur gets the args array passed)
+and loading the gnunet configuration files (accessed by 
Program.getConfiguration())
+(talk about scheduler/asynchronous stuff)
+
+{\bf Exercise:} Try to get the code above running. Place your code in the {\tt 
src/} directory (so that you can use the build script in {\tt tools}, copy and 
modify the example shell-wrapper {\tt bin/gnunet-ext} until you can
+run your own program with it.
+
+\bigskip
+
+\subsection{Adding and using command line arguments}
+Command line options are added by annotating members of your 
org.gnunet.util.Program-subclass
+with the address@hidden
+
+Let's start with an example:
+
+\lstset{language=java}
+\begin{lstlisting}
+new Program(args) {
+    @Option(
+        shortname = "n",
+        longname = "name",
+        action = OptionAction.STORE_STRING,
+        description = "the name of the person you want to greet")
+    String name;
+[...]
+}
+\end{lstlisting}
+
+You can now specify value for the member {\tt name} at the command 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 run-method, the class member 'name' will then be initialized 
with the passed argument,
+or null if the option has not been passed.
+
+The address@hidden annotation can not only be used with Strings, but also with 
booleans and numbers. The following types of actions are available:
+\begin{itemize}
+\item {\tt STORE\_STRING}: Store a string in a {\tt String} variable
+\end{itemize}
+By default, the following arguments are available on the command line:
+\begin{itemize}
+\item {\tt -h} / {\tt --help} shows the help text
+\item {\tt -v} / {\tt --version} shows version information
+\item {\tt -}
+\end{itemize}
+
+You can change the about text and the version by subclassing the getVersion / 
getAboutTest methods in your Program subclass.
+
+\subsection{Using an existing service API}
+In this section we will use the statistics-API of gnunet-java. This service 
allows us to store numbers under a subsystem and a name, which are still 
available to you and other components of your peer if your program quits.
+\subsubsection{Establishing a connection with the statistics service}
+
+\begin{lstlisting}[language=java]
+Statistics statistics = new Statistics(getConfiguration());
+\end{lstlisting}
+
+The Statistics constructor is called with the default configuration, provided 
by the method {\tt getConfiguration}
+of the {\tt Program} class. Calling the constructor establishes a connection 
to the statistics service.
+As with most API calls in gnunet-java, this operation is asynchronous. This is 
one of the main reasons why you have to wrap your program in the overridden 
{\tt run} method of {\tt Program}: Once all your asynchronous calls are
+made, the run method returns, and gnunet-java keeps the system running until 
all work has been done.
+
+Always remember that you always explicitly have to destroy your {\tt Service} 
instance with the
+{\tt destroy(boolean sync)} method. Otherwise there might be pending 
operations that prevent
+the termination of your program. The parameter of {\tt destroy} determines 
whether pending
+set-requests to the statistics service should be satisfied or dropped.
+
+You can use the newly created {\tt statistics} handle like this to set a value:
+
+\begin{lstlisting}[language=java]
+statistics.set("gnunet-java-hello", "the answer", 42);
+\end{lstlisting}
+
+Retrieving a value is a little bit more complex. Because of the asynchronous 
nature of the gnunet-java APIs,
+the {\tt startGet} method does not directly return values, but a handle 
(implementing the interface
+{\tt Cancelable} to cancel the get request. The actual values are accessed by 
passing a callback object to the
+{\tt startGet} method.
+
+Example:
+
+\begin{lstlisting}[language=java]
+// the name parameter is the empty string, this gets all options of the 
specified subsystem
+Cancelable getCancel = statistics.get(RelativeTime.SECOND, 
"gnunet-java-hello", "", new Statistics.StatisticsReceiver {
+    public void onDone() {
+        System.out.println("everything done");
+    }
+    public void onReceive(String subsystem, String name, long val) {
+        System.out.println(subsyste + " " + name + " " + val);
+    }
+    public void onTimeout() {
+        System.out.println("timeout occured");
+    }
+});
+\end{lstlisting}
+
+
+{\bf Exercise:} Write a program that takes a name from the command line. Greet 
that name, and count / print out how many times your program has greeted 
somebody before. {\it Tip:} You can use the gnunet-statistics command line 
program to view and
+modify values from the statistics service.
+
+\bigskip
+
+\section {Overview of useful APIs}
+statistics
+
+dht
+* explain dht-put and dht-get / one example
+
+core
+* explain API, maybe refer to example code
+
+
+\section{Creating a new gnunet-java service}
+
+\subsection{Defining new Messages}
+All gnunet services have a common communication protocol.
+Every message consists of a header (with the message size and the message 
type), and a body.
+
+You can define a new type of Message in gnunet-java by annotating a class with 
how
+to represent its members in binary format.
+
+Additionaly, you have to register your new message type with gnunet-java, 
giving it a unique id.
+
+\begin{lstlisting}
address@hidden(4242)
+public class HelloWorldMessage implements GnunetMessage.Body {
+    @UInt8
+    public int age;
+    @ZeroTerminatedString;
+    public String name;
+}
+\end{lstlisting}
+Todo: explain the above
+
+
+Other useful annotations are:
+...
+
+
+Running the msgtypes-tool:
+
+\subsection{Implementing the Service}
+Similarily to Program.run, Service.run is the entry point of every gnunet-java 
service.
+It's members can be annotated with the same command line parsing options as in 
Program.
+
+The first difference is that every Service has at least one server, waiting on 
new clients to connect.
+When implementing a Service, you have to specify the kind of messages you are 
interested in.
+
+The basic skeleton for a Service looks like this:
+
+\subsubsection{Talking back to a client}
+explain Client.this.notifyTransmitReady(...)
+
+\subsection{Creating the configuration file}
+For every service ther is a configuration file that specifies
+over which port the service is reachable. Other options in the configuration 
can be used to
+configure the service without touching the code or implementing your own 
configuration.
+
+[provide example config file here]
+
+\subsection{Using arm to start the service}
+
+\section{Communicating with a Service directly}
+\subsection{Using the client API}
+\subsubsection{Creating a new Client}
+\begin{lstlisting}
+Client = new Client("hello-world-service", getConfiguration());
+\end{lstlisting}
+establishes a connection with the service named "hello-world-service". The 
necessary information (e.g. the right TCP/IP port) for connecting
+to the service is is looked up under the section [hello-world-service] in the 
configuration.
+
+
+
+\end{document}