gnunet-svn
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: gnunet
Subject: [GNUnet-SVN] r21096 - gnunet-java/doc
Date: Mon, 23 Apr 2012 09:25:46 +0200

Author: grothoff
Date: 2012-04-23 09:25:45 +0200 (Mon, 23 Apr 2012)
New Revision: 21096

Modified:
   gnunet-java/doc/gnunet-java-tutorial.tex
Log:
-formatting

Modified: gnunet-java/doc/gnunet-java-tutorial.tex
===================================================================
--- gnunet-java/doc/gnunet-java-tutorial.tex    2012-04-23 07:03:35 UTC (rev 
21095)
+++ gnunet-java/doc/gnunet-java-tutorial.tex    2012-04-23 07:25:45 UTC (rev 
21096)
@@ -13,11 +13,12 @@
   urlcolor=blue
 }
 
-\title{Tutorial: gnunet-java}
-%\author{Florian Dold\\
-%    address@hidden
-%}
+\newcommand{\exercise}[1]{\noindent\begin{boxedminipage}{\textwidth}{\bf 
Exercise:} #1 \end{boxedminipage}}
 
+\title{A Tutorial for GNUnet 0.9.x (Java version)}
+
+\author{Florian Dold}
+
 \begin{document}
 
 \maketitle
@@ -25,23 +26,43 @@
 \lstset{language=bash}
 
 \section{Getting Started}
-\subsection{Installing gnunet}
-This tutorial assumes that you have gnunet$\geq$0.9.3 installed on your 
system. Instructions on how to do this can be found at 
\url{https://gnunet.org/installation}.
+\subsection{Installing GNUnet}
+This tutorial assumes that you have GNUnet $\geq$ 0.9.3 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} and convince yourself that 
the default gnunet services are running by typing {\tt gnunet-arm -I}.
+Start GNUnet with the command {\tt gnunet-arm -s} and 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 interfacing with gnunet. Now run the command
-{\tt ./tools/build} to compile {\tt gnunet-java}.
+Check out the latest version of gnunet-java with subversion:
+\lstset{language=bash}
+\begin{lstlisting}
+$ svn checkout https://gnunet.org/svn/gnunet-java/
+\end{lstlisting}
+% $
+Tools for gnunet-java development are located in {\tt tools/}, while
+the {\tt bin/} directory contains shell wrappers for java programs
+interfacing with GNUnet. Now run the command 
 
-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).
+\lstset{language=bash}
+\begin{lstlisting}
+$ ./tools/build
+\end{lstlisting}
+% $
 
-Throughout the tutorial it will be useful to consult the javadocs for 
gnunet-java,
-either built them yourself with \\* {\tt ./tools/make-javadoc}
+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
+
+\lstset{language=bash}
+\begin{lstlisting}
+$ ./tools/make-javadoc
+\end{lstlisting}
+% $
+
 or use the online version at \url{https://gnunet.org/javadoc/}
 
 \section{Creating an extension}
@@ -49,38 +70,52 @@
 
 
 \section{A simple gnunet-java program}
+
 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 {\tt envcfg}. This file contains the necessary information so that 
scripts in the
-{\tt gnunet-java-ext/tools directory}, as well as the shell-wrappers in {\tt 
gnunet-java-ext/bin} can find your gnunet-java installation. Not that the 
template directory already contains an executable example extension that will 
print a "hello world" message, in this section you will learn how to write your 
own.
+\lstset{language=bash}
+\begin{lstlisting}
+$ svn checkout https://gnunet.org/svn/gnunet-java-ext/
+\end{lstlisting}
+% $
 
+Now edit {\tt envcfg}. This file contains the necessary information so
+that scripts in the {\tt gnunet-java-ext/tools directory}, as well as
+the shell-wrappers in {\tt gnunet-java-ext/bin} can find your
+gnunet-java installation. Note that the template directory already
+contains an executable example extension that will print a "hello
+world" message, in this section you will learn how to write your own.
+
 \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");
+                    System.out.println("Hello, GNUnet");
                 }
             }.start();
 }
 \end{lstlisting}
 
-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. 
+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.
 
-\bigskip
-{\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
+\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.}
 
+
 \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:
+Command line options are added by annotating members of your
+{\tt org.gnunet.util.Program} subclass with the address@hidden
 
+Here is a simple example:
+
 \lstset{language=java}
 \begin{lstlisting}
 new Program(args) {
@@ -94,20 +129,25 @@
 }
 \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.
+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.
+Inside of the {\tt run} method, the field {\tt name} will then be
+initialized with the passed argument, or {\tt 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. These are a few
-of the available options:
+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:
+
 \begin{itemize}
 \item {\tt STORE\_STRING}: Store a string in a {\tt String} variable
 \item {\tt STORE\_NUMBER}: Store a number in a member of primitive type
-\item {\tt SET}: Set a boolean to true
+\item {\tt SET}: Set a {\tt boolean} to {\tt true}
 \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
@@ -116,30 +156,45 @@
 \item {\tt -l} / {\tt --logfile} specify a file to write the logs to
 \end{itemize}
 
-You can change the about text and the version information by overriding the 
{\tt getVersion} / 
-{\tt getAboutTest} methods in your Program subclass.
+You can change the about text and the version information by
+overriding the {\tt getVersion} or {\tt getAboutTest} methods in your
+{\tt Program} subclass.
 
-\bigskip
-{\bf Exercise:} Add a few different command line options to your program and 
print them to {\tt System.out}!
-\bigskip
+\exercise{Add a few different command line options to your program and print 
them to {\tt System.out}!}
 
+
 \section{The statistics 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.
+
+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 after
+your program exits.
+
+
 \subsection{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.
+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 
Statistics} 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.
+Always remember that you always explicitly have to destroy your {\tt
+  Statistics} 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.\footnote{This argument is about to be removed in
+the C version and will likely be removed soon.  So don't worry about it,
+just passing {\tt true} will do.}
 
 
 \subsection{Setting statistics}
@@ -152,10 +207,12 @@
 
 \subsection{Retrieving statistics}
 
-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.
+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:
 
@@ -175,26 +232,27 @@
 });
 \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.}
 
-\bigskip
-\noindent
-{\bf Exercise:} Write a program that sets statistics values, and check the 
result with the {\tt gnunet-statistics} command line tool.
-\noindent
-{\bf Exercise:} Now the other way around: Write a program to read statistics 
values.
 
-\bigskip
+\section{The core API}
 
-\section{The core API}
 The core API allows sending messages to other connected peers.
 
 \subsection{Defining new Messages}
-All gnunet messages follow 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 nessage in gnunet-java by annotating a class with 
how to represent its members in binary format.
+All GNUnet messages follow a common communication protocol.  Every
+message consists of a header (with the message size and the message
+type) and a body.
 
-Additionaly, you have to register your new message type with gnunet-java, 
giving it a unique id. Here's an example:
-\begin{lstlisting}
+You can define a new type of nessage 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.  Here is an example:
+
+\begin{lstlisting}[language=java]
 @UnionCase(4242)
 public class ExampleMessage implements GnunetMessage.Body {
     @UInt8
@@ -204,58 +262,76 @@
 }
 \end{lstlisting}
 
-The {\tt @UnionCase} annotation specifies the message id of the message body 
below (4242 in the example). That is, GnunetMessage.Body
-actually is a union of messages, and ExampleMessage just one member of the 
union.
+The {\tt @UnionCase} annotation specifies the message id of the
+message body below (4242 in the example).  GnunetMessage.Body is a
+union of messages, and ExampleMessage is one (new) member of the
+union.
 
-Every time you add a new type of gnunet message, you have to run the {\tt 
tools/update-msgtypes} command. This
-generates the file {\tt src/org/gnunet/construct/MsgMap.txt}, which allows the 
system to load the right
-java class when reading a message from the network.
+Every time you add a new type of GNUnet message, you have to run the
+{\tt tools/update-msgtypes} command. This generates the file {\tt
+  src/org/gnunet/construct/MsgMap.txt}, which allows the system to
+load the right java class when reading a message from the network.
 
-The above message then contains a value annotated with {\tt @UInt8}: An 8-bit 
{\bf U}nsigned integer.
-There are similar annotations for integers of other sizes, and {\tt @Int}{\it 
N} annotations for signed integers.
-The second member is a String, whose binary representation appends a zero-byte 
to the string to mark its end.
+The above message then contains a value annotated with {\tt @UInt8}:
+An {\bf 8}-bit {\bf U}nsigned {\bf int}eger.  There are similar
+annotations for integers of other sizes, and {\tt @Int}{\it N}
+annotations for signed integers.  The second member is a String, whose
+binary representation appends a zero-byte to the string to mark its
+end.
 
-Other useful annotations can be found in the package {\tt 
org.gnunet.construct}. Among them are annotations for arrays of fixed or 
variable size 
-({\tt @VariableSizeArray, @FixedSizeArray}), for embeding other messages in 
your message ({\tt @NestedMessage} and
+Other useful annotations can be found in the package {\tt
+  org.gnunet.construct}. Among them are annotations for arrays of
+fixed or variable size ({\tt @VariableSizeArray, @FixedSizeArray}),
+for embeding other messages in your message ({\tt @NestedMessage} and
 for implementing your own message unions.
 
+\exercise{Define a message that contains a 32-bit signed integer.}
 
-\bigskip
-{\bf Exercise:} Define a message that contains a 32-bit signed integer.
-\bigskip
 
 \subsection{Connecting to Core}
-After creating a handle to core by calling the {\tt Core} constructor, you 
have to specify what
-types of messages you are interested in. The core service will only send 
messages of these types to you,
-and only notify you of connecting peers if they share a subset of the messages 
you are interested in.
 
-The {\tt handleMessages} method allows you to specify an object of a class 
inheriting {\tt Runabout}.
-The Runabout is a mechanism for single-argument multiple dispatch in Java.
-You have to define one {\tt visit} method for every type of message you are 
interested in.
-Once Core receives a Message, it is dispatched dynamically to the visit method 
with the right signature.
-Note that every visit method, as well as the receiver's class has to be 
public, in order for the
-dynamic dispatch to work.
+After creating a handle to core by calling the {\tt Core} constructor,
+you have to specify what types of messages you are interested in. The
+core service will only send messages of these types to you, and only
+notify you of connecting peers if they share a subset of the messages
+you are interested in.
 
+The {\tt handleMessages} method allows you to specify an object of a
+class inheriting {\tt Runabout}.  The Runabout is a mechanism for
+single-argument multiple dispatch in Java.  You have to define one
+{\tt visit} method for every type of message you are interested in.
+Once {\tt Core} receives a message, it is dispatched dynamically to
+the {\tt visit} method with the appropriate signature.  Note that
+every {\tt visit} method, as well as the receiver's class, has to be
+public in order for the dynamic dispatch to work.
+
 Example:
-\begin{lstlisting}
+
+\begin{lstlisting}[language=java]
 public class MyMessageReceiver extends Runabout {
     public visit(MyFooMessage m) { /* do something */ }
     public visit(MyBarMessage m  { /* do something else */ }
 }
 \end{lstlisting}
 
-After specifing your message handler, the {\tt init} method has to be called 
with a callback object.
-This starts the handshake with the core service, once done the callback 
object's {\tt onInit} method will
+After specifing your message handler, the {\tt init} method has to be
+called with a callback object.  This starts the handshake with the
+core service, once done the callback object's {\tt onInit} method will
 be called with your peer's identity.
 
 \subsection{Sending a message to another peer}
-Before you can actually send a message, you have to wait until the core 
service is ready to send your message.
-This is done by calling the {\tt notifyTransmitReady} method. You have to 
provide a callback object to this method,
-whose {\tt transmit} method is invoked with a {\tt MessageSink} object once 
the core is ready to transmit your message.
-Call the {\tt send} method in the {\tt MessageSink} in order to finally 
transmit it.
 
+Before you can actually send a message, you have to wait until the
+core service is ready to send your message.  This is done by calling
+the {\tt notifyTransmitReady} method. You have to provide a callback
+object to this method, whose {\tt transmit} method is invoked with a
+{\tt MessageSink} object once the core is ready to transmit your
+message.  Call the {\tt send} method in the {\tt MessageSink} in order
+to finally transmit it.
+
 Example:
-\begin{lstlisting}
+
+\begin{lstlisting}[language=java]
 // arguments: messagePriority, timeout, targetPeer, messageSize, transmitter
 core.notifyTransmitReady(0, RelativeTime.FOREVER, myIdentity, 42, new 
MessageTransmitter() {
     public transmit(Connection.MessageSink sink) {
@@ -266,37 +342,45 @@
     }
 \end{lstlisting}
 
-You can use {\tt Construct.getSize} to calculate the size of a message, or 
just do it manually.
+You can use {\tt Construct.getSize} to calculate the size of a
+message, or just do it manually.
 
-\bigskip
-{\bf Exercise:} Write an echo program for core: Send a message to the local 
peer and receive it!
-\bigskip
+\exercise{Write an echo program for core: Send a message to the local peer and 
receive it!}
 
+
 \section{Other useful APIs}
-Many of gnunet's services are not yet available as a gnunet-java API.
 
-The other two service APIs currently implemented are nse (in {\tt 
org.gnunet.java.nse.NetworkSizeEstimation}), 
-a service that gives an estimation of the current size of the network, and dht 
(in {\tt org.gnunet.java.dht.DistributedHashTable}), a service that allows 
key/value pairs to be stored distributed across the network.
+Many of GNUnet's services are not yet available as a gnunet-java API.
 
+The other two service APIs currently implemented are nse (in {\tt
+  org.gnunet.java.nse.NetworkSizeEstimation}), a service that gives an
+estimation of the current size of the network, and DHT (in {\tt
+  org.gnunet.java.dht.DistributedHashTable}), a service that allows
+key/value pairs to be stored distributed across the network.
+
+
 \section{Writing your own client/server}
-{\tt gnunet} is split up in components, every component runs in its own 
process.
-In the previous sections you have used existing APIs to interface with other 
services.
-gnunet-java also provides the tools necessary to directly interface with 
services yourself.
-The {\tt org.gnunet.util.Client} class allows to connect to a gnunet service 
and transmit/receive messages.
 
-At the time of writing of this tutorial, the server/service functionality is 
not yet fully implemented.
+GNUnet is split up into components, every component runs in its own
+process.  In the previous sections you have used existing APIs to
+interface with other services written in C.  gnunet-java also provides
+the tools necessary to directly interface with services yourself.  The
+{\tt org.gnunet.util.Client} class allows to connect to a GNUnet
+service and exchange messages with the service.
 
+At the time of writing of this tutorial, the server/service API is 
+not yet fully implemented, so writing new services in Java is not
+yet ``easy'' in 0.9.3.  However, you can write daemons and user
+interfaces using the {\tt Program} class.
 
-\bigskip
-\noindent
-{\bf Exercise:} Write a {\tt Service} and a {\tt Program} with a client that 
communicates with it.
-\noindent
-{\bf Exercise(advanced):} Write an API for a gnunet service that has not been 
implemented yet in gnunet-java.
-\bigskip
+\exercise{Write a {\tt Service} and a {\tt Program} with a client that 
communicates with it.}
+\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{The state of gnunet-java}
-The {\tt gnunet-java} project is under heavy development, expect changes that 
break your stuff!
-Please report any bugs or feature requests at \url{https://gnunet.org/bugs/}
 
+The {\tt gnunet-java} project is under heavy development, expect
+changes that break your stuff!  Please report any bugs or feature
+requests at \url{https://gnunet.org/bugs/}
+
 \end{document}




reply via email to

[Prev in Thread] Current Thread [Next in Thread]