fr.dgac.ivy

Class Ivy


public class Ivy
extends java.lang.Object
implements Runnable

a software bus package

Field Summary

public static final String DEFAULT_DOMAIN
the domain for the UDP rendez vous
public static final int DEFAULT_PORT
the port for the UDP rendez vous, if none is supplied
public static final int PROTOCOLMINIMUM
public static final int PROTOCOLVERSION
the protocol version number
public static final int TIMEOUTLENGTH
protected int applicationPort
protected boolean doProtectNewlines
public static final String libVersion
the library version, useful for development purposes only, when java is invoked with -DIVY_DEBUG
protected String ready_message
protected SelfIvyClient selfIvyClient

Constructor Summary

public Ivy(String name, String message, IvyApplicationListener appcb)
Readies the structures for the software bus connexion.

Method Summary

public int addApplicationListener(IvyApplicationListener callback)
adds an application listener to a bus
public int addBindListener(IvyBindListener callback)
adds a bind listener to a bus
public int bindAsyncMsg(String sregexp, IvyMessageListener callback)
Subscribes to a regular expression with asyncrhonous callback execution.
public int bindMsg(String sregexp, IvyMessageListener callback)
Subscribes to a regular expression.
public int bindMsg(String sregexp, IvyMessageListener callback, boolean async)
Subscribes to a regular expression.
protected void clientConnects(IvyClient client)
protected void clientDisconnects(IvyClient client)
protected void dieReceived(IvyClient client, int id, String message)
public void directMessage(IvyClient client, int id, String msgarg)
public String domains(String toparse)
public static String getDomainArgs(String progname, String args)
returns the domain bus
public static String getDomain(String domainbus)
returns the domain bus
public Vector getIvyClientsByName(String name)
gives a list of IvyClient(s) with the name given in parameter
public Vector getIvyClients()
gives the names of IvyClient(s)
public IvyClient getSelfIvyClient()
returns our self IvyClient.
protected int getSerial()
public boolean isSendToSelf()
public static void main(String args)
public fr.dgac.ivy.Ivy.Domain parseDomains(String domainbus)
public void protectNewlines(boolean b)
Toggles the encoding/decoding of messages to prevent bugs related to the presence of a "\n"
protected void regexpDeleted(IvyClient client, int id, String sregexp)
protected void regexpReceived(IvyClient client, int id, String sregexp)
public void removeApplicationListener(int id)
removes an application listener
public void removeBindListener(int id)
removes a bind listener
public void run()
public int sendMsg(String message)
Performs a pattern matching according to everyone's regexps, and sends the results to the relevant ivy agents.
public void sendToSelf(boolean b)
Toggles the sending of messages to oneself, the remote client's IvyMessageListeners are processed first, and ourself afterwards.
public void start(String domainbus)
connects the Ivy bus to a domain or list of domains.
public void stop()
disconnects from the Ivy bus
public void unBindMsg(int id)
unsubscribes a regular expression
public boolean unBindMsg(String re)
unsubscribes a regular expression
public IvyClient waitForClient(String name, int timeout)
Waits for an other IvyClient to join the bus
public IvyClient waitForMsg(String regexp, int timeout)
Waits for a message to be received

Field Details

DEFAULT_DOMAIN

public static final DEFAULT_DOMAIN

the domain for the UDP rendez vous

DEFAULT_PORT

public static final DEFAULT_PORT

the port for the UDP rendez vous, if none is supplied

PROTOCOLMINIMUM

public static final PROTOCOLMINIMUM


PROTOCOLVERSION

public static final PROTOCOLVERSION

the protocol version number

TIMEOUTLENGTH

public static final TIMEOUTLENGTH


applicationPort

protected applicationPort


doProtectNewlines

protected doProtectNewlines


libVersion

public static final libVersion

the library version, useful for development purposes only, when java is invoked with -DIVY_DEBUG

ready_message

protected ready_message


selfIvyClient

protected selfIvyClient

Constructor Details

Ivy

public Ivy(String name, String message, 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

Method Details

addApplicationListener

public int addApplicationListener(IvyApplicationListener callback)

adds an application listener to a bus

Parameters:

callback - is an object implementing the IvyApplicationListener interface

addBindListener

public int addBindListener(IvyBindListener callback)

adds a bind listener to a bus

Parameters:

callback - is an object implementing the IvyBindListener interface
Since:
1.2.4

bindAsyncMsg

public int bindAsyncMsg(String sregexp, IvyMessageListener callback)

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:

sregexp
callback - any objects implementing the IvyMessageListener interface, on the AWT/Swing framework

Throws:

IvyException
Since:
1.2.4

bindMsg

public int bindMsg(String sregexp, IvyMessageListener callback)

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:

sregexp
callback - any objects implementing the IvyMessageListener interface, on the AWT/Swing framework

Throws:

IvyException

bindMsg

public int bindMsg(String sregexp, IvyMessageListener callback, boolean async)

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:

sregexp
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

Throws:

IvyException
Since:
1.2.4

clientConnects

protected void clientConnects(IvyClient client)

Parameters:

client

clientDisconnects

protected void clientDisconnects(IvyClient client)

Parameters:

client

dieReceived

protected void dieReceived(IvyClient client, int id, String message)

Parameters:

client
id
message

directMessage

public void directMessage(IvyClient client, int id, String msgarg)

Parameters:

client
id
msgarg

domains

public String domains(String toparse)

Parameters:

toparse

getDomainArgs

public static String getDomainArgs(String progname, String args)

returns the domain bus

Parameters:

progname - The name of your program, for error message
args - the String[] of arguments passed to your main()
Since:
1.2.8

getDomain

public static String getDomain(String domainbus)

returns the domain bus

Parameters:

domainbus - if non null, returns the argument

getIvyClientsByName

public Vector getIvyClientsByName(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

getIvyClients

public Vector getIvyClients()

gives the names of IvyClient(s)

getSelfIvyClient

public IvyClient getSelfIvyClient()

returns our self IvyClient.
Since:
1.2.4

getSerial

protected int getSerial()


isSendToSelf

public boolean isSendToSelf()

Since:
1.2.4

main

public static void main(String args)

Parameters:

args

parseDomains

public fr.dgac.ivy.Ivy.Domain parseDomains(String domainbus)

Parameters:

domainbus

protectNewlines

public void protectNewlines(boolean b)

Toggles the encoding/decoding of messages to prevent bugs related to the presence of a "\n"

Parameters:

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

regexpDeleted

protected void regexpDeleted(IvyClient client, int id, String sregexp)

Parameters:

client
id
sregexp

regexpReceived

protected void regexpReceived(IvyClient client, int id, String sregexp)

Parameters:

client
id
sregexp

removeApplicationListener

public void removeApplicationListener(int id)

removes an application listener

Parameters:

id - the id of the application listener to remove

Throws:

IvyException

removeBindListener

public void removeBindListener(int id)

removes a bind listener

Parameters:

id - the id of the bind listener to remove

Throws:

IvyException
Since:
1.2.4

run

public void run()


sendMsg

public int sendMsg(String message)

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

Throws:

IvyException

sendToSelf

public void sendToSelf(boolean b)

Toggles the sending of messages to oneself, the remote client's IvyMessageListeners are processed first, and ourself afterwards.

Parameters:

b
Since:
1.2.4

start

public void start(String domainbus)

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.

    Throws:

    IvyException

    stop

    public void stop()

    disconnects from the Ivy bus

    unBindMsg

    public void unBindMsg(int id)

    unsubscribes a regular expression

    Parameters:

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

    Throws:

    IvyException

    unBindMsg

    public boolean unBindMsg(String re)

    unsubscribes a regular expression

    Parameters:

    re

    waitForClient

    public IvyClient waitForClient(String name, int timeout)

    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

    Throws:

    IvyException
    Since:
    1.2.4

    waitForMsg

    public IvyClient waitForMsg(String regexp, int timeout)

    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

    Throws:

    IvyException
    Since:
    1.2.4