Broadcast Cell Users Guide

Class

dmg.cells.services.multicaster.BroadcastCell

Syntax

     define context broadcastSetup endDefine
         <configuration>
     endDefine
     #
     create dmg.cells.services.multicaster.BroadcastCell broadcast
  

Purpose

The purpose of the Broadcast cell is to forward messages, it receives, to one or more other cells. The class of the object, carried by the incoming messages, determines the destination cells. The Class-DestinationCell pair is configured by the cells command line interface or by BroadcastCommandMessages. Any cell may register to receive messages containing the specified object class.
Rules :

• If a cell registers for a class, it will receive the specified class plus all classes extending the specified class.
• If a cell registers for an interface, it will receive all classes, implementing this interface.

Map entry modes

• STATIC : The class-cell pair stays in the map until it is actively unregistered.
• CANCEL ON FAILURE : The class-cell pair is removed as soon as the destination cell is no longer reachable.
• AUTO EXIRATION : The class-cell pair is removed after the specified timeout has expired.

The following classes won't be forwarded

• java.lang.String
• dmg.cells.nucleus.NoRouteToCellException and Superclasses
• dmg.cells.services.multicaster.BroadcastCommandMessage and Superclasses.

More :

• If a destination cell replies on a forwarded message, the message travels back to the original source of the messager and not to the BroadcastCell.
• Wellknown cells may be registered through the command line interface just by name. An anonymous cell needs to be registed by its full path (<cell@domain>).
• By using the BroadcastRegisterMessage to register the cell which sends the broadcast message, the path is determined automatically and doesn't need to be specified. If the BroadcastRegisterMessage is used to register a different cell, the above anonymous/wellknow rule applies.

Command Line Syntax

Register Class Destination Pair

        register <eventClass> <destinationCell> [<options>]
            Options :
               -cancelonfailure
               -expires=<Time/seconds>
      

The broadcast cell will forward all messages containing the specified <eventClass> to the <destinationCell>. If -cancelonfailure is specified, the first message which doesn't reach the given <destinationCell> will remove the class-cell pair from the forwarding map. If -expires=<Time/seconds> is give, the class-cell pair is removed automatically after <Time/seconds> seconds. If no option is given, the entry will stay until it is unregistered.

Unregister Class Destination Pair

        unregister <eventClass> <destinationCell>
      

The <eventClass> <destinationCell> pair is removed from the class-cell map.

BroadcastCommmandMessage method

Register

  //
  BroadcastRegisterMessage broadcast = 
         new BroadcastRegisterMessage("<className>");
  //
  // without further options, this will be a static 'registration'
  //
  // OR this would be a cancelOnFailure registration
  //
  broadcast.setCancelOnFailure(true);
  //
  // OR this would be a autmatic experiation registration
  //
  broadcast.setExpires( <experation/seconds> ) ;
  //
  //
  CellMessage carrier = 
         new CellMessage( new CellPath("broadcast") , broadcast ) ;
  //
  sendMessage( carrier ) ;
  

Unregister

  //
  BroadcastUnregisterMessage broadcast = 
         new BroadcastUnregisterMessage("<className>");
  //
  CellMessage carrier = 
         new CellMessage( new CellPath("broadcast") , broadcast ) ;
  //
  sendMessage( carrier ) ;
  

Examples

Static Forwards

     create diskCacheV111.cells.PnfsManager2 PnfsManager \
               " .....   \
                cmRelay=broadcast \
                ..... "
     #         
     create diskCacheV111.poolManager.PoolManagerV5 PoolManager \
               " .....   \
                poolStatusRelay=broadcast \
                ..... "
     #          
     define context broadcastSetup endDefine
         
         register diskCacheV111.vehicles.PoolStatusChangedMessage replicaManager
         register diskCacheV111.vehicles.PnfsModifyCacheLocationMessage replicaManager
         
     endDefine
     #
     create dmg.cells.services.multicaster.BroadcastCell broadcast  \
          "default -export"
     #
  

PoolManager and PnfsManager are sending PoolStatusChanges and PnfsModifyCacheLocation messages to the broadcast cell. The broadcast cell is statically configured to broadcast those messages to the replicaManager. Any Cell may register to get those messages as well without central configuration by using the BroadcastRegisterMessage to register for certain java classes.

  //
  // Prepare broadcast register message for PoolStatusChangedMessage
  //
  String eventClass = "diskCacheV111.vehicles.PoolStatusChangedMessage" ;
  //
  BroadcastRegisterMessage broadcast = new BroadcastRegisterMessage( eventClass );
  //
  CellMessage carrier = new CellMessage( new CellPath("broadcast") , broadcast ) ;
  //
  carrier = sendAndWait( carrier , 10000L ) ;
  //
  if( carrier == null )
     throw new
     Exception("Registing timed out");
  
  broadcast = (BroadcastRegisterMessage)carrier.getMessageObject() ;
  //
  int rc = broadcast.getReturnCode() ;
  if( rc != null ){
      Object obj = broadcast.getReturnObject() ;
      
      if( obj == null )
          throw new
          Exception("Unspecified error received from broadcast registration "+rc ) ;
          
      if( obj instanceof Exception )
          throw (Exception)obj ;
      
      throw new
      Exception("Error received from broadcast registration "+obj ) ;
  }
  say(" Successfully registered for "+eventClass ) ;
  

Dynamic Forwards

Short-living cells, which need to register themselves for a certain event should set the 'cancel on failure' option. This takes care that after the destination cell disappears, the event is automatically unregistered.

  BroadcastRegisterMessage broadcast = new BroadcastRegisterMessage( eventClass );
  //
  broadcast.setCancelOnFailure(true);