ist.palcom.mal
Class AbstractMediaManager

java.lang.Object
  extended by ist.palcom.mal.AbstractMediaManager
All Implemented Interfaces:
MediaManager
Direct Known Subclasses:
BluetoothMediaManager, CompoundMediaManager, IRMediaManager, IRMediaManager, MediaManagerSkeleton, UDPMediaManager

public abstract class AbstractMediaManager
extends java.lang.Object
implements MediaManager

AbstractMediaManager is the central class which hides details about different media and protocols (such as UDP or IR). It is an abstract class. Concrete subclasses implement medium/protocol specifics by instantiating proper subclasses of CommunicationThread.

AbstractMediaManager handles two kinds of communication: unicast and broadcast (in the case of UDP, "broadcast" means multicast). Subclasses implement the method isBroadcast, which determines whether an address is unicast or broadcast.

Communication between this class and the CommunicationThreads that do the actual sending and receiving of messages is done through events. For a message to be sent, the AbstractMediaManager posts a MessageArrayWithURLEvent in the CommunicationThread's mailbox (putEvent). The MessageArrayWithURLEvent contains the message and the URL to send it to. When a message is received, the CommunicationThread posts a MessageArrayWithURLEvent in the mailbox of the AbstractMediaManager's DistributorThread (the AbstractMediaManager is not itself a thread). The URL in the MessageArrayWithURLEvent now contains the URL of the device which the message was received from.. The DistributorThread handles the distribution of the message to interested receivers.

The public methods of this class are used by clients. The protected abstract methods are implemented by subclasses for supporting a particular combination of protocols/media.

See Also:
CommunicationThread, UDPMediaManager

Nested Class Summary
 class AbstractMediaManager.DistributorThread
          Thread for receiving MessageArrayWithURLEvents and distributing them to interested listeners.
 
Field Summary
protected  AbstractMediaManager.DistributorThread distributorThread
           
static java.lang.String PALCOM_URL_PREFIX
           
protected  PalcomScheduler scheduler
           
protected static int TIMEOUTS_BEFORE_REMOVAL
          The number of times a heartBeat (device) can time out before it is removed (during normal, periodic updating - after initiateDiscovery, heartBeat (devices) are removed after the first timeout)
static java.lang.String WIRE_PROTOCOL_VERSION
           
 
Constructor Summary
AbstractMediaManager(PalcomScheduler scheduler, PalcomThread errorHandler)
          Default AbstractMediaManager constructor.
 
Method Summary
 void addErrorHandler(PalcomThread handler)
          Subscribe to error events from this media manager.
abstract  URL[] getDefaultGroupAddresses()
           
abstract  URL getDefaultUnicastURL()
          Returns the URL that the manager listens for messages at by default.
 PalcomPriorityThread getDistributorThread()
           
static java.lang.String getHost(URL url)
           
 java.lang.String getLocalDeviceCache()
           
 java.lang.String getLocalDeviceID()
           
static int getPort(URL url)
           
static java.lang.String getProtocol(URL url)
           
static URL getProtocolSpecificUrl(URL url)
           
protected abstract  CommunicationThread getReceivingThread(URL url)
           
 java.util.ArrayList getRegisteredDevices()
          Get all devices registered at this media manager except itself.
static Selector getSelector(URL url)
           
abstract  int getSendBufferSize()
           
protected abstract  CommunicationThread getSendingThread(URL url)
           
protected abstract  boolean isBroadcast(URL url)
           
 boolean isDeviceRegistered(java.lang.String deviceID)
          Checks if the device with ID deviceID is known to the media manager.
protected  void messageReceived(Message message)
          This method is called every time a message is received.
protected  void raiseErrorEvent(MALErrorEvent mee)
          When unhandled errors occur, concrete implementations of this class should call this method for notifying error handlers about the events.
 void registerAsListener(PalcomThread listener)
          Registers as a listener to messages received by this manager from the network.
 void registerDevice(java.lang.String deviceID, DeviceCacheObject device)
          This method is public so it can be used by test programs, but it is usually not called from other classes.
 void registerForHeartBeats(PalcomThread listener)
          Register as a listener for heartBeats.
protected abstract  void removeReceivingThread(URL url)
          Stop receiving at url, and remove the receiving thread.
 boolean send(Message message, java.lang.String receiverDeviceID)
          Send a message to a receiver at a given deviceID.
 void sendBroadcast(Message message)
          Send out a broadcast message, with required message header nodes inserted before.
 void sendHeartAttack()
          Send out a broadcast HeartAttack message.
 void sendHeartBeat(boolean isHeartBeatAck, LinkedList messageHeaderNodes)
          Send out a broadcast HeartBeat message.
 void setDiscoverySelector(Selector selector)
           
 void setLocalDeviceCache(java.lang.String deviceCache)
           
 void setLocalDeviceID(java.lang.String deviceID)
           
 void setLocalDiscoveryVersion(java.lang.String discoveryVersion)
           
 void setLocalStatusFlag(byte statusFlag)
           
 void setPeriod(long period)
          Set the time interval between heartbeats.
 void stop()
          Stop the manager.
abstract  void suggestSendBufferSize(int size)
          Used in the same manner as setSendBufferSize.
 boolean unRegisterDevice(java.lang.String deviceID)
          This method removes a device and its information from the list with registered devices.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PALCOM_URL_PREFIX

public static final java.lang.String PALCOM_URL_PREFIX
See Also:
Constant Field Values

TIMEOUTS_BEFORE_REMOVAL

protected static int TIMEOUTS_BEFORE_REMOVAL
The number of times a heartBeat (device) can time out before it is removed (during normal, periodic updating - after initiateDiscovery, heartBeat (devices) are removed after the first timeout)


scheduler

protected final PalcomScheduler scheduler

distributorThread

protected AbstractMediaManager.DistributorThread distributorThread

WIRE_PROTOCOL_VERSION

public static final java.lang.String WIRE_PROTOCOL_VERSION
See Also:
Constant Field Values
Constructor Detail

AbstractMediaManager

public AbstractMediaManager(PalcomScheduler scheduler,
                            PalcomThread errorHandler)
Default AbstractMediaManager constructor. Should be overridden in subclasses where appropriate, to allow for instantiation using reflection mechanisms. You may specify an errorHandler @see #addErrorHandler(PalcomPriorityThread) if you wish to know about any errors occuring in the startup phase of the AbstractMediaManager; If not, simply pass null.

Method Detail

registerAsListener

public void registerAsListener(PalcomThread listener)
Registers as a listener to messages received by this manager from the network. Currently only one listener at a time is supported.

Specified by:
registerAsListener in interface MediaManager
Parameters:
listener - The PalcomThread that are interested in messages from the media manager.

registerForHeartBeats

public void registerForHeartBeats(PalcomThread listener)
Register as a listener for heartBeats. This method is used by test programs and the RoutingManager.

Specified by:
registerForHeartBeats in interface MediaManager

setPeriod

public void setPeriod(long period)
Set the time interval between heartbeats. This method has to be called in order for the device to send out heartbeats requesting answers, otherwise it will only send out heartbeats in reply to other devices.

Specified by:
setPeriod in interface MediaManager

getDistributorThread

public PalcomPriorityThread getDistributorThread()
Specified by:
getDistributorThread in interface MediaManager

suggestSendBufferSize

public abstract void suggestSendBufferSize(int size)
Used in the same manner as setSendBufferSize.

Specified by:
suggestSendBufferSize in interface MediaManager

getSendBufferSize

public abstract int getSendBufferSize()
Specified by:
getSendBufferSize in interface MediaManager

setLocalDeviceCache

public void setLocalDeviceCache(java.lang.String deviceCache)
Specified by:
setLocalDeviceCache in interface MediaManager

getLocalDeviceCache

public java.lang.String getLocalDeviceCache()
Specified by:
getLocalDeviceCache in interface MediaManager

getLocalDeviceID

public java.lang.String getLocalDeviceID()
Specified by:
getLocalDeviceID in interface MediaManager

setLocalDeviceID

public void setLocalDeviceID(java.lang.String deviceID)
Specified by:
setLocalDeviceID in interface MediaManager

setLocalStatusFlag

public void setLocalStatusFlag(byte statusFlag)
Specified by:
setLocalStatusFlag in interface MediaManager

setLocalDiscoveryVersion

public void setLocalDiscoveryVersion(java.lang.String discoveryVersion)
Specified by:
setLocalDiscoveryVersion in interface MediaManager

setDiscoverySelector

public void setDiscoverySelector(Selector selector)
Specified by:
setDiscoverySelector in interface MediaManager

sendHeartBeat

public void sendHeartBeat(boolean isHeartBeatAck,
                          LinkedList messageHeaderNodes)
Send out a broadcast HeartBeat message. This method is used by the ResourceManager. Sending HeartBeatAck messages are handled automatically by the AbstractMediaManager.

Specified by:
sendHeartBeat in interface MediaManager
Parameters:
isHeartBeatAck - is the heartBeat an ack or a request for others to answer with heartbeatAcks.
messageHeaderNodes - used when for instance a mark node should be sent with the heartBeat.

sendHeartAttack

public void sendHeartAttack()
Send out a broadcast HeartAttack message. This method is used by the DiscoveryManager and tells the receiving devices that this devices is about to close down.

Specified by:
sendHeartAttack in interface MediaManager

stop

public void stop()
Stop the manager. This will stop all listening for messages.

Specified by:
stop in interface MediaManager

addErrorHandler

public void addErrorHandler(PalcomThread handler)
Subscribe to error events from this media manager. Unhandled errors within the AbstractMediaManager will be send to the handler in the form of MALErrorEvent events. Notice: Currently, only one error handler at a time is supported

Specified by:
addErrorHandler in interface MediaManager

send

public boolean send(Message message,
                    java.lang.String receiverDeviceID)
Send a message to a receiver at a given deviceID.

Specified by:
send in interface MediaManager
Parameters:
message - The message to send.
receiverDeviceID - The deviceID of the receiver.
Returns:
True if the AbstractMediaManager knows about the device, and has sent the message.

sendBroadcast

public void sendBroadcast(Message message)
Send out a broadcast message, with required message header nodes inserted before.

Specified by:
sendBroadcast in interface MediaManager

registerDevice

public void registerDevice(java.lang.String deviceID,
                           DeviceCacheObject device)
This method is public so it can be used by test programs, but it is usually not called from other classes.

Specified by:
registerDevice in interface MediaManager

unRegisterDevice

public boolean unRegisterDevice(java.lang.String deviceID)
This method removes a device and its information from the list with registered devices.

Specified by:
unRegisterDevice in interface MediaManager
Parameters:
deviceID - The ID of the device to be removed.
Returns:
True if the device was removed from the list.

getRegisteredDevices

public java.util.ArrayList getRegisteredDevices()
Get all devices registered at this media manager except itself.

Specified by:
getRegisteredDevices in interface MediaManager
Returns:
ArrayList with DeviceCacheObjects

isDeviceRegistered

public boolean isDeviceRegistered(java.lang.String deviceID)
Checks if the device with ID deviceID is known to the media manager.

Specified by:
isDeviceRegistered in interface MediaManager
Parameters:
deviceID - must contain deviceID but nothing more.
Returns:
true if device is registered

getDefaultUnicastURL

public abstract URL getDefaultUnicastURL()
Returns the URL that the manager listens for messages at by default. This method has been made public so it can be used from test programs, but it is not otherwise used by classes other than AbstractMediaManager and its subclasses.

Returns:
The default URL. This URL is listened on unless another URL is specified in a call to startReceiving(String, PalcomThread).

getReceivingThread

protected abstract CommunicationThread getReceivingThread(URL url)
Returns:
CommunicationThread for receiving at url. If it does not exist, a new one is created and returned.

removeReceivingThread

protected abstract void removeReceivingThread(URL url)
Stop receiving at url, and remove the receiving thread.


getSendingThread

protected abstract CommunicationThread getSendingThread(URL url)
Returns:
A CommunicationThread that can be used for sending a message to the given URL.

isBroadcast

protected abstract boolean isBroadcast(URL url)
Returns:
true if the URL is a broadcast address (or multicast, depending on the protocol), false if not.

messageReceived

protected void messageReceived(Message message)
This method is called every time a message is received. It may be overridden by subclasses that want to do more than just let the message be distributed to registered receivers.


getDefaultGroupAddresses

public abstract URL[] getDefaultGroupAddresses()
Returns:
The default broadcast addresses for group communication.

raiseErrorEvent

protected void raiseErrorEvent(MALErrorEvent mee)
When unhandled errors occur, concrete implementations of this class should call this method for notifying error handlers about the events.


getProtocol

public static java.lang.String getProtocol(URL url)

getHost

public static java.lang.String getHost(URL url)

getPort

public static int getPort(URL url)
Returns:
The port of the protocol-specific part of the URL, or -1 if not specified.

getProtocolSpecificUrl

public static URL getProtocolSpecificUrl(URL url)
Returns:
The protocol-specific part of the URL (the URL that can be used for addressing the device).

getSelector

public static Selector getSelector(URL url)
Returns:
Selector part of the URL, or null if it is not set.