Package org.eclipse.net4j.signal

## Class SignalProtocol<INFRA_STRUCTURE>

- java.lang.Object
- - org.eclipse.net4j.util.event.Notifier
  - - org.eclipse.net4j.util.lifecycle.Lifecycle
    - - org.eclipse.spi.net4j.Protocol<INFRA_STRUCTURE>
      - - org.eclipse.net4j.signal.SignalProtocol<INFRA_STRUCTURE>

- All Implemented Interfaces:
    `IBufferHandler`, `ILocationAware`, `IProtocol<INFRA_STRUCTURE>`, `IProtocol2<INFRA_STRUCTURE>`, `ISignalProtocol<INFRA_STRUCTURE>`, `org.eclipse.net4j.util.concurrent.IExecutorServiceProvider`, `org.eclipse.net4j.util.event.INotifier`, `org.eclipse.net4j.util.event.INotifier.INotifier2`, `org.eclipse.net4j.util.lifecycle.IDeactivateable`, `org.eclipse.net4j.util.lifecycle.ILifecycle`, `org.eclipse.net4j.util.lifecycle.ILifecycle.DeferrableActivation`, `org.eclipse.net4j.util.security.IUserAware`
  Direct Known Subclasses:
    `AuthenticatingSignalProtocol`, `HeartBeatProtocol`, `HeartBeatProtocol.Server`

      public class SignalProtocol<INFRA_STRUCTURE>
      extends Protocol<INFRA_STRUCTURE>
      implements ISignalProtocol<INFRA_STRUCTURE>

  The default implementation of a `signal protocol`.

  On the `receiver side(s)` of protocol the `createSignalReactor()` method has to be overridden to create appropriate peer instances for incoming `signals`.

  Author:
    Eike Stepper

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `SignalProtocol.InvalidSignalIDException` |
    `static class` | `SignalProtocol.TimeoutChangedEvent` | An `event` fired from a `signal protocol` when the protocol `timeout` has been changed.

    - ### Nested classes/interfaces inherited from interface org.eclipse.net4j.util.lifecycle.ILifecycle

      `org.eclipse.net4j.util.lifecycle.ILifecycle.DeferrableActivation`

    - ### Nested classes/interfaces inherited from interface org.eclipse.net4j.ILocationAware

      `ILocationAware.Location`

    - ### Nested classes/interfaces inherited from interface org.eclipse.net4j.util.event.INotifier

      `org.eclipse.net4j.util.event.INotifier.INotifier2`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static long` | `COMPRESSED_STRINGS_ACKNOWLEDGE_TIMEOUT` |
    `static short` | `SIGNAL_ACKNOWLEDGE_COMPRESSED_STRINGS` |
    `static short` | `SIGNAL_MONITOR_CANCELED` |
    `static short` | `SIGNAL_MONITOR_PROGRESS` |
    `static short` | `SIGNAL_REMOTE_EXCEPTION` |
    `static short` | `SIGNAL_SET_TIMEOUT` |

    - ### Fields inherited from class org.eclipse.net4j.util.lifecycle.Lifecycle

      `USE_LABEL`

    - ### Fields inherited from interface org.eclipse.net4j.protocol.IProtocol2

      `UNSPECIFIED_VERSION`

    - ### Fields inherited from interface org.eclipse.net4j.signal.ISignalProtocol

      `DEFAULT_TIMEOUT, NO_TIMEOUT`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SignalProtocol​(java.lang.String type)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addStreamWrapper​(org.eclipse.net4j.util.io.IStreamWrapper streamWrapper)` |
    `void` | `close()` |
    `protected SignalReactor` | `createSignalReactor​(short signalID)` | Returns a new signal instance to serve the given signal ID or `null` if the signal ID is invalid/unknown for this protocol.
    `protected void` | `doBeforeDeactivate()` |
    `protected void` | `doDeactivate()` |
    `org.eclipse.net4j.util.io.IStreamWrapper` | `getStreamWrapper()` |
    `protected org.eclipse.net4j.util.io.StringCompressor` | `getStringCompressor()` |
    `long` | `getTimeout()` |
    `void` | `handleBuffer​(IBuffer buffer)` | Handles a given (incoming) buffer.
    `protected void` | `handleChannelDeactivation()` |
    `protected boolean` | `isSendingTimeoutChanges()` | Returns `true` by default, override to change this behavior.
    `IChannel` | `open​(IConnector connector)` |
    `protected SignalReactor` | `provideSignalReactor​(short signalID)` |
    `void` | `setStreamWrapper​(org.eclipse.net4j.util.io.IStreamWrapper streamWrapper)` |
    `void` | `setTimeout​(long timeout)` | Equivalent to calling SignalProtocol.setTimeout(timeout, false).
    `boolean` | `setTimeout​(long timeout, boolean useOldTimeoutToSendNewOne)` | Update the timeout used for signal end of stream waiting time.
    `java.lang.String` | `toString()` |
    `boolean` | `waitForSignals​(long timeout)` |

    - ### Methods inherited from class org.eclipse.spi.net4j.Protocol

      `doBeforeActivate, getBufferProvider, getChannel, getExecutorService, getInfraStructure, getLocation, getType, getUserID, getVersion, isClient, isServer, setChannel, setExecutorService, setInfraStructure, setUserID`

    - ### Methods inherited from class org.eclipse.net4j.util.lifecycle.Lifecycle

      `activate, checkActive, checkArg, checkArg, checkInactive, checkNull, checkState, checkState, deactivate, deferredActivate, doActivate, doAfterActivate, dump, getLifecycleState, isActive, isDeferredActivation`

    - ### Methods inherited from class org.eclipse.net4j.util.event.Notifier

      `addListener, addUniqueListener, fireEvent, fireEvent, fireEvent, fireThrowable, firstListenerAdded, getListeners, getNotificationService, hasListener, hasListeners, lastListenerRemoved, listenerAdded, listenerRemoved, removeListener`

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

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

    - ### Methods inherited from interface org.eclipse.net4j.ILocationAware

      `getLocation, isClient, isServer`

    - ### Methods inherited from interface org.eclipse.net4j.util.event.INotifier

      `addListener, getListeners, hasListeners, removeListener`

    - ### Methods inherited from interface org.eclipse.net4j.protocol.IProtocol

      `getBufferProvider, getChannel, getExecutorService, getInfraStructure, getType, setChannel, setExecutorService, setInfraStructure`

    - ### Methods inherited from interface org.eclipse.net4j.util.security.IUserAware

      `getUserID`

- - ### Field Detail

    - #### COMPRESSED_STRINGS_ACKNOWLEDGE_TIMEOUT

          public static final long COMPRESSED_STRINGS_ACKNOWLEDGE_TIMEOUT

      Since:
        4.7

    - #### SIGNAL_REMOTE_EXCEPTION

          public static final short SIGNAL_REMOTE_EXCEPTION

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### SIGNAL_MONITOR_CANCELED

          public static final short SIGNAL_MONITOR_CANCELED

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### SIGNAL_MONITOR_PROGRESS

          public static final short SIGNAL_MONITOR_PROGRESS

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### SIGNAL_SET_TIMEOUT

          public static final short SIGNAL_SET_TIMEOUT

      Since:
        4.1
      See Also:
        Constant Field Values

    - #### SIGNAL_ACKNOWLEDGE_COMPRESSED_STRINGS

          public static final short SIGNAL_ACKNOWLEDGE_COMPRESSED_STRINGS

      Since:
        4.7
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SignalProtocol

          public SignalProtocol​(java.lang.String type)

      Since:
        2.0

  - ### Method Detail

    - #### getTimeout

          public long getTimeout()

      Specified by:
        `getTimeout` in interface `ISignalProtocol<INFRA_STRUCTURE>`
      Since:
        2.0

    - #### setTimeout

          public void setTimeout​(long timeout)

      Equivalent to calling SignalProtocol.setTimeout(timeout, false).
      Specified by:
        `setTimeout` in interface `ISignalProtocol<INFRA_STRUCTURE>`
      Since:
        2.0

    - #### setTimeout

          public boolean setTimeout​(long timeout,
                                    boolean useOldTimeoutToSendNewOne)

      Update the timeout used for signal end of stream waiting time.
      Parameters:
        `timeout` - the new timeout
        `useOldTimeoutToSendNewOne` - `true` to use the old timeout, `false` to use the new specified one to sent to server side the new specified timeout
      Returns:
        `true` if the new specified timeout has correctly been sent NOTE: this second parameter is useful mostly for test to be able to set a to small timeout
      Since:
        4.4

    - #### getStreamWrapper

          public org.eclipse.net4j.util.io.IStreamWrapper getStreamWrapper()

      Specified by:
        `getStreamWrapper` in interface `ISignalProtocol<INFRA_STRUCTURE>`

    - #### setStreamWrapper

          public void setStreamWrapper​(org.eclipse.net4j.util.io.IStreamWrapper streamWrapper)

      Specified by:
        `setStreamWrapper` in interface `ISignalProtocol<INFRA_STRUCTURE>`

    - #### addStreamWrapper

          public void addStreamWrapper​(org.eclipse.net4j.util.io.IStreamWrapper streamWrapper)

      Specified by:
        `addStreamWrapper` in interface `ISignalProtocol<INFRA_STRUCTURE>`

    - #### open

          public IChannel open​(IConnector connector)

      Specified by:
        `open` in interface `ISignalProtocol<INFRA_STRUCTURE>`
      Since:
        2.0

    - #### close

          public void close()

      Specified by:
        `close` in interface `ISignalProtocol<INFRA_STRUCTURE>`
      Since:
        2.0

    - #### waitForSignals

          public boolean waitForSignals​(long timeout)

    - #### handleBuffer

          public void handleBuffer​(IBuffer buffer)

      Handles a given (incoming) buffer. Creates a signal to act upon the given buffer or uses a previously created signal.
      Specified by:
        `handleBuffer` in interface `IBufferHandler`
      Parameters:
        `buffer` - The buffer to be handled.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `org.eclipse.net4j.util.lifecycle.Lifecycle`

    - #### doBeforeDeactivate

          protected void doBeforeDeactivate()
                                     throws java.lang.Exception

      Overrides:
        `doBeforeDeactivate` in class `org.eclipse.net4j.util.lifecycle.Lifecycle`
      Throws:
        `java.lang.Exception`

    - #### doDeactivate

          protected void doDeactivate()
                               throws java.lang.Exception

      Overrides:
        `doDeactivate` in class `Protocol<INFRA_STRUCTURE>`
      Throws:
        `java.lang.Exception`

    - #### handleChannelDeactivation

          protected void handleChannelDeactivation()

      Overrides:
        `handleChannelDeactivation` in class `Protocol<INFRA_STRUCTURE>`

    - #### provideSignalReactor

          protected final SignalReactor provideSignalReactor​(short signalID)

    - #### createSignalReactor

          protected SignalReactor createSignalReactor​(short signalID)

      Returns a new signal instance to serve the given signal ID or `null` if the signal ID is invalid/unknown for this protocol.

    - #### isSendingTimeoutChanges

          protected boolean isSendingTimeoutChanges()

      Returns `true` by default, override to change this behavior.
      Since:
        4.1

    - #### getStringCompressor

          protected org.eclipse.net4j.util.io.StringCompressor getStringCompressor()

      Since:
        4.7