[GNUnet-SVN] r20950 - in gnunet-java: . bin doc

[gnunet]

Author: dold
Date: 2012-04-12 08:46:06 +0200 (Thu, 12 Apr 2012)
New Revision: 20950

Added:
   gnunet-java/bin/gnunet-core
Modified:
   gnunet-java/ISSUES
   gnunet-java/doc/gnunet-exercise.tex
Log:
updated issues, doc

Modified: gnunet-java/ISSUES
===================================================================
--- gnunet-java/ISSUES  2012-04-11 16:03:28 UTC (rev 20949)
+++ gnunet-java/ISSUES  2012-04-12 06:46:06 UTC (rev 20950)
@@ -347,19 +347,41 @@
 
 
========================================================================================
 
-* 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?
 * => solved, ported C-code, encountered some problems because of the lack of 
unsigned in java
   (had to use long instead of int in java code because of sign)
@@ -388,6 +410,8 @@
 * 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 @@
  * 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
-

Added: gnunet-java/bin/gnunet-core
===================================================================
--- gnunet-java/bin/gnunet-core                         (rev 0)
+++ gnunet-java/bin/gnunet-core 2012-04-12 06:46:06 UTC (rev 20950)
@@ -0,0 +1,5 @@
+#!/bin/sh
+
+DIR=`dirname $0`
+
+java -ea -cp "$DIR/../build/:$DIR/../lib/*" org.gnunet.core.Core "$@"


Property changes on: gnunet-java/bin/gnunet-core
___________________________________________________________________
Added: svn:executable
   + *

Modified: gnunet-java/doc/gnunet-exercise.tex
===================================================================
--- gnunet-java/doc/gnunet-exercise.tex 2012-04-11 16:03:28 UTC (rev 20949)
+++ gnunet-java/doc/gnunet-exercise.tex 2012-04-12 06:46:06 UTC (rev 20950)
@@ -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,18 +35,17 @@
 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,
 otherwise you have to prefix every command with this directory.
@@ -55,11 +54,18 @@
 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}
 \begin{lstlisting}
@@ -73,22 +79,141 @@
 }
 \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 address@hidden
 
+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 address@hidden 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}
address@hidden(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}