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>, IExecutorServiceProvider, INotifier, IDeactivateable, ILifecycle, ILifecycle.DeferrableActivation, 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 and Description
    --- | ---
    `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.ILocationAware

      `ILocationAware.Location`

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

      `ILifecycle.DeferrableActivation`

  - ### Field Summary

    Fields
    Modifier and Type | Field and 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.signal.ISignalProtocol

      `DEFAULT_TIMEOUT, NO_TIMEOUT`

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

      `UNSPECIFIED_VERSION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SignalProtocol(java.lang.String type)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addStreamWrapper(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()`
    `IStreamWrapper` | `getStreamWrapper()`
    `protected 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(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, fireEvent, fireEvent, fireEvent, fireThrowable, firstListenerAdded, getListeners, getNotificationService, hasListeners, lastListenerRemoved, 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.protocol.IProtocol

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

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

      `getUserID`

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

- - ### 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 IStreamWrapper getStreamWrapper()

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

    - #### setStreamWrapper

          public void setStreamWrapper(IStreamWrapper streamWrapper)

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

    - #### addStreamWrapper

          public void addStreamWrapper(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 and otionally released.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `Lifecycle`

    - #### doBeforeDeactivate

          protected void doBeforeDeactivate()
                                     throws java.lang.Exception

      Overrides:
        `doBeforeDeactivate` in class `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 StringCompressor getStringCompressor()

      Since:
        4.7

Copyright (c) 2004-2019 Eike Stepper (Loehne, Germany) and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html