[GNUnet-SVN] r17933 - in gnunet-java: . src/org/gnunet/util/client src/org/gnunet/util/connection

[gnunet]

Author: dold
Date: 2011-11-02 16:47:40 +0100 (Wed, 02 Nov 2011)
New Revision: 17933

Modified:
   gnunet-java/ISSUES
   gnunet-java/src/org/gnunet/util/client/Client.java
   gnunet-java/src/org/gnunet/util/connection/Connection.java
Log:
added stuff

Modified: gnunet-java/ISSUES
===================================================================
--- gnunet-java/ISSUES  2011-11-02 15:37:42 UTC (rev 17932)
+++ gnunet-java/ISSUES  2011-11-02 15:47:40 UTC (rev 17933)
@@ -2,4 +2,6 @@
 * package structure, inner classes vs. packages
 * naming conventions: stick with java standards?
 * ugly cross-reference to TransmitReadyNotify.java in 
org.gnunet.util.client.Client
-*
\ No newline at end of file
+* Client/Connection class hierarchy
+* how to handle disconnect/destroy (as java cannot directly dispose of objects)
+* 
\ No newline at end of file

Modified: gnunet-java/src/org/gnunet/util/client/Client.java
===================================================================
--- gnunet-java/src/org/gnunet/util/client/Client.java  2011-11-02 15:37:42 UTC 
(rev 17932)
+++ gnunet-java/src/org/gnunet/util/client/Client.java  2011-11-02 15:47:40 UTC 
(rev 17933)
@@ -6,24 +6,102 @@
 
 public class Client {
        interface MessageHandler {
-               
+
        }
 
        public static class TransmitHandle {
+               /**
+                * Cancel a request for notification.
+                */
                void cancel() {
                        throw new UnsupportedOperationException();
                }
-               
+
        }
+
+       /**
+        * Get a connection with a service.
+        * 
+        * @param service_name
+        *            name of the service
+        * @param cfg
+        *            configuration to use
+        */
        public Client(String service_name, Configuration c) {
                throw new UnsupportedOperationException();
        }
-       
+
+       /**
+        * Read from the service.
+        * 
+        * @param handler
+        *            function to call with the message
+        * @param timeout
+        *            how long to wait until timing out
+        */
+
        public void receive(MessageHandler handler, RelativeTime timeout) {
                throw new UnsupportedOperationException();
        }
-       public TransmitHandle notifyTransmitReady(int size, RelativeTime 
timeout, boolean auto_retry,
-                       TransmitReadyNotify cb) {
+
+       /**
+        * Ask the client to call us once the specified number of bytes are 
free in
+        * the transmission buffer. May call the notify method immediately if 
enough
+        * space is available.
+        * 
+        * @param sock
+        *            connection to the service
+        * @param size
+        *            number of bytes to send
+        * @param timeout
+        *            after how long should we give up (and call notify with buf
+        *            NULL and size 0)?
+        * @param auto_retry
+        *            if the connection to the service dies, should we 
automatically
+        *            re-connect and retry (within the timeout period) or 
should we
+        *            immediately fail in this case? Pass GNUNET_YES if the 
caller
+        *            does not care about temporary connection errors, for 
example
+        *            because the protocol is stateless
+        * @param notify
+        *            function to call
+        * @param notify_cls
+        *            closure for notify
+        * @return NULL if someone else is already waiting to be notified 
non-NULL
+        *         if the notify callback was queued (can be used to cancel 
using
+        *         GNUNET_CONNECTION_notify_transmit_ready_cancel)
+        */
+       public TransmitHandle notifyTransmitReady(int size, RelativeTime 
timeout,
+                       boolean auto_retry, TransmitReadyNotify cb) {
                throw new UnsupportedOperationException();
        }
+
+       
+       /**
+        * Convenience API that combines sending a request
+        * to the service and waiting for a response.
+        * If either operation times out, the callback
+        * will be called with a "NULL" response (in which
+        * case the connection should probably be destroyed).
+        *
+        * @param sock connection to use
+        * @param hdr message to transmit
+        * @param timeout when to give up (for both transmission
+        *         and for waiting for a response)
+        * @param auto_retry if the connection to the service dies, should we
+        *        automatically re-connect and retry (within the timeout period)
+        *        or should we immediately fail in this case?  Pass GNUNET_YES
+        *        if the caller does not care about temporary connection errors,
+        *        for example because the protocol is stateless
+        * @param rn function to call with the response
+        * @param rn_cls closure for rn
+        * @return GNUNET_OK on success, GNUNET_SYSERR if a request
+        *         is already pending
+        */
+       // XXX: should rettype really be bool?
+       // XXX: how to represent the message? does the original function really 
only
+       // get the header?
+       public boolean transmitAndGetResponse(Message m, RelativeTime timeout,
+                       boolean autoRetry, MessageHandler handler) {
+               throw new UnsupportedOperationException();
+       }
 }

Modified: gnunet-java/src/org/gnunet/util/connection/Connection.java
===================================================================
--- gnunet-java/src/org/gnunet/util/connection/Connection.java  2011-11-02 
15:37:42 UTC (rev 17932)
+++ gnunet-java/src/org/gnunet/util/connection/Connection.java  2011-11-02 
15:47:40 UTC (rev 17933)
@@ -15,7 +15,7 @@
 
        private Connection(Socket s) {
        }
-       
+
        public static Connection fromAccept(ServerSocket ss) {
                throw new UnsupportedOperationException();
        }
@@ -23,53 +23,124 @@
        public static Connection fromExisting(Socket ss) {
                return new Connection(ss);
        }
-       
+
        public static Connection fromConnect(String hostname, long port) {
                throw new UnsupportedOperationException();
        }
-       
+
        public static Connection fromUnixPath(String path) {
                // problematic as java has no nativ support for unix domain 
sockets
                throw new UnsupportedOperationException();
        }
-       
+
        public static Connection fromSocketAddress(SocketAddress addr) {
                throw new UnsupportedOperationException();
        }
 
+       /**
+        * Receive data from the given socket. Note that this function will call
+        * "receiver" asynchronously using the scheduler. It will "immediately"
+        * return. Note that there MUST only be one active receive call per 
socket
+        * at any given point in time (so do not call receive again until the
+        * receiver callback has been invoked).
+        * 
+        * @param max
+        *            maximum number of bytes to read
+        * @param timeout
+        *            maximum amount of time to wait
+        * @param receiver
+        *            function to call with received data
+        */
+
        public void receive(int max, RelativeTime timeout, Receiver r) {
                throw new UnsupportedOperationException();
        }
 
+       /**
+        * Cancel receive job on the given socket. Note that the receiver 
callback
+        * must not have been called yet in order for the cancellation to be 
valid.
+        * 
+        * @return closure of the original receiver callback closure
+        */
        public void receive_cancel() {
                throw new UnsupportedOperationException();
        }
-       
-       
-       public TransmitHandle notifyTransmitReady(int size, RelativeTime 
timeout, boolean auto_retry,
-                       TransmitReadyNotify cb) {
+
+       /**
+        * Ask the socket to call us once the specified number of bytes are 
free in
+        * the transmission buffer. May call the notify method immediately if 
enough
+        * space is available. Note that this function will abort if "size" is
+        * greater than GNUNET_SERVER_MAX_MESSAGE_SIZE.
+        * 
+        * Note that "notify" will be called either when enough buffer space is
+        * available OR when the socket is destroyed. The size parameter given 
to
+        * notify is guaranteed to be larger or equal to size if the buffer is
+        * ready, or zero if the socket was destroyed (or at least closed for
+        * writing). Finally, any time before 'notify' is called, a client may 
call
+        * "notify_transmit_ready_cancel" to cancel the transmission request.
+        * 
+        * Only one transmission request can be scheduled at the same time. 
Notify
+        * will be run with the same scheduler priority as that of the caller.
+        * 
+        * @param size
+        *            number of bytes to send
+        * @param timeout
+        *            after how long should we give up (and call notify with buf
+        *            NULL and size 0)?
+        * @param notify
+        *            function to call when buffer space is available
+        * @param notify_cls
+        *            closure for notify
+        * @return non-NULL if the notify callback was queued, NULL if we are
+        *         already going to notify someone else (busy)
+        */
+       public TransmitHandle notifyTransmitReady(int size, RelativeTime 
timeout,
+                       boolean auto_retry, TransmitReadyNotify cb) {
                throw new UnsupportedOperationException();
        }
 
+       /**
+        * Set the persist option on this connection handle. Indicates that the
+        * underlying socket or fd should never really be closed. Used for
+        * indicating process death.
+        */
        public void persist() {
                this.persist = true;
        }
 
+       /**
+        * Disable the "CORK" feature for communication with the given socket,
+        * forcing the OS to immediately flush the buffer on transmission 
instead of
+        * potentially buffering multiple messages. Essentially reduces the OS 
send
+        * buffers to zero. Used to make sure that the last messages sent 
through
+        * the connection reach the other side before the process is terminated.
+        */
        // XXX: error code / exception
        public void disableCorking() {
                throw new UnsupportedOperationException();
        }
 
+       /**
+        * Check if socket is valid (no fatal errors have happened so far). Note
+        * that a socket that is still trying to connect is considered valid.
+        */
        public boolean check() {
                throw new UnsupportedOperationException();
        }
-       
+
+       /**
+        * Configure this connection to ignore shutdown signals.
+        * 
+        * @param do_ignore
+        *            GNUNET_YES to ignore, GNUNET_NO to restore default
+        */
        public void ignoreShutdown(boolean doIgnore) {
-               
+
        }
-       
+
        /*
-        * not implemented: GNUNET_CONNECTION_get_address (never used outside 
testing)
+        * not implemented: GNUNET_CONNECTION_get_address (never used outside
+        * testing)
         */
 
 }