## 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 syhchronized 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 Link <graphics>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

Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details