net.i2p.sam

## Class SAMHandler

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

- All Implemented Interfaces:
    Runnable
  Direct Known Subclasses:
    SAMv1Handler

      public abstract class SAMHandler
      extends Object
      implements Runnable

  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.
  Author:
    human

- - ### Field Summary

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

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `closeClientSocket()` Close the socket connected to the SAM client.
    `protected SocketChannel` | `getClientSocket()` Get the input stream 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()`
    `void` | `setBridge(SAMBridge 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
    `String` | `toString()` Get a string describing the handler.
    `protected void` | `writeBytes(ByteBuffer data)` Write a byte array on the handler's socket.
    `static void` | `writeBytes(ByteBuffer data, SocketChannel out)`
    `protected boolean` | `writeString(String str)` Write a string to the handler's socket.
    `static boolean` | `writeString(String str, SocketChannel out)`

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

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

- - ### Field Detail

    - #### thread

          protected I2PAppThread thread

    - #### bridge

          protected SAMBridge bridge

    - #### socket

          protected SocketChannel socket

    - #### verMajor

          protected int verMajor

    - #### verMinor

          protected int verMinor

    - #### i2cpProps

          protected Properties i2cpProps

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

  - ### Constructor Detail

    - #### SAMHandler

          protected SAMHandler(SocketChannel s,
                    int verMajor,
                    int verMinor,
                    Properties i2cpProps)
                        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

    - #### startHandling

          public final void startHandling()

      Start handling the SAM connection, detaching an handling thread.

    - #### setBridge

          public void setBridge(SAMBridge bridge)

    - #### handle

          protected abstract void handle()

      Actually handle the SAM protocol.

    - #### getClientSocket

          protected final SocketChannel getClientSocket()

      Get the input stream of the socket connected to the SAM client
      Returns:
        input stream
      Throws:
        `IOException`

    - #### 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`

    - #### writeBytes

          public static void writeBytes(ByteBuffer data,
                        SocketChannel out)
                                 throws IOException

      Throws:
        `IOException`

    - #### 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

    - #### 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)

    - #### closeClientSocket

          protected final void closeClientSocket()
                                          throws IOException

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

    - #### stopHandling

          public final void stopHandling()

      Stop the SAM handler

    - #### shouldStop

          protected final boolean shouldStop()

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

    - #### toString

          public final String toString()

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

    - #### run

          public final void run()

      Specified by:
        `run` in interface `Runnable`