[Top][All Lists]
[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}
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r21096 - gnunet-java/doc,
gnunet <=