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

[gnunet]

Author: dold
Date: 2014-04-07 16:59:17 +0200 (Mon, 07 Apr 2014)
New Revision: 32933

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

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 14:56:17 UTC (rev 
32932)
+++ gnunet-java/doc/gnunet-java-tutorial.tex    2014-04-07 14:59:17 UTC (rev 
32933)
@@ -36,7 +36,7 @@
 
 Although GNUnet is primarily developed in the C programming language, it is 
also possible to write peer-to-peer applications
 with GNUnet in Java.
-The GNUnet-Java project provides bindings to a subset of existing GNUnet 
components, and provides the infrastructure to
+The GNUnet-Java project provides bindings to a subset of existing GNUnet 
components, as well as the infrastructure to
 develop new components.  GNUnet-Java is less stable and less complete than the 
C version. Please report any bugs or feature requests at 
\url{https://gnunet.org/bugs/}.
 
 \section{Getting Started}
@@ -198,12 +198,10 @@
 
 The Statistics constructor is called with the configuration,
 provided by the method {\tt getConfiguration} of the {\tt Program}
-class.  This establishes a connection to the
+class.  The configuration contains the necessary information (port numbers, 
socket paths, \dots) to establish 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 one
-has to wrap their program in the {\tt run} method of {\tt
-  Program}: Once all method calls are done, the run method
-returns, and GNUnet-Java keeps the system running until all work is done.
+operation is asynchronous, meaning that the above statement
+does not wait for the connection to be established, but returns immediately.
 
 Always remember to explicitly destroy your {\tt
   Statistics} instance by calling its {\tt destroy()}
@@ -213,14 +211,15 @@
 \subsection{Setting statistics}
 
 You can use the newly created {\tt statistics} handle to, for instance,
-set the value named ``\# bytes sent'' to the value 42. The last parameter 
(\texttt{true})
-indicates that the value should be stored persistently (%
-persistent values are stored even if the statistics service restarts).
-
+set the value named ``\# bytes sent'' to the value 42.
 \begin{lstlisting}[language=java]
 statistics.set("gnunet-java-hello", "# bytes sent", 42, true);
 \end{lstlisting}
+The last parameter (\texttt{true})
+indicates that the value should be stored persistently (%
+persistent values are stored even if the statistics service restarts).
 
+
 \subsection{Retrieving statistics}
 
 Retrieving a value is slightly more complex. Because of the
@@ -233,7 +232,7 @@
 This example retrieves the statistics value ``\# Requests Served'' for the 
subsystem ``gnunet-java-hello''
 \begin{lstlisting}[language=java]
 Cancelable getCancel = statistics.get(RelativeTime.SECOND, "gnunet-java-hello",
-"# Requests Served", new Statistics.StatisticsReceiver {
+        "# Requests Served", new Statistics.StatisticsReceiver {
     public void onDone() {
         System.out.println("everything done");
     }
@@ -283,7 +282,7 @@
 }
 \end{lstlisting}
 
-The {\tt @UnionCase} annotation specifies the message id of the
+The {\tt @UnionCase} annotation specifies the message type 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.
@@ -295,7 +294,7 @@
 \end{lstlisting}
 This generates the file {\tt
   src/main/java/org/gnunet/construct/MsgMap.txt}, which allows the system to
-instantiate the right Java class when reading a message from the network.
+instantiate the right Java class when de-serializing a message from its binary 
representation.
 
 The above message then contains a value annotated with {\tt @UInt8}:
 An {\bf 8}-bit {\bf U}nsigned {\bf int}eger.  There are similar
@@ -320,9 +319,9 @@
 
 \subsection{Connecting to Core}
 
-After creating a handle to core by calling the {\tt Core} constructor,
+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
+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.
 
@@ -346,16 +345,16 @@
 
 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, and once done the callback object's {\tt onInit} method will
+CORE service, and 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
+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
+{\tt MessageSink} object once CORE is ready to transmit your
 message.  Call the {\tt transmit} method in the {\tt MessageSink}
 with a {\tt GnunetMessage.Body} in order transmit it to CORE.
 to finally transmit it. The header of the message is automatically
@@ -376,12 +375,11 @@
 You can use {\tt Construct.getSize} to calculate the size of a
 message, or compute it manually.
 
-\exercise{Write an echo program for core: Send a message to the local peer and 
receive it!}
+\exercise{Write an echo program for CORE: Send a message to the local peer and 
receive it!}
 
 \section{Establishing channels to remote peers with MESH}
 In contrast to CORE, the MESH
-service can send messages reliably (if requested) over channels to distant 
peers.
-
+service can send messages reliably (if requested) over channels to distant 
peers, who must not necessarily be directly connected.
 The following code connects to the mesh service, and waits for connections on 
port 42:
 \begin{lstlisting}[language=java]
 Mesh m = new Mesh(cfg, inboundChannelHandler, messageHandler, 42);
@@ -391,7 +389,7 @@
 to our peer on port 42.  The \texttt{messageHandle} must be a Runabout 
instance, and implement visit methods analogously to the
 CORE message handler in the previous section.
 
-The following snippet estavlishes a channel to the given peer on port 42, where
+The following snippet establishes a channel to the given peer on port 42, where
 the channel should not buffer data (first boolean argument) and be reliable 
(second boolean argument).
 \begin{lstlisting}[language=java]
 Channel c = m.createChannel(targetPeer, 42, true, true);
@@ -468,7 +466,7 @@
 Run \texttt{gnunet-gns-import.sh} (distributed with the main GNUnet package) 
in order to
 set up GNS.
 
-Verify that this created a master-zone ego:
+Verify that this created the master-zone ego:
 \begin{lstlisting}[language=bash]
 \$ gnunet-identity -d # display all egos
 \end{lstlisting}
@@ -478,7 +476,7 @@
 \$ gnunet-namestore -z master-zone -a -n myrecord -t A -V 1.2.3.4 -e never
 \end{lstlisting}
 
-The following snipped assumes that \texttt{master} is the ego with the name 
``master-zone'',
+The following snippet assumes that \texttt{master} is the ego with the name 
``master-zone'',
 as retrieved with the \texttt{Identity.lookup} function.
 \begin{lstlisting}
 final Gns gns = new Gns(getConfiguration());