updated issues, doc

3 files changed, 171 insertions, 29 deletions

diff --git a/ISSUES b/ISSUES
index f68ad51..774edb6 100644
--- a/ISSUES
+++ b/ISSUES
@@ -347,17 +347,39 @@ public interface GnunetMessageBody extends MessageUnion { }
 
 ========================================================================================
 
-* client_api.c
+* are we in a hurry? when should gnunet-java be usable to students?
+ * according to the website the project begins very soon
+* currently my progress with the tutorial is not that far, as the java APIs are not
+  yet completely implemented / stable.
+* needed: a place to host the javadocs (so the tutorial can link to it)
+
+* what is the best way to configure the classpath for gnunet-java-ext?
+ * a bash script that exports environment variables for e.g. the gnunet-java.jar?
+* once a MessageMap.txt has been generated for a new extension, how do we tell gnunet-java that/where it
+  exists?
+* what about allocation of message IDs for extesions / what about clashes?
+
+* core_api.c, notify_transmit_ready:
   * pr = GNUNET_CONTAINER_multihashmap_get (handle->peers, &target->hashPubKey);
   * the above line crashes when target==NULL, but comment indicates that NULL is valid for target
 
 * ...NOTIFY_PRE_CONNECT.. message type not used
 
-* what about allocation of message IDs for extesions / what about clashes?
 
 core:
 * we seem to get all incoming messages if the handlers array is empty (even if we don't request anything)
 * being notified about outbound messages does not seem to work at all
+ * comment in core_connect talks about timout, but there is no timeout parameter.
+ * GNUNET_MESSAGE_TYPE_CORE_NOTIFY_STATUS_CHANGE not used
+  * also GNUNET_CORE_OPTION_SEND_STATUS_CHANGE
+ * inconsistency in structs with trailing ATS information (NotifyTrafficMessage vs ConnectNotifyMessage)
+  * why zero-termination *and* size field?
+  * what does zero-termination really mean? is it only one byte? a whole ats entry?
+ * what happens when we can't connect to core / lose connection? in the c api implementation, this is never handeled?
+  * why is there even the init callback if init can't fail?
+
+* are there really any ambiguities when receiving messages with a runabout?
+
 
 
 * how does the Hash ascii-encoding work?
@@ -388,6 +410,8 @@ int[] foo;
 * server:
  * what is a MessageStreamTokenizer and why does it belong to the server?
   * my guess: for fragmented messages inside other messages?
+  * GNUNET_SERVER_connect_socket: what is it for?
+  * how to disable corking in java? is corking the same as TCP_NODELAY?
 
 
 * discuss: the size parameter in the various notifyTransmitReady methods
@@ -395,22 +419,10 @@ int[] foo;
  * proposal: keep for c api compatibility, introduce additional version that
    gets a message object directly, and calls a continuation to notify about success/failure
 
-* core:
- * comment in core_connect talks about timout, but there is no timeout parameter.
- * GNUNET_MESSAGE_TYPE_CORE_NOTIFY_STATUS_CHANGE not used
-  * also GNUNET_CORE_OPTION_SEND_STATUS_CHANGE
- * inconsistency in structs with trailing ATS information (NotifyTrafficMessage vs ConnectNotifyMessage)
-  * why zero-termination *and* size field?
-  * what does zero-termination really mean? is it only one byte? a whole ats entry?
- * what happens when we can't connect to core / lose connection? in the c api implementation, this is never handeled?
-  * why is there even the init callback if init can't fail?
 
 
-* GNUNET_SERVER_connect_socket: what is it for?
-* how to disable corking in java? is corking the same as TCP_NODELAY?
-
+* server:
+ * what is client_keep?
+ * when handling signals through the pipe, how is the service / server notified?
 
-* why is installing gnunet so compilicated?
- * e.g. stuff like "base of XYZ installation" in ./configure is very confusing
- * many dependencies with out-of-date packages on common distros
 
diff --git a/bin/gnunet-core b/bin/gnunet-core
new file mode 100755
index 0000000..dea64d8
--- /dev/null
+++ b/bin/gnunet-core
@@ -0,0 +1,5 @@
+#!/bin/sh
+
+DIR=`dirname $0`
+
+java -ea -cp "$DIR/../build/:$DIR/../lib/*" org.gnunet.core.Core "$@"
diff --git a/doc/gnunet-exercise.tex b/doc/gnunet-exercise.tex
index 692b03c..1845e0e 100644
--- a/doc/gnunet-exercise.tex
+++ b/doc/gnunet-exercise.tex
@@ -26,7 +26,7 @@
 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}.
 
-TODO: ./configure --enable-javaports
+TODO: remark about ./configure --enable-javaports / port configuration
 
 Make sure that the default gnunet services are running by typing
 \begin{lstlisting}
@@ -35,17 +35,16 @@ gnunet-arm -I
 on your command line.
 
 \section{Installing gnunet-java}
-You can either check out the latest version of gnunet-java with
+Check out the latest version of gnunet-java with
 \lstset{language=bash}
 \begin{lstlisting}
 svn checkout https://gnunet.org/svn/gnunet-java/
 \end{lstlisting}
-or download a more convenient installer at \url{http://example.com/gnunet-java-installer.jar}.
-You can start the installer by double-clicking on it, or running
+as well as the template directory for extensions with
 \begin{lstlisting}
-java -jar gnunet-java-installer.jar
+svn checkout https://gnunet.org/svn/gnunet-java-ext/
 \end{lstlisting}
-on your command line.
+
 
 \section{First Steps}
 Programs to communicate with gnunet are located unter the bin/ directory. You can add this directory to your path,
@@ -55,10 +54,17 @@ To test if everything is working, try to run the program gnunet-nse. This should
 of the network.
 
 \subsection{Project Layout}
-(explanation of the directory structure: src, test, bin, tools, gnunet-java-ext)
+src contains the source code of gnunet-java, test contains test cases, bin contains wrappers arround main classes,
+tools contain scripts used for development.
+
+gnunet-java-ext has a similar structure.
+
 
 \section{Creating an extension}
-(copying gnunet-java-ext, setting variables / the gnunet-java path in the bash wrapper)
+create a copy of gnunet-java-ext and rename it to gnunet-java-hellognunet.
+
+\subsection{configuring your extension}
+describe the classpath config file, the shell wrapper
 
 \section{A simple gnunet-java program}
 \lstset{language=java}
@@ -73,22 +79,141 @@ public class HelloGnunet {
 }
 \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)
+
 \subsection{Adding and using command line arguments}
 Command line options are added by annotating members of your org.gnunet.util.Program-subclass
 with the \@Option-annotation.
 
+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}
+
+The command line program can now be called with -nXXX or --name=XXX.
+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 \@Option annotation can not only be used with Strings, but also with booleans and numbers.
+
+(reference the java docs)
+
+By default, the following arguments are available on the command line
+
+(table comes here)
+
+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 gnunet statistics api to track how often the HelloGnunet program
 has been run.
+\subsubsection{Establishing a connection to the statistics service}
+
+\begin{lstlisting}
+Statistics statistics = new Statistics(cfg);
+\end{lstlisting}
+
+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 run method: Once all your asynchronous calls are
+made, the run method returns, and gnunet-java hast to keep the system running until all work has been done.
+
+\begin{lstlisting}
+statistics.set(RelativeTime.SECOND, "gnunet-java-ext-hello", "has said hello", 1,
+    new SetCompleted() {
+        @Override
+        public void onCompleted() {
+            System.out.println("done.");
+        }
+
+        @Override
+        public void onTimeout() {
+            System.out.println("timeout while setting");
+        }});
+\end{lstlisting}
+
 
 \section {Overview of useful APIs}
-statistics, dht, core
+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}
+@UnionCase(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}
-\subsection{Defining a new message type}
-(example, annotations, running gnunet-java-update-msgtypes)
-\section{Writing a gnunet service}
+\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}