juglr
Class MessageBus

java.lang.Object
  extended by juglr.MessageBus

public class MessageBus
extends java.lang.Object

Central message hub all actors are connected to. Actors created without a specific message bus will be using the bus obtained from calling getDefault().

See Also:
juglr.net.HTTPMessageBus

Constructor Summary
MessageBus()
          Create a new, empty, MessageBus.
 
Method Summary
 Address allocateNamedAddress(Actor actor, java.lang.String name)
          Assign a named address to actor.
 Address allocateUniqueAddress(Actor actor)
           
 boolean freeAddress(Address address)
          Release a unique- or named address.
static MessageBus getDefault()
          Get a reference to the default MessageBus instance for the runtime.
 java.util.Iterator<Address> list()
          Iterate through all unique- and named addresses on the bus
 Address lookup(java.lang.String address)
          Look up an Address for given string.
static void main(java.lang.String[] args)
           
 void send(Message msg, Address recipient)
          Asynchronously send msg to recipient.
 void start(Address recipient)
          Asynchronously invoke the Actor.start() on the recipient actor
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MessageBus

public MessageBus()
Create a new, empty, MessageBus. Note that actor by default register on the bus provided by getDefault(). If you want actors to register on a non-default bus you must pass in the bus as a parameter in the actor's constructor.

Unless you have specific requirements you are advised to use the getDefault() to obtain a bus instance instead of invoking this method directly.

See Also:
getDefault(), Actor.Actor(MessageBus)
Method Detail

getDefault

public static MessageBus getDefault()
Get a reference to the default MessageBus instance for the runtime. If there is no instance yet a new one will be created. By a default MessageBus will be created, but you may specify another MessageBus class in the system property juglr.busclass.

Actors created without a reference to a message bus will use the message bus obtained from calling this method.

Returns:
a reference to the system wide default message bus

allocateUniqueAddress

public Address allocateUniqueAddress(Actor actor)

allocateNamedAddress

public Address allocateNamedAddress(Actor actor,
                                    java.lang.String name)
                             throws AddressAlreadyOwnedException
Assign a named address to actor. Note that named addresses must start with a /. So if have an actor responsible for flushing messages to persistent storage, you could assign it the well known address /store. Actors in need of storing a message would not need to know the unique address of the storage actor, simply be aware of the of the agreement that the storage actor is available under the /store address.

Parameters:
actor - The actor to associate the named address with
name - the address to assign
Returns:
the Address instance created to represent the named address
Throws:
AddressAlreadyOwnedException - if the address is already owned by an actor
IllegalAddressException - if name doesn't start with a /

freeAddress

public boolean freeAddress(Address address)
Release a unique- or named address. Actors wishing to retract from the bus should call this method with the value of their getAddress() method as well as with any named addresses they own.

Parameters:
address - the address to release
Returns:
true if the address existed on the bus and has been removed. Returns false if the address was not known

list

public java.util.Iterator<Address> list()
Iterate through all unique- and named addresses on the bus

Returns:
and iterator over all addresses registered on the bus

send

public void send(Message msg,
                 Address recipient)
Asynchronously send msg to recipient. Note that it is highly recommended to never send messages containing mutable state unless you know exactly what you are doing.

Parameters:
msg - the message to send
recipient - the address of the recipient actor

start

public void start(Address recipient)
Asynchronously invoke the Actor.start() on the recipient actor

Parameters:
recipient - the address of the actor to start

lookup

public Address lookup(java.lang.String address)
Look up an Address for given string. Note that addresses normally start with a /.

Parameters:
address - the external string form of the address to look up
Returns:
The address which' external form is address or null in case no such address is registered on the bus

main

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