com.bbn.openmap.layer.link
Class Link

java.lang.Object
  com.bbn.openmap.layer.link.Link

All Implemented Interfaces:

LinkConstants

Direct Known Subclasses:

ClientLink

public class Link
extends java.lang.Object
implements LinkConstants

The Link object is the main mechanism for communications between a LinkClient (most likely a LinkLayer) and a LinkServer. This class should only be used directly by a server - clients should use the ClientLink object. This object defines the communications that either side can make.

The ClientLink adds some control methods that the client should use. The client needs to make sure that several queries are not sent to the server at the same time. The ClientLink contains a lock that can be checked, and set. It is up to the client to manage the lock. The ClientLink also provides the method to close the link down, since it makes that decision. The server should remain connected until the client is finished. The server can request to be disconnected, however, and the ClientLink provides a method for the client to check if that request has been made.

Field Summary

protected LinkActionList	actionList Used to retrieve any potential gesture responses that came in over the link.
protected LinkActionRequest	actionRequest Used to retrieve any potential gesture queries that came in over the link.
protected char[]	charArray Used to read/create strings from off the input stream.
protected boolean	closeLink Set for the client, by the server, to indicate whether the socket should be closed.
protected java.io.DataInputStream	dis For incoming traffic.
protected LinkOutputStream	dos For outgoing traffic.
protected LinkGraphicList	graphicList Used to retrieve any potential graphics responses that came in over the link.
protected LinkGUIList	guiList Used to retrieve any potential GUI responses that came in over the link.
protected LinkGUIRequest	guiRequest Used to retrieve any potential GUI queries that came in over the link.
protected boolean	locked The lock.
protected LinkMapRequest	mapRequest Used to retrieve any potential graphics queries that came in over the link.
static int	MAX_HEADER_LENGTH The apparent maximum size of a header.
protected boolean	obeyCommandToExit Flag to control whether this side of the link will adhere to shutdown commands issued from other side of the link.
protected java.net.Socket	socket The socket used for the link.

Fields inherited from interface com.bbn.openmap.layer.link.LinkConstants

ACTION_REQUEST_HEADER, ACTIONS_HEADER, ARC_HEADER, BITMAP_HEADER, CIRCLE_HEADER, CLOSE_LINK_HEADER, ELLIPSE_HEADER, END_SECTION, END_TOTAL, GRAPHIC_HEADER, GRAPHICS_HEADER, GRID_HEADER, GUI_HEADER, GUI_REQUEST_HEADER, HUH_HEADER, LINE_HEADER, LINK_VERSION, MAP_REQUEST_HEADER, PING_REQUEST_HEADER, PING_RESPONSE_HEADER, POINT_HEADER, POLY_HEADER, RASTER_HEADER, RECTANGLE_HEADER, SHUTDOWN_HEADER, TEXT_HEADER, UNKNOWN, UPDATE_GRAPHICS, UPDATE_GUI, UPDATE_MAP

Constructor Summary

Link(java.net.Socket socket)
Open up a link over a socket.

Method Summary

void	cleanUp() Should be called by the server and/or client to release resources when the link is through being used.
int	clearBytesWritten() Reset the bytes written count to 0.
void	end(java.lang.String endType) The method that needs to be called at the end of a request/response or section.
boolean	getAcceptCommandToExit()
LinkActionList	getActionList() After a readAndParse() has been called on a link, this can be called to retrieve the gesture response.
LinkActionRequest	getActionRequest() After a readAndParse() has been called on a link, this can be called to retrieve a gesture notification/request, if one was sent.
int	getBytesWritten() Returns the number of bytes written since the last clearBytesWritten() call.
java.io.DataInput	getDIS() This method complements getDOS().
java.io.DataOutput	getDOS() This method is provided for those who want to optimize how they write the graphical objects to the output stream.
LinkGraphicList	getGraphicList() After a readAndParse() has been called on a link, this can be called to retrieve graphics in an LinkOMGraphicList, if any graphics were sent.
LinkGUIList	getGUIList() After a readAndParse() has been called on a link, this can be called to retrieve the GUI response, if any GUI components were sent.
LinkGUIRequest	getGUIRequest() After a readAndParse() has been called on a link, this can be called to retrieve a gesture notification/request, if one was sent.
LinkMapRequest	getMapRequest() After a readAndParse() has been called on a link, this can be called to retrieve a graphics request, if one was sent.
boolean	isLocked() Other threads can check to see if the link is in use.
void	readAndParse() Called to begin reading the information coming off the link.
void	readAndParse(Projection proj, OMGridGenerator generator) Called to begin reading the information coming off the link.
void	readAndParse(Projection proj, OMGridGenerator generator, Layer layer) Called to begin reading the information coming off the link.
protected java.lang.String	readDelimiter(boolean returnString) readDelimiter is a function designed to read a header string off the data input stream in the Link object.
boolean	setLocked(boolean set) Set the lock.
void	setObeyCommandToExit(boolean value)
void	start(java.lang.String messageHeader) The method to call at the beginning of a request or response.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_HEADER_LENGTH

public static final int MAX_HEADER_LENGTH

The apparent maximum size of a header.

See Also:

Constant Field Values

dos

protected LinkOutputStream dos

For outgoing traffic.

dis

protected java.io.DataInputStream dis

For incoming traffic.

charArray

protected char[] charArray

Used to read/create strings from off the input stream.

closeLink

protected boolean closeLink

Set for the client, by the server, to indicate whether the socket should be closed. By default, this will be false, Used when the server wants to run in a stateless mode, and doesn't care to maintain a connection with the client. It's included in the Link object because the server knows about it and sets it in the client.

mapRequest

protected LinkMapRequest mapRequest

Used to retrieve any potential graphics queries that came in over the link.

graphicList

protected LinkGraphicList graphicList

Used to retrieve any potential graphics responses that came in over the link.

actionRequest

protected LinkActionRequest actionRequest

Used to retrieve any potential gesture queries that came in over the link.

actionList

protected LinkActionList actionList

Used to retrieve any potential gesture responses that came in over the link.

guiRequest

protected LinkGUIRequest guiRequest

Used to retrieve any potential GUI queries that came in over the link.

guiList

protected LinkGUIList guiList

Used to retrieve any potential GUI responses that came in over the link.

socket

protected java.net.Socket socket

The socket used for the link. Kept for convenience.

locked

protected boolean locked

The lock. This should only be changed within a synchronized block of code, synchronized on the link object.!! Otherwise, race conditions can result.

obeyCommandToExit

protected boolean obeyCommandToExit

Flag to control whether this side of the link will adhere to shutdown commands issued from other side of the link. False by default.

Constructor Detail

Link

public Link(java.net.Socket socket)
     throws java.io.IOException

Open up a link over a socket.

Parameters:

socket - the socket to open the Link on.

Throws:

java.io.IOException

Method Detail

cleanUp

public void cleanUp()

Should be called by the server and/or client to release resources when the link is through being used.

start

public void start(java.lang.String messageHeader)
           throws java.io.IOException

The method to call at the beginning of a request or response. It writes the header given to the link. This header is expected on the other side of the link.

Parameters:

messageHeader - Header string, defined in the Link object, that describes the tranmission.

Throws:

java.io.IOException

end

public void end(java.lang.String endType)
         throws java.io.IOException

The method that needs to be called at the end of a request/response or section. This places the END_TOTAL symbol on the link to let the other side know that the transmission is done, and it also flushes the output stream buffer.

Parameters:

endType - use END_SECTION if you want to add more types of responses. Use END_TOTAL at the end of the total transmission.

Throws:

java.io.IOException

readAndParse

public void readAndParse()
                  throws java.io.IOException

Called to begin reading the information coming off the link. Since the information can be coming in different sections, this method figures out how to read the different sections and get ready for requests on what was read. After the link is read, you can then request the link to find out what was sent back - for graphics, GUI components, or actions. When this method is called, the link resets the objects that are returned by getGraphics(), getGUI and getActions(). These methods are meant to be used after read() to find out what was returned.

Throws:

java.io.IOException

readAndParse

public void readAndParse(Projection proj,
                         OMGridGenerator generator)
                  throws java.io.IOException

Called to begin reading the information coming off the link.

Parameters:

proj - a projection for graphics

generator - an OMGridGenerator that knows how to render grid objects.

Throws:

java.io.IOException

readAndParse

public void readAndParse(Projection proj,
                         OMGridGenerator generator,
                         Layer layer)
                  throws java.io.IOException

Called to begin reading the information coming off the link.

Parameters:

proj - pass in a projection if you are expecting graphics to arrive, and they will be projected as they come off the link.

generator - an OMGridGenerator that knows how to render grid objects.

layer - a layer that is interested in gesture reactions.

Throws:

java.io.IOException

setObeyCommandToExit

public void setObeyCommandToExit(boolean value)

getAcceptCommandToExit

public boolean getAcceptCommandToExit()

getMapRequest

public LinkMapRequest getMapRequest()

After a readAndParse() has been called on a link, this can be called to retrieve a graphics request, if one was sent.

Returns:

LinkMapRequest containing the request.

getGraphicList

public LinkGraphicList getGraphicList()

After a readAndParse() has been called on a link, this can be called to retrieve graphics in an LinkOMGraphicList, if any graphics were sent.

Returns:

GraphicLinkRsponse containing the information. If no graphics were sent the list will be empty.

getActionRequest

public LinkActionRequest getActionRequest()

After a readAndParse() has been called on a link, this can be called to retrieve a gesture notification/request, if one was sent.

Returns:

LinkActionRequest containing the request.

getActionList

public LinkActionList getActionList()

After a readAndParse() has been called on a link, this can be called to retrieve the gesture response.

Returns:

LinkActionList containing the information.

getGUIRequest

public LinkGUIRequest getGUIRequest()

After a readAndParse() has been called on a link, this can be called to retrieve a gesture notification/request, if one was sent.

Returns:

LinkGUIRequest containing the request.

getGUIList

public LinkGUIList getGUIList()

After a readAndParse() has been called on a link, this can be called to retrieve the GUI response, if any GUI components were sent.

readDelimiter

protected java.lang.String readDelimiter(boolean returnString)
                                  throws java.io.IOException,
                                         java.lang.ArrayIndexOutOfBoundsException

readDelimiter is a function designed to read a header string off the data input stream in the Link object. It expects that the next byte off the link will be a '<' in the stream, and then reads through the stream until it finds the '>' expected at the end of the string. It will also return a string version of END_TOTAL or END_SECTION if it is encountered instead. If desired, an intern version of the string is returned.

Parameters:

returnString - if true, an intern String version of the characters is returned.

Throws:

java.io.IOException

java.lang.ArrayIndexOutOfBoundsException

isLocked

public boolean isLocked()

Other threads can check to see if the link is in use.

Returns:

true if link in use and unavailable.

setLocked

public boolean setLocked(boolean set)

Set the lock. Should only be called in a synchronized block of code, where you have control over the link.

Parameters:

set - true if the lock should be turned on, false if the link should be released.

getDOS

public java.io.DataOutput getDOS()

This method is provided for those who want to optimize how they write the graphical objects to the output stream. Look in the LinkGraphics API to find out the order of the pieces for each graphic type. Not recommended for the faint of heart.

getDIS

public java.io.DataInput getDIS()

This method complements getDOS().

getBytesWritten

public int getBytesWritten()

Returns the number of bytes written since the last clearBytesWritten() call.

clearBytesWritten

public int clearBytesWritten()

Reset the bytes written count to 0.

Returns:

the old byte count