[GNUnet-SVN] r21084 - in gnunet-java: doc src/org/gnunet/core src/org/gnunet/statistics

[gnunet]

Author: dold
Date: 2012-04-22 23:50:09 +0200 (Sun, 22 Apr 2012)
New Revision: 21084

Modified:
   gnunet-java/doc/gnunet-java-tutorial.tex
   gnunet-java/src/org/gnunet/core/Core.java
   gnunet-java/src/org/gnunet/statistics/Statistics.java
Log:
updated tutorial


Modified: gnunet-java/doc/gnunet-java-tutorial.tex
===================================================================
--- gnunet-java/doc/gnunet-java-tutorial.tex    2012-04-22 21:21:03 UTC (rev 
21083)
+++ gnunet-java/doc/gnunet-java-tutorial.tex    2012-04-22 21:50:09 UTC (rev 
21084)
@@ -17,7 +17,6 @@
 %\author{Florian Dold\\
 %    address@hidden
 %}
-\date{}
 
 \begin{document}
 
@@ -27,7 +26,7 @@
 
 \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}.
+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}.
 
@@ -47,14 +46,15 @@
 
 \section{Creating an extension}
 
+
+
+\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, you should ignore this and write your own.
+{\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.
 
-
-\section{A simple gnunet-java program}
 \subsection{The Basics}
 \begin{lstlisting}[language=java]
 public class HelloGnunet {
@@ -70,9 +70,9 @@
 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
 
 \subsection{Adding and using command line arguments}
@@ -116,11 +116,16 @@
 \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 subclassing the 
getVersion / getAboutTest methods in your Program subclass.
+You can change the about text and the version information by overriding the 
{\tt getVersion} / 
+{\tt getAboutTest} methods in your Program subclass.
 
+\bigskip
+{\bf Exercise:} Add a few different command line options to your program and 
print them to {\tt System.out}!
+\bigskip
+
 \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.
-\subsubsection{Establishing a connection with the statistics service}
+\subsection{Establishing a connection with the statistics service}
 
 \begin{lstlisting}[language=java]
 Statistics statistics = new Statistics(getConfiguration());
@@ -131,17 +136,22 @@
 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
+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.
 
+
+\subsection{Setting statistics}
+
 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}
 
+\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
@@ -166,8 +176,9 @@
 \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 {\tt gnunet-statistics} command 
line program to view and
-modify values from the statistics service.
+\bigskip
+{\bf Exercise:} Write a program that sets statistics values, and check the 
result with the {\tt gnunet-statistics} command line tool.
+{\bf Exercise:} Now the other way around: Write a program to read statistics 
values.
 
 \bigskip
 
@@ -191,18 +202,26 @@
 }
 \end{lstlisting}
 
-The {\tt @UnionCase} annotation specifies the message id of the message body 
below. That is, GnunetMessage.Body
+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.
 
 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.
 
-Other useful annotations can be found in the package {\tt 
org.gnunet.construct}. Among them are annotations for
-zero-terminated strings ({\tt @ZeroTerminatedString}), arrays of fixed or 
variable size 
+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.
+
+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.
 
+
+\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,
@@ -227,16 +246,16 @@
 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}
-Before you can actually send a message, you have to wait until core is ready 
to receive a new message.
-This is done by calling the {\tt notifyTransmitReady}. You have to provide a 
callback object to this method,
+\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.
 
 Example:
 \begin{lstlisting}
 // arguments: messagePriority, timeout, targetPeer, messageSize, transmitter
-client.notifyTransmitReady(0, RelativeTime.FOREVER, myIdentity, new 
MessageTransmitter() {
+core.notifyTransmitReady(0, RelativeTime.FOREVER, myIdentity, 42, new 
MessageTransmitter() {
     public transmit(Connection.MessageSink sink) {
         sink.transmit(myMessage);
     }
@@ -245,8 +264,11 @@
     }
 \end{lstlisting}
 
+You can use {\tt Construct.getSize} to calculate the size of a message, or 
just do it manually.
 
-{\bf Exercise:} Write a program that connects to core, and send a message to 
the local peer!
+\bigskip
+{\bf Exercise:} Write an echo program for core: Send a message to the local 
peer and receive it!
+\bigskip
 
 \section{Other useful APIs}
 Many of gnunet's services are not yet available as a gnunet-java API.
@@ -260,10 +282,17 @@
 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 functionality is not yet 
fully implemented.
+At the time of writing of this tutorial, the server/service functionality is 
not yet fully implemented.
 
+
+\bigskip
+{\bf Exercise:} Write a {\tt Service} and a {\tt Program} with a client that 
communicates with it.
+{\bf Exercise(advanced):} Write an API for a gnunet service that has not been 
implemented yet in gnunet-java.
+\bigskip
+
+
 \section{The state of gnunet-java}
-The {\tt gnunet-java} project is under heavy development, expect changes that 
break your stuff!  
-Please send any suggestions, questions or complaints to {\tt address@hidden
+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}

Modified: gnunet-java/src/org/gnunet/core/Core.java
===================================================================
--- gnunet-java/src/org/gnunet/core/Core.java   2012-04-22 21:21:03 UTC (rev 
21083)
+++ gnunet-java/src/org/gnunet/core/Core.java   2012-04-22 21:50:09 UTC (rev 
21084)
@@ -500,7 +500,8 @@
         final TransmitHandle transmitHandle = new TransmitHandle();
 
         transmitHandle.peerIdentity = target;
-        transmitHandle.size = size;
+        // add space for the header
+        transmitHandle.size = size + 4;
         transmitHandle.smrId = cpi.nextSmrId;
         transmitHandle.transmitter = transmitter;
         cpi.nextSmrId += 1;

Modified: gnunet-java/src/org/gnunet/statistics/Statistics.java
===================================================================
--- gnunet-java/src/org/gnunet/statistics/Statistics.java       2012-04-22 
21:21:03 UTC (rev 21083)
+++ gnunet-java/src/org/gnunet/statistics/Statistics.java       2012-04-22 
21:50:09 UTC (rev 21084)
@@ -87,6 +87,7 @@
 
     private class StatisticsGetRequest extends StatisticsRequest implements 
Cancelable {
         public StatisticsReceiver receiver;
+        public Cancelable receiveHandle;
 
         public class GetResponseHandler extends RunaboutMessageReceiver {
             public void visit(ResponseValueMessage m) {
@@ -107,6 +108,9 @@
         @Override
         public void cancel() {
             requests.remove(this);
+            if (receiveHandle != null) {
+                receiveHandle.cancel();
+            }
         }
 
         @Override
@@ -121,7 +125,7 @@
 
             sink.send(rm);
 
-            client.receive(deadline.getRemaining(), new GetResponseHandler());
+            receiveHandle = client.receive(deadline.getRemaining(), new 
GetResponseHandler());
         }
 
         @Override