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
`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
`protected` `SAMHandler(SocketChannel s, int verMajor, int verMinor, Properties i2cpProps)` SAMHandler constructor (to be called by subclasses)

### Method Summary

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