diff options
| -rw-r--r-- | doc/ivy-java.sgml | 53 |
1 files changed, 43 insertions, 10 deletions
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 |