blackboard
Class BlackBoard

java.lang.Object
  blackboard.BlackBoard

All Implemented Interfaces:

Collection, Set

public class BlackBoard

extends Object

implements Set

The BlackBoard stores all the information on the current network in a controlled fashion. Only one thread can write to a given node at any particular time, but multiple threads can read each node simultaneously. This is accomplished through the LanNode construction.

The LanNode contains very little data directly, but instead is a wrapper for a lot of references to actual data. By this method, anyone with a copy of a particular LanNode will actually be reading the same thing as everyone else with a copy regardless of which one has something written to it. Also, the LanNode has a mutual exclusion lock to prevent two different thread from writing to it simultaneously. In fact, only one thread may have a writable copy of a LanNode at any given moment in time and the only process that can create an unlocked LanNode is the BlackBoard. (there is, however, an exception with the FrontEnd information since all writing is contained within one portion of the program.)

The BlackBoard has only one constructor because one instance of it will be created by the main method and will be passed to both the FrontEnd and the BackEnd. If the FrontEnd has a feature to load and save nodes then it should be done through the addAll and either the toArray method or the toHashSet method respectively.

The BlackBoard is completely thread safe, but you still need to add a synchronized block if you wish to use the iterator. For example...

 synchronized(blackboard) {
 Iterator i = blackboard.iterator(); // Must be in the synchronized block
 while (i.hasNext())
 foo(i.next());
 }
 

See Also:

LanNode

Constructor Summary

BlackBoard()
Creates a new instance of BlackBoard.

Method Summary

boolean	add(Object o) This will add a LanNode to the BlackBoard.
boolean	addAll(Collection c) Adds a Collection of LanNodes to the BlackBoard.
void	checkIn(LanNode node) This method checksIn the passed node into the BlackBoard; If it doesn't exists in the BlackBoard then it will added.
void	clear() Empties the entire BlackBoard of all contents.
boolean	contains(Object o) Returns true if this set contains the specified element.
boolean	containsAll(Collection c) Returns true if this set contains all of the elements of the specified collection.
protected void	finalize() Decrements the blackboardcount so another BlackBoard may be created.
Set	getAllForUpdate() Returns all LanNodes that have not been either deleted or previously checked out and also checks them out for writing.
LanNode	getForUpdate() Returns writable LanNode (ie checked-out), so you must return it afterwards (via add or checkIn).
LanNode	getIpForUpdate(InetAddress ip) Returns a LanNode for update by the backend according to the IP address passed to this method.
int	getPingInterval() Getter for property pingInterval.
int	getPollingThreadCount() Getter for property pollingThreadCount.
String	getSnmpCommunity() Returns the current community used for SNMP gets by the backend.
boolean	isEmpty() Returns true if this set contains no elements.
boolean	isSnmpPollingOn() Getter for property snmpPolling.
Iterator	iterator() The BlackBoard is completely thread safe, but you still need to add a synchronized block if you wish to use the iterator.
void	pauseMonitoring() The frontend calls this method to stop the backend from updating nodes in the BlackBoard.
boolean	remove(Object o) Removes the LanNode specified and marks it as deleted.
boolean	removeAll(Collection c) Removes from this set all of its elements that are contained in the specified collection.
boolean	retainAll(Collection c) NOT IMPLEMENTED; WILL THROW EXCEPTION.
void	setPingInterval(int pingInterval) Setter for property pingInterval.
void	setPollingThreadCount(int pollingThreadCount) Setter for property pollingThreadCount.
void	setReferenceToBackEnd(backEnd x) Should only be called once at the beginning of the program to allow the BlackBoard to call the backend for the updateNow method.
void	setSnmpCommunity(String snmpCommunity) Sets the current SNMP community for SNMP gets.
void	setSnmpPolling(boolean snmpPolling) Setter for property snmpPolling.
int	size() Returns the number of LanNodes in the BlackBoard.
Object[]	toArray() Returns an array containing all of the elements in this set.
Object[]	toArray(Object[] a) Returns an array containing all of the elements in this set; the runtime type of the returned array is that of the specified array.
HashSet	toHashSet() Returns a shallow copy of the HashSet contained within the BlackBoard.
void	unpauseMonitoring() Calling this method after calling pauseMonitoring() will restart polling.
void	updateNow(LanNode x) Updates the LanNode passed to it by requesting an update of the backend and when the backend checks the node back in the Observable's notifyObservers method will be called.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Set

equals, hashCode

Constructor Detail

BlackBoard

public BlackBoard()

Creates a new instance of BlackBoard. Only one instance of BlackBoard is allowed at any given time.

Method Detail

add

public boolean add(Object o)

This will add a LanNode to the BlackBoard. If you try to add a node that's already in the BlackBoard then this method will return false.

You may only add a LanNode to the BlackBoard. If something other than a LanNode is passed then a ClassCastException is thrown.

If a node is added that's already included in the BlackBoard and was previously checked-out then add will simply check the node back in.

Trying to add a null will cause a NullPointerException to be thrown.

This method will return true if it was able to either add the node or check-in the node. If you try to add a node already contained and the copy you have is not a checked-out copy, then this method will return false and nothing will happen.

Specified by:

add in interface Set

Parameters:

o - A LanNode that you wish to be added to the BlackBoard

Returns:

returns true if added or checked-in, false otherwise

addAll

public boolean addAll(Collection c)

Adds a Collection of LanNodes to the BlackBoard. All members of the Collection must be LanNodes, and there may be no nulls. Also, if an empty Collection is passed then an IllegalArgumentException will be thrown.

This method always returns true if it returns properly.

Specified by:

addAll in interface Set

Parameters:

c - collection of LanNodes to be added to the BlackBoard

Returns:

always returns true.

Throws:

NullPointerException - if the Collection reference is null.

NullPointerException - if there's a null in the Collection.

IllegalArgumentException - if you passed an empty Collection.

ClassCastException - if there exists an element in the passed collection that is not a LanNode

clear

public void clear()

Empties the entire BlackBoard of all contents. All LanNodes contained within the BlackBoard will be marked as deleted and then removed from the BlackBoard

Specified by:

clear in interface Set

contains

public boolean contains(Object o)

Returns true if this set contains the specified element. More formally, returns true if and only if this set contains an element e such that (o==null ? e==null : o.equals(e)).

Specified by:

contains in interface Set

Parameters:

o - element whose presence in this set is to be tested.

Returns:

true if this set contains the specified element.

containsAll

public boolean containsAll(Collection c)

Returns true if this set contains all of the elements of the specified collection. If the specified collection is also a set, this method returns true if it is a subset of this set.

Specified by:

containsAll in interface Set

Parameters:

c - collection to be checked for containment in this set.

Returns:

if this set contains all of the elements of the specified collection.

Throws:

NullPointerException - if the Collection reference is null.

finalize

protected void finalize()
                 throws Throwable

Decrements the blackboardcount so another BlackBoard may be created. This method is probably not really necessary, but was included for completeness.

Throws:

Throwable - if Object.finalize() encounters an error.

isEmpty

public boolean isEmpty()

Returns true if this set contains no elements.

Specified by:

isEmpty in interface Set

Returns:

true if this set contains no elements.

iterator

public Iterator iterator()

The BlackBoard is completely thread safe, but you still need to add a synchronized block if you wish to use the iterator. For example...

 synchronized(blackboard) {
 Iterator i = blackboard.iterator(); // Must be in the synchronized block
 while (i.hasNext())
 foo(i.next());
 }
 

As an alternative, you can use the toArray method to get a copy of the current BlackBoard and not worry about it.

However, in both cases the LanNodes contained within the Array can still be changed so you'll want to synchronize each element as you come to them and also make sure that each node isn't already deleted.

NOTE: the iterator's remove() method has been changed to make sure that the effected LanNode has its deleted flag turned on.

Specified by:

iterator in interface Set

Returns:

an iterator over the elements in the BlackBoard.

remove

public boolean remove(Object o)

Removes the LanNode specified and marks it as deleted. If the object is not contained with in the BlackBoard then it will NOT mark the LanNode as deleted and will return false.

A null pointer or a non-LanNode will not cause a runtime error in this method.

Specified by:

remove in interface Set

Parameters:

o - LanNode to be removed from this set, if present.

Returns:

true if the set contained the specified element.

removeAll

public boolean removeAll(Collection c)

Removes from this set all of its elements that are contained in the specified collection.

Specified by:

removeAll in interface Set

Parameters:

c - collection that defines which elements will be removed from this set.

Returns:

true if this set changed as a result of the call.

Throws:

NullPointerException - if the Collection reference is null.

retainAll

public boolean retainAll(Collection c)

NOT IMPLEMENTED; WILL THROW EXCEPTION.

Retains only the elements in this set that are contained in the specified collection (optional operation). In other words, removes from this set all of its elements that are not contained in the specified collection. If the specified collection is also a set, this operation effectively modifies this set so that its value is the intersection of the two sets.

Specified by:

retainAll in interface Set

Parameters:

c - collection that defines which elements this set will retain.

Returns:

true if this collection changed as a result of the call.

size

public int size()

Returns the number of LanNodes in the BlackBoard.

Specified by:

size in interface Set

Returns:

the number of elements in the BlackBoard

toArray

public Object[] toArray()

Returns an array containing all of the elements in this set. Obeys the general contract of the Collection.toArray method.

Specified by:

toArray in interface Set

Returns:

an array containing the LanNodes in the BlackBoard.

toArray

public Object[] toArray(Object[] a)

Returns an array containing all of the elements in this set; the runtime type of the returned array is that of the specified array. Obeys the general contract of the Collection.toArray(Object[]) method.

Specified by:

toArray in interface Set

Parameters:

a - the array into which the elements of this set are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the LanNodes in the BlackBoard.

Throws:

ArrayStoreException - the runtime type of a is not a supertype of the runtime type of every element in this set.

NullPointerException - if the specified array is null.

toHashSet

public HashSet toHashSet()

Returns a shallow copy of the HashSet contained within the BlackBoard. This was added to the implementation to allow the FrontEnd to save the HashSet via Serialization.

Returns:

a complete HashSet of the LanNodes contained within the BlackBoard

See Also:

HashSet

checkIn

public void checkIn(LanNode node)

This method checksIn the passed node into the BlackBoard; If it doesn't exists in the BlackBoard then it will added.

Essentially, it does the same thing as add except that it does not need to check the type of the object or cast it. (minor speed improvement)

Parameters:

node - node to add or check-in to the BlackBoard.

Throws:

NullPointerException - if you try to checkIn a null.

getForUpdate

public LanNode getForUpdate()

Returns writable LanNode (ie checked-out), so you must return it afterwards (via add or checkIn). If there are no nodes or all have already been checked out then this method returns a null.

Returns:

returns writable LanNode for update

getIpForUpdate

public LanNode getIpForUpdate(InetAddress ip)
                       throws LanNodeAlreadyCheckedOut

Returns a LanNode for update by the backend according to the IP address passed to this method. If the LanNode is already being held by the backend then a LanNodeAlreadyCheckedOut exception is thrown. If the LanNode does not exist in the blackboard then a null is returned.

Parameters:

ip - IP address of node to be updated

Returns:

either the LanNode with the specified IP address or a null

Throws:

LanNodeAlreadyCheckedOut - if the node with the matching IP is already checked out then this exception is thrown

getAllForUpdate

public Set getAllForUpdate()

Returns all LanNodes that have not been either deleted or previously checked out and also checks them out for writing.

Returns:

Set of writable checked-out LanNodes.

isSnmpPollingOn

public boolean isSnmpPollingOn()

Getter for property snmpPolling.

Returns:

Value of property snmpPolling.

setSnmpPolling

public void setSnmpPolling(boolean snmpPolling)

Setter for property snmpPolling.

Parameters:

snmpPolling - New value of property snmpPolling.

getPingInterval

public int getPingInterval()

Getter for property pingInterval.

Returns:

Value of property pingInterval.

setPingInterval

public void setPingInterval(int pingInterval)

Setter for property pingInterval.

Parameters:

pingInterval - New value of property pingInterval.

getPollingThreadCount

public int getPollingThreadCount()

Getter for property pollingThreadCount.

Returns:

Value of property pollingThreadCount.

setPollingThreadCount

public void setPollingThreadCount(int pollingThreadCount)

Setter for property pollingThreadCount.

Parameters:

pollingThreadCount - New value of property pollingThreadCount.

pauseMonitoring

public void pauseMonitoring()

The frontend calls this method to stop the backend from updating nodes in the BlackBoard. This is accomplished in the BlackBoard by preventing nodes from being checked out by the backend.

unpauseMonitoring

public void unpauseMonitoring()

Calling this method after calling pauseMonitoring() will restart polling. This is accomplished by allowing the backend to again check out nodes for updating

setReferenceToBackEnd

public void setReferenceToBackEnd(backEnd x)

Should only be called once at the beginning of the program to allow the BlackBoard to call the backend for the updateNow method.

updateNow

public void updateNow(LanNode x)
               throws LanNodeIsDeleted

Updates the LanNode passed to it by requesting an update of the backend and when the backend checks the node back in the Observable's notifyObservers method will be called. If the LanNode is already checked out then the request will be ignored since the backend most likely already has the node and is updating it. This method also assumes that the LanNode has already been checked into the BlackBoard.

Throws:

LanNodeIsDeleted

getSnmpCommunity

public String getSnmpCommunity()

Returns the current community used for SNMP gets by the backend. This value will also be used by the MIB Browser as its default community setting.

Returns:

String containing the SNMP Community

setSnmpCommunity

public void setSnmpCommunity(String snmpCommunity)

Sets the current SNMP community for SNMP gets.

Parameters:

snmpCommunity - SNMP community to use