


		    Important Events in JavaGroups
		    ==============================



1. Create a new group
---------------------

  a. Multicast address

- A client calls GroupService.CreateGroup(GroupService.UseMcast). This
  returns a new group if not yet existent, otherwise an exception is
  thrown. For this purpose the GroupService multicasts the new group
  name to all GroupServices. This installs the new group in all GSs.

- A new entry is added to the GroupService's local groups hashtable

- A new multicast address (IP address/port) is automatically chosen
  for the group. Alternatively, the caller may supply IP address and
  port. No JOIN to the MCAST address is done yet ! No
  UdpMcastReceiverThread is yet created to listen to the multicast
  address !




  b. Unicast address

- A client calls GroupService.CreateGroup(GroupService.UseUcast). This
  returns a new group if not yet existent, otherwise an exception is
  thrown. The new group is installed in all GSs (see above).

- If the group exists, our own IP address/port is added to the
  Group's address. (Our own address is the one that Transport is
  listening on (in_port)). This means adding a UnicastAddress to the
  MultipleAddress of Group. However, this is only done when the
  address is not yet present in MultipleAddress !






2. Client joins group
---------------------

  a. Group with multicast address

- The client calls Group.Join(client) to add itself to the group

- If this is the first local JOIN to the multicast address (first
  object to join the group), then a new UdpMcastReceiverThread is
  created to listen to the mcast address (UDP.JoinMultiCastGroup) 

- The Group adds the caller (Member) to the Group (locally) and sends
  a ViewChange message to all GroupServices




  b. Group with unicast address

- The client calls Group.Join(client) to add itself to the group

- The Group adds the caller (Member) to the Group (locally) and sends
  a ViewChange message to all GroupServices





3. Client leaves group
----------------------

  a. Multicast group

- When the last local member leaves the group, we LEAVE the multicast
  address, but do not delete the group since clients must still be
  able to send messages to the members of the group on other
  nodes. However, they won't receive multicast messages any longer
  (until a JOIN is done)



  b. Unicast group

- (Nothing to be done)




4. Client sends multicast message to group
------------------------------------------

- The client calls Group.Mcast(msg)

- An mcast message is sent to the multicast group

- The groups of all objects that have joined them will have a
  multicast address to which a UdpMcastReceiverThread is listening
  (Transport). Therefore at least one object will receive the message

- The multicast message is received by the group service. The
  group service locates the object(s) with the help of the message's
  destination address (which contains host:port:id of the object)

- The Receive() upcall is invoked on the object(s) (in a separate
  thread)







5. Client sends unicast message to group member(s)
--------------------------------------------------

- The client calls Group.Send(msg)

- The groups of all objects that have joined it will have a
  MultipleAddress address object. Each of these represents one
  Dispatcher object

- A unicast message is sent to all addresses that are members of the
  MultipleAddress address, effectively sending a unicast message to a
  number of dispatchers

- Each dispatcher receives the message and dispatches it to the
  members of the group.

