peer2me.framework
Class FrameworkFrontEnd

java.lang.Object
  extended bypeer2me.framework.FrameworkFrontEnd
All Implemented Interfaces:
Framework

public class FrameworkFrontEnd
extends java.lang.Object
implements Framework

This is the main class of the Peer2Me framework. It manages and connects the resources and functions of the framework. It also handles all communication and interaction with the MIDlets running the framework.

Author:
Torbjørn Vatn & Steinar A. Hestnes

Method Summary
 void connectToNodes(java.lang.String[] addresses)
          This method establishes a connection to the chosen nodes.
 java.util.Enumeration getFileList(java.lang.String root)
          This method returns a list of the files in the given root directory on the device
 Group getGroup()
          This method returns the local representation of the group.
static Framework getInstance(FrameworkListener midlet)
          This method creates an instance of FrameworkFrontEnd and returns it as a reference of type Framework.
 Node getLocalNode()
          This method returns a reference to the local node.
 void initFramework(java.lang.String nodeName, java.lang.String midletName, java.lang.String preferredNetwork)
          This method initiates the framework, and is the first method that should be run after getting a instance of the framework.
 void notifyAboutException(java.lang.String location, java.lang.Exception exception)
          This method passes on the Exception notice from the Log to the MIDlet.
 void notifyAboutFoundNode(java.lang.String address, java.lang.String remoteNodeName)
          This method is called from the nodeFound() method in the Network class whenever a node is found
 void notifyAboutLostNode(java.lang.String address)
          This method removes a lost node from the group.
 void notifyAboutReceivedFilePackage(FilePackage filePackage)
          This method is called from NodeConnection.processIncomingData() whenever a file package is received from a remote node.
 void notifyAboutReceivedGroupSyncPackage(GroupSyncPackage groupSyncPackage)
          This method is called from NodeConnection.processIncomingData() whenever a groupSyncPackage is received from a remote node.
 void notifyAboutReceivedTextPackage(TextPackage textPackage)
          This method is called from NodeConnection.processIncomingData() whenever a text package is received from a remote node.
 void sendFilePackage(java.lang.String[] recipients, java.lang.String filePath)
          This method is used by the MIDlet to send a file package over the network.
 void sendTextPackage(java.lang.String[] recipients, java.lang.String textMessage)
          This method is used by the MIDlet to send a text package over the network.
 void shutdownFramework()
          This method shuts down the framework and closes all the open network connections and streams.
 void startNodeSearch()
          This method starts a search for devices running the same MIDlet.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static Framework getInstance(FrameworkListener midlet)
This method creates an instance of FrameworkFrontEnd and returns it as a reference of type Framework. This is the only method that can be called directly from the MIDlet on the FrameworkFrontEnd. The MIDlet is restricted to only use the methods specified in the Framework interface.

Parameters:
midlet - A reference to the MIDlet (The MIDlet must implement the FrameworkListener interface).
Returns:
A reference to the Framework

initFramework

public void initFramework(java.lang.String nodeName,
                          java.lang.String midletName,
                          java.lang.String preferredNetwork)
                   throws java.lang.ClassNotFoundException,
                          java.lang.IllegalAccessException,
                          java.lang.InstantiationException,
                          java.io.IOException,
                          java.lang.Exception
This method initiates the framework, and is the first method that should be run after getting a instance of the framework. It initiates the fundamental services offered by the framework.

Specified by:
initFramework in interface Framework
Parameters:
nodeName - The name of the user of the MIDlet.
midletName - The name of the MIDlet, eventually translated into a ServiceID used to find other devices running the same MIDlet.
preferredNetwork - Deciding which network implementation to use.
Throws:
java.lang.ClassNotFoundException - The input preferredNetwork is invalid
java.lang.IllegalAccessException - The input preferredNetwork is invalid
java.lang.InstantiationException - The input preferredNetwork is invalid
java.io.IOException - Error initiating framework
java.lang.Exception - Error initiating framework

shutdownFramework

public void shutdownFramework()
This method shuts down the framework and closes all the open network connections and streams. It should be called from the MIDlet before closing, to clean up the network connections.

Specified by:
shutdownFramework in interface Framework

getGroup

public Group getGroup()
This method returns the local representation of the group. It is called from ConnectionListener.run() or Network.nodeFound() when a remote node is found and should be added to the group.

Returns:
The local representation of the group

startNodeSearch

public void startNodeSearch()
                     throws java.io.IOException
This method starts a search for devices running the same MIDlet. When such a device is found, the notifyAboutFoundNode() method in this class is called.

Specified by:
startNodeSearch in interface Framework
Throws:
java.io.IOException - Thrown if the search crashes

connectToNodes

public void connectToNodes(java.lang.String[] addresses)
This method establishes a connection to the chosen nodes. After updating the local group, it synchronizes the groups on all other participating nodes. The method should be called from the MIDlet.

Specified by:
connectToNodes in interface Framework
Parameters:
addresses - The addresses to the nodes to connect to.

getLocalNode

public Node getLocalNode()
This method returns a reference to the local node.

Returns:
An object representing the local node

sendTextPackage

public void sendTextPackage(java.lang.String[] recipients,
                            java.lang.String textMessage)
This method is used by the MIDlet to send a text package over the network. When the package terminates to the recipients, the notifyAboutReceivedTextPackage() method in this class is run.

Specified by:
sendTextPackage in interface Framework
Parameters:
recipients - A list containing the addresses of the recipient nodes
textMessage - The text to be sent

sendFilePackage

public void sendFilePackage(java.lang.String[] recipients,
                            java.lang.String filePath)
This method is used by the MIDlet to send a file package over the network. When the package terminates to the recipients, the notifyAboutReceivedFilePackage() method in this class is run.

Specified by:
sendFilePackage in interface Framework
Parameters:
recipients - A list containing the addresses of the recipient nodes
filePath - The path of the file to send

getFileList

public java.util.Enumeration getFileList(java.lang.String root)
This method returns a list of the files in the given root directory on the device

Specified by:
getFileList in interface Framework
Parameters:
root - The path to the root directory
Returns:
A Enumeration containing the names of the files in the root directory

notifyAboutFoundNode

public void notifyAboutFoundNode(java.lang.String address,
                                 java.lang.String remoteNodeName)
This method is called from the nodeFound() method in the Network class whenever a node is found

Parameters:
address - The network address of the node
remoteNodeName - The name of the found remote node

notifyAboutLostNode

public void notifyAboutLostNode(java.lang.String address)
This method removes a lost node from the group. It is called from Network.sendDataPackage() if a node is unreachable. After removing the node, the groups on all other nodes become synchronized.

Parameters:
address - The address to the lost node

notifyAboutException

public void notifyAboutException(java.lang.String location,
                                 java.lang.Exception exception)
This method passes on the Exception notice from the Log to the MIDlet. This will be done in cases where exceptions occure in threads and cannot be thrown in the usual way.

Parameters:
location - The location (class and method) where the Exception occured
exception - The actual Exception

notifyAboutReceivedGroupSyncPackage

public void notifyAboutReceivedGroupSyncPackage(GroupSyncPackage groupSyncPackage)
This method is called from NodeConnection.processIncomingData() whenever a groupSyncPackage is received from a remote node. The method processes the package, logs the event, and updates the group.

Parameters:
groupSyncPackage - The received groupSyncPackage.

notifyAboutReceivedTextPackage

public void notifyAboutReceivedTextPackage(TextPackage textPackage)
This method is called from NodeConnection.processIncomingData() whenever a text package is received from a remote node. It processes the package, logs the event, and notifies the midlet.

Parameters:
textPackage - The received text package.

notifyAboutReceivedFilePackage

public void notifyAboutReceivedFilePackage(FilePackage filePackage)
This method is called from NodeConnection.processIncomingData() whenever a file package is received from a remote node. It processes the package, logs the event, and notifies the midlet.

Parameters:
filePackage - The received file package.