fr.dgac.ivy
Class Ivy

java.lang.Object
  |
  +--fr.dgac.ivy.Ivy
All Implemented Interfaces:
java.lang.Runnable

public class Ivy
extends java.lang.Object
implements java.lang.Runnable


Field Summary
protected  int applicationPort
           
protected  java.lang.String appName
          the name of the application on the bus
static java.lang.String DEFAULT_DOMAIN
          the domain for the UDP rendez vous
static int DEFAULT_PORT
          the port for the UDP rendez vous, if none is supplied
protected  boolean doProtectNewlines
           
static java.lang.String libVersion
          the library version, useful for development purposes only, when java is invoked with -DIVY_DEBUG
static int PROTOCOLMINIMUM
           
static int PROTOCOLVERSION
          the protocol version number
protected  java.lang.String ready_message
           
protected  fr.dgac.ivy.SelfIvyClient selfIvyClient
           
static int TIMEOUTLENGTH
           
 
Constructor Summary
Ivy(java.lang.String name, java.lang.String message, fr.dgac.ivy.IvyApplicationListener appcb)
          Readies the structures for the software bus connexion.
 
Method Summary
 int addApplicationListener(fr.dgac.ivy.IvyApplicationListener callback)
          adds an application listener to a bus
 int addBindListener(fr.dgac.ivy.IvyBindListener callback)
          adds a bind listener to a bus
 int bindAsyncMsg(java.lang.String sregexp, fr.dgac.ivy.IvyMessageListener callback)
          Subscribes to a regular expression with asyncrhonous callback execution.
 int bindMsg(java.lang.String sregexp, fr.dgac.ivy.IvyMessageListener callback)
          Subscribes to a regular expression.
 int bindMsg(java.lang.String sregexp, fr.dgac.ivy.IvyMessageListener callback, boolean async)
          Subscribes to a regular expression.
protected  void clientConnects(fr.dgac.ivy.IvyClient client)
           
protected  void clientDisconnects(fr.dgac.ivy.IvyClient client)
           
protected  void dieReceived(fr.dgac.ivy.IvyClient client, int id, java.lang.String message)
           
 void directMessage(fr.dgac.ivy.IvyClient client, int id, java.lang.String msgarg)
           
 java.lang.String domains(java.lang.String toparse)
           
static java.lang.String getDomain(java.lang.String domainbus)
           
 java.util.Vector getIvyClients()
          gives the names of IvyClient(s)
 java.util.Vector getIvyClientsByName(java.lang.String name)
          gives a list of IvyClient(s) with the name given in parameter
 fr.dgac.ivy.IvyClient getSelfIvyClient()
          returns our self IvyClient.
protected  int getSerial()
           
 boolean isSendToSelf()
           
static void main(java.lang.String[] args)
           
 fr.dgac.ivy.Ivy.Domain[] parseDomains(java.lang.String domainbus)
           
 void protectNewlines(boolean b)
          Toggles the encoding/decoding of messages to prevent bugs related to the presence of a "\n"
protected  void regexpDeleted(fr.dgac.ivy.IvyClient client, int id, java.lang.String sregexp)
           
protected  void regexpReceived(fr.dgac.ivy.IvyClient client, int id, java.lang.String sregexp)
           
 void removeApplicationListener(int id)
          removes an application listener
 void removeBindListener(int id)
          removes a bind listener
 void run()
           
 int sendMsg(java.lang.String message)
          Performs a pattern matching according to everyone's regexps, and sends the results to the relevant ivy agents.
 void sendToSelf(boolean b)
          Toggles the sending of messages to oneself, the remote client's IvyMessageListeners are processed first, and ourself afterwards.
 void start(java.lang.String domainbus)
          connects the Ivy bus to a domain or list of domains.
 void stop()
          disconnects from the Ivy bus
 void unBindMsg(int id)
          unsubscribes a regular expression
 boolean unBindMsg(java.lang.String re)
          unsubscribes a regular expression
 fr.dgac.ivy.IvyClient waitForClient(java.lang.String name, int timeout)
          Waits for an other IvyClient to join the bus
 fr.dgac.ivy.IvyClient waitForMsg(java.lang.String regexp, int timeout)
          Waits for a message to be received
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

appName

protected java.lang.String appName
the name of the application on the bus


PROTOCOLVERSION

public static final int PROTOCOLVERSION
the protocol version number

See Also:
Constant Field Values

PROTOCOLMINIMUM

public static final int PROTOCOLMINIMUM
See Also:
Constant Field Values

DEFAULT_PORT

public static final int DEFAULT_PORT
the port for the UDP rendez vous, if none is supplied

See Also:
Constant Field Values

DEFAULT_DOMAIN

public static final java.lang.String DEFAULT_DOMAIN
the domain for the UDP rendez vous

See Also:
Constant Field Values

libVersion

public static final java.lang.String libVersion
the library version, useful for development purposes only, when java is invoked with -DIVY_DEBUG

See Also:
Constant Field Values

applicationPort

protected int applicationPort

ready_message

protected java.lang.String ready_message

doProtectNewlines

protected boolean doProtectNewlines

selfIvyClient

protected fr.dgac.ivy.SelfIvyClient selfIvyClient

TIMEOUTLENGTH

public static final int TIMEOUTLENGTH
See Also:
Constant Field Values
Constructor Detail

Ivy

public Ivy(java.lang.String name,
           java.lang.String message,
           fr.dgac.ivy.IvyApplicationListener appcb)
Readies the structures for the software bus connexion. All the dirty work is done un the start() method

Parameters:
name - The name of your Ivy agent on the software bus
message - The hellow message you will send once ready
appcb - A callback handling the notification of connexions and disconnections, may be null
See Also:
start(java.lang.String)
Method Detail

waitForMsg

public fr.dgac.ivy.IvyClient waitForMsg(java.lang.String regexp,
                                        int timeout)
                                 throws IvyException
Waits for a message to be received

Parameters:
regexp - the message we're waiting for to continue the main thread.
timeout - in millisecond, 0 if infinite
Returns:
the IvyClient who sent the message, or null if the timeout is reached
IvyException
Since:
1.2.4

waitForClient

public fr.dgac.ivy.IvyClient waitForClient(java.lang.String name,
                                           int timeout)
                                    throws IvyException
Waits for an other IvyClient to join the bus

Parameters:
name - the name of the client we're waiting for to continue the main thread.
timeout - in millisecond, 0 if infinite
Returns:
the first IvyClient with the name or null if the timeout is reached
IvyException
Since:
1.2.4

start

public void start(java.lang.String domainbus)
           throws IvyException
connects the Ivy bus to a domain or list of domains.
  • One thread (IvyWatcher) for each traffic rendezvous (either UDP broadcast or TCPMulticast)
  • One thread (serverThread/Ivy) to accept incoming connexions on server socket
  • a thread for each IvyClient when the connexion has been done

    Parameters:
    domainbus - a domain of the form 10.0.0:1234, it is similar to the netmask without the trailing .255. This will determine the meeting point of the different applications. Right now, this is done with an UDP broadcast. Beware of routing problems ! You can also use a comma separated list of domains.
    IvyException

  • parseDomains

    public fr.dgac.ivy.Ivy.Domain[] parseDomains(java.lang.String domainbus)

    stop

    public void stop()
    disconnects from the Ivy bus


    sendToSelf

    public void sendToSelf(boolean b)
    Toggles the sending of messages to oneself, the remote client's IvyMessageListeners are processed first, and ourself afterwards.

    Since:
    1.2.4

    isSendToSelf

    public boolean isSendToSelf()
    Since:
    1.2.4

    getSelfIvyClient

    public fr.dgac.ivy.IvyClient getSelfIvyClient()
    returns our self IvyClient.

    Since:
    1.2.4

    protectNewlines

    public void protectNewlines(boolean b)
    Toggles the encoding/decoding of messages to prevent bugs related to the presence of a "\n"

    Since:
    1.2.5 The default escape character is a ESC 0x1A

    sendMsg

    public int sendMsg(java.lang.String message)
                throws IvyException
    Performs a pattern matching according to everyone's regexps, and sends the results to the relevant ivy agents.

    Parameters:
    message - A String which will be compared to the regular expressions of the different clients
    Returns:
    returns the number of messages actually sent
    IvyException

    bindMsg

    public int bindMsg(java.lang.String sregexp,
                       fr.dgac.ivy.IvyMessageListener callback)
                throws IvyException
    Subscribes to a regular expression. The callback will be executed with the saved parameters of the regexp as arguments when a message will sent by another agent. A program doesn't receive its own messages.

    Example:
    the Ivy agent A performs

    b.bindMsg("^Hello (*)",cb);

    the Ivy agent B performs
    b2.sendMsg("Hello world");

    a thread in A will uun the callback cb with its second argument set to a array of String, with one single element, "world"

    Parameters:
    callback - any objects implementing the IvyMessageListener interface, on the AWT/Swing framework
    Returns:
    the id of the regular expression
    IvyException

    bindAsyncMsg

    public int bindAsyncMsg(java.lang.String sregexp,
                            fr.dgac.ivy.IvyMessageListener callback)
                     throws IvyException
    Subscribes to a regular expression with asyncrhonous callback execution. Same as bindMsg, except that the callback will be executed in a separate thread each time. WARNING : there is no way to predict the order of execution of the * callbacks, i.e. a message received might trigger a callback before another one sent before

    Parameters:
    callback - any objects implementing the IvyMessageListener interface, on the AWT/Swing framework
    Returns:
    the int ID of the regular expression.
    IvyException
    Since:
    1.2.4

    bindMsg

    public int bindMsg(java.lang.String sregexp,
                       fr.dgac.ivy.IvyMessageListener callback,
                       boolean async)
                throws IvyException
    Subscribes to a regular expression. The callback will be executed with the saved parameters of the regexp as arguments when a message will sent by another agent. A program doesn't receive its own messages.

    Example:
    the Ivy agent A performs

    b.bindMsg("^Hello (*)",cb);

    the Ivy agent B performs
    b2.sendMsg("Hello world");

    a thread in A will uun the callback cb with its second argument set to a array of String, with one single element, "world"

    Parameters:
    callback - any objects implementing the IvyMessageListener interface, on the AWT/Swing framework
    async - if true, each callback will be run in a separate thread, default is false
    Returns:
    the id of the regular expression
    IvyException
    Since:
    1.2.4

    unBindMsg

    public void unBindMsg(int id)
                   throws IvyException
    unsubscribes a regular expression

    Parameters:
    id - the id of the regular expression, returned when it was bound
    IvyException

    unBindMsg

    public boolean unBindMsg(java.lang.String re)
    unsubscribes a regular expression

    Returns:
    a boolean, true if the regexp existed, false otherwise or whenever an exception occured during unbinding

    addBindListener

    public int addBindListener(fr.dgac.ivy.IvyBindListener callback)
    adds a bind listener to a bus

    Parameters:
    callback - is an object implementing the IvyBindListener interface
    Returns:
    the id of the bind listener, useful if you wish to remove it later
    Since:
    1.2.4

    removeBindListener

    public void removeBindListener(int id)
                            throws IvyException
    removes a bind listener

    Parameters:
    id - the id of the bind listener to remove
    IvyException
    Since:
    1.2.4

    addApplicationListener

    public int addApplicationListener(fr.dgac.ivy.IvyApplicationListener callback)
    adds an application listener to a bus

    Parameters:
    callback - is an object implementing the IvyApplicationListener interface
    Returns:
    the id of the application listener, useful if you wish to remove it later

    removeApplicationListener

    public void removeApplicationListener(int id)
                                   throws IvyException
    removes an application listener

    Parameters:
    id - the id of the application listener to remove
    IvyException

    clientConnects

    protected void clientConnects(fr.dgac.ivy.IvyClient client)

    clientDisconnects

    protected void clientDisconnects(fr.dgac.ivy.IvyClient client)

    regexpReceived

    protected void regexpReceived(fr.dgac.ivy.IvyClient client,
                                  int id,
                                  java.lang.String sregexp)

    regexpDeleted

    protected void regexpDeleted(fr.dgac.ivy.IvyClient client,
                                 int id,
                                 java.lang.String sregexp)

    dieReceived

    protected void dieReceived(fr.dgac.ivy.IvyClient client,
                               int id,
                               java.lang.String message)

    directMessage

    public void directMessage(fr.dgac.ivy.IvyClient client,
                              int id,
                              java.lang.String msgarg)

    getIvyClients

    public java.util.Vector getIvyClients()
    gives the names of IvyClient(s)


    getIvyClientsByName

    public java.util.Vector getIvyClientsByName(java.lang.String name)
    gives a list of IvyClient(s) with the name given in parameter

    Parameters:
    name - The name of the Ivy agent you're looking for

    getDomain

    public static java.lang.String getDomain(java.lang.String domainbus)

    run

    public void run()
    Specified by:
    run in interface java.lang.Runnable

    getSerial

    protected int getSerial()

    domains

    public java.lang.String domains(java.lang.String toparse)

    main

    public static void main(java.lang.String[] args)