From f1b701b31a59d905cae82a752a56a3ed87a1b668 Mon Sep 17 00:00:00 2001
From: jestin
Date: Thu, 29 Jul 2004 17:32:21 +0000
Subject: doc major update

---
 doc/ivy-java.sgml | 53 +++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 43 insertions(+), 10 deletions(-)

(limited to 'doc/ivy-java.sgml')

diff --git a/doc/ivy-java.sgml b/doc/ivy-java.sgml
index 1691119..175b684 100644
--- a/doc/ivy-java.sgml
+++ b/doc/ivy-java.sgml
@@ -343,10 +343,10 @@ Will send each remote agent the substrings in case there is a regexp matching.
 The default behaviour is not to send the message to oneself !
 The result is the number of messages actually sent. The main issue here is
 that the sender ivy agent is the one who takes care of the regexp matching, so
-that only useful information are conveyed on the network. For instance, if
-agent B has subscribed to "^a*(.*)c*" and agent A triggers
-sendMsg("aaaaaaaaabccccccc"), the agent B will execute its callback with a "b"
-parameter.
+that only useful information are conveyed on the network. Be sure that the
+message sent doesn't contains protocol characters: 0x01 to 0x08 and
+unfortunately 0x0D, the newline character. If you want to send newlines, see
+protectNewline, in advanced functions.
 
 </para></sect2><sect2><title>Subscription to messages</title>
 
@@ -413,14 +413,18 @@ public boolean isSendToSelf();
 </para>
 </sect2>
 
-<sect2><title>Sending to self</title>
+<sect2><title>Newline within messages</title>
 <para>
-using <command>Ivy.protectNewLine(boolean b)</command>, you can set your Ivy
-object to ensure encoding and decoding of newlines characters. This is tested
+As we have seen in <function>Ivy.sendMsg()</function>, you can not have
+newline characters within the string you send on the bus. If you still want to
+send messages with newline, you can encode and decode them at the emitter and
+receiver's side. With <command>Ivy.protectNewLine(boolean b)</command>, you can set your
+Ivy object to ensure encoding and decoding of newlines characters. This is tested
 and working between java ivy applications, but not yet implemented in other
-ivy libraries. The newlines are protected by ESC characters ( hex 0x1A ). As
+ivy libraries. The newlines are replaced by ESC characters ( hex 0x1A ). As
 the encoding and decoding cost a little more CPU and is not yet standardized
-in the Ivy protocol, use it at your own risk.
+in the Ivy protocol, use it at your own risk. We should of course protect the
+other protocol special caracters.
 </para>
 </sect2>
 
@@ -446,7 +450,9 @@ buffer and to the blocking of the message sender. To alleviate this, we have
 set up since ivy-java 1.2.4 an asynchronous subscription, where each and every
 time a callback is performed, it is done in a newly created separate thread.
 As creating a thread is quite expensive, one should use this method for
-lengthy callbacks only.
+lengthy callbacks only. Furthermore, to avoid concurrent access to the
+callback data, the String[] argument passed on to the callbacks are cloned.
+This causes an extra overhead.
 <programlisting>
 public int bindMsg(String regexp, IvyMessageListener callback,boolean async);
 public int bindAsyncMsg(String regexp, IvyMessageListener callback);
@@ -457,6 +463,33 @@ thread will be created for each callback. The same
 </para>
 </sect2>
 
+<sect2><title>Waiting for someone: waitForClient and waitForMsg</title>
+<para>
+Very often, while developping an Ivy agent, you will be facing the need of the
+arrival of another agent on the bus to perform your task correctly. For
+instance, for your spiffy application to run, a gesture recognition engine
+will have to be on the bus, or another data sending application. The Ivy way
+to do this is to subscribe to the known agent's <parameter>ready
+message</parameter> (be sure to subscribe before starting the
+bus), or to implement an IvyApplicationListener and change of state in the
+<function>connect()</function> method. However, it is often useful to stop and
+wait, and it is awkward to wait for a variable change.
+<programlisting>
+IvyClient waitForClient(String name, int timeout)
+IvyClient waitForMsg(String regexp, int timeout) 
+</programlisting>
+These two methods allow you to stop the flow of your main (or other) thread
+by waiting for the arrival of an agent, or for the arrival of a message. If
+the agent is already here, <function>waitForClient</function> will return
+immediately. If <parameter>timeout</parameter> is set to null, your thread can
+wait "forever", otherwise it will wait <parameter>timeout</parameter>
+milliseconds. With <function>waitForMsg</function>, be aware that your subscription can be
+propagated to the remote agents after that their message was sent, so that
+you'd wait for nothing. You had better be sure that the
+<function>waitForMsg</function> method is called early enough.
+</para>
+</sect2>
+
 <sect2><title>Subscribing to subscriptions</title>
 <para>
 TODO
-- 
cgit v1.1