net.i2p.sam

## Class SAMHandler

- java.lang.Object
- - net.i2p.sam.SAMHandler

- All Implemented Interfaces:
    Runnable, Handler
  Direct Known Subclasses:
    SAMv1Handler

      abstract class SAMHandler
      extends Object
      implements Runnable, Handler

  Base class for SAM protocol handlers. It implements common methods, but is not able to actually parse the protocol itself: this task is delegated to subclasses.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `_log`
    `protected SAMBridge` | `bridge`
    `protected Properties` | `i2cpProps` I2CP options configuring the I2CP connection (port, host, numHops, etc)
    `protected SocketChannel` | `socket`
    `protected boolean` | `stopHandler`
    `protected Object` | `stopLock`
    `protected I2PAppThread` | `thread`
    `int` | `verMajor`
    `int` | `verMinor`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SAMHandler(SocketChannel s, int verMajor, int verMinor, Properties i2cpProps, SAMBridge parent)` SAMHandler constructor (to be called by subclasses)

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `closeClientSocket()` Close the socket connected to the SAM client.
    `protected SocketChannel` | `getClientSocket()` Get the channel of the socket connected to the SAM client
    `protected Object` | `getWriteLock()` If you're crazy enough to write to the raw socket, grab the write lock with getWriteLock(), synchronize against it, and write to the getOut()
    `protected abstract void` | `handle()` Actually handle the SAM protocol.
    `void` | `run()` Register with the bridge, call handle(), unregister with the bridge.
    `protected boolean` | `shouldStop()` Should the handler be stopped?
    `void` | `startHandling()` Start handling the SAM connection, detaching an handling thread.
    `void` | `stopHandling()` Stop the SAM handler, close the client socket, unregister with the bridge.
    `String` | `toString()` Get a string describing the handler.
    `protected void` | `writeBytes(ByteBuffer data)` Write a byte array on the handler's socket.
    `protected boolean` | `writeString(String str)` Write a string to the handler's socket.
    `static boolean` | `writeString(String str, SocketChannel out)` Unsynchronized, use with caution

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### _log

          protected final Log _log

    - #### bridge

          protected final SAMBridge bridge

    - #### i2cpProps

          protected final Properties i2cpProps

      I2CP options configuring the I2CP connection (port, host, numHops, etc)

    - #### socket

          protected final SocketChannel socket

    - #### stopHandler

          protected boolean stopHandler

    - #### stopLock

          protected final Object stopLock

    - #### thread

          protected I2PAppThread thread

    - #### verMajor

          public final int verMajor

    - #### verMinor

          public final int verMinor

  - ### Constructor Detail

    - #### SAMHandler

          protected SAMHandler(SocketChannel s,
                               int verMajor,
                               int verMinor,
                               Properties i2cpProps,
                               SAMBridge parent)
                        throws IOException

      SAMHandler constructor (to be called by subclasses)
      Parameters:
        `s` - Socket attached to a SAM client
        `verMajor` - SAM major version to manage
        `verMinor` - SAM minor version to manage
        `i2cpProps` - properties to configure the I2CP connection (host, port, etc)
      Throws:
        `IOException`

  - ### Method Detail

    - #### closeClientSocket

          protected final void closeClientSocket()
                                          throws IOException

      Close the socket connected to the SAM client.
      Throws:
        `IOException`

    - #### getClientSocket

          protected final SocketChannel getClientSocket()

      Get the channel of the socket connected to the SAM client
      Returns:
        channel

    - #### getWriteLock

          protected Object getWriteLock()

      If you're crazy enough to write to the raw socket, grab the write lock with getWriteLock(), synchronize against it, and write to the getOut()
      Returns:
        socket Write lock object

    - #### handle

          protected abstract void handle()

      Actually handle the SAM protocol.

    - #### run

          public final void run()

      Register with the bridge, call handle(), unregister with the bridge.
      Specified by:
        `run` in interface `Runnable`

    - #### shouldStop

          protected final boolean shouldStop()

      Should the handler be stopped?
      Returns:
        True if the handler should be stopped, false otherwise

    - #### startHandling

          public final void startHandling()

      Start handling the SAM connection, detaching an handling thread.

    - #### stopHandling

          public void stopHandling()

      Stop the SAM handler, close the client socket, unregister with the bridge.
      Specified by:
        `stopHandling` in interface `Handler`

    - #### toString

          public final String toString()

      Get a string describing the handler.
      Overrides:
        `toString` in class `Object`
      Returns:
        A String describing the handler;

    - #### writeBytes

          protected final void writeBytes(ByteBuffer data)
                                   throws IOException

      Write a byte array on the handler's socket. This method must always be used when writing data, unless you really know what you're doing.
      Parameters:
        `data` - A byte array to be written
      Throws:
        `IOException`

    - #### writeString

          protected final boolean writeString(String str)

      Write a string to the handler's socket. This method must always be used when writing strings, unless you really know what you're doing.
      Parameters:
        `str` - A byte array to be written
      Returns:
        True if the string was successfully written, false otherwise

    - #### writeString

          public static boolean writeString(String str,
                                            SocketChannel out)

      Unsynchronized, use with caution
      Returns:
        success