Class: Endpoint

Endpoint

The main interface to Trap, a TrapEndpoint is the shared interface between servers and clients. It provides most of the methods that should be necessary to configure and use a Trap connection.

In general, a TrapEndpoint should be configured either when it has just been created.Reconfiguring a TrapEndpoint while it is in use can have unintended consequences.

Common tasks on a TrapEndpoint are:

Configuring Transports

Enabling and disabling transports, as well as configuring each transport, is possible from TrapEndpoint. Adding new transports to an existing endpoint is not possible.

Sending and Receiving Messages

To send messages, simply use Trap.Endpoint#send to send data. When data is received, it will be received in the onmessage listener.

Checking Liveness

Trap provides a simple facility to check if the other endpoint is alive, that is, communication is active and the other application layer is responding. The Trap.Endpoint#isAlive method can be used to check if the endpoint has been alive recently, or a combination of the two.

Configuring Keepalives

By default, Trap will attempt to use a per-transport keepalive policy that strikes a moderate balance between liveness and chattiness. It will take into account traffic only on the current TrapTransport, and without using device integration. This simple implementation can be tweaked to use a static keepalive interval instead (every X milliseconds), or disabled, using the method. More advanced keepalives can be user-supplied on a transport basis using TrapTransport#setKeepalivePredictor(TrapKeepalivePredictor).

Customizing the Message Queue

Trap has a number of buffers it uses, and some (such as the message queue) can impact performance significantly under different usage patterns. The message queue is the first front-end that feeds Trap, and plays a large role. An endpoint can be instructed to either choose the "best" buffer available of a given type (see constants) using , or it can be told to explicitly use a specific queue using . User-supplied queues can be use, as long as they fulfil the requirements.

new Endpoint()

Do not instantiate an endpoint directly. Instead, use Trap.ClientEndpoint or Trap.ListenerEndpoint.
Properties:
Name Type Description
state Trap.Endpoint.State The current Trap.Endpoint.State
queueType Trap.Endpoint.Queue The message queue type
maxActiveTransports Integer The maximum number of active transports. Default is 1.
authentication Trap.Authentication The current authentication provider
format Trap.Endpoint.Format The message format used. Default is 8-bit.
Source:

Namespaces

Queue
State

Members

_lastAlive

Last known activity of the connection. Activity is defined as any form of message FROM the client. In general, the TrapEndpoint will not concern itself with ensuring this.value is continually updated, as that is mostly unnecessary overhead. It will update it during the following conditions:

  • A transport disconnects. Even in this.case, the lastActivity field will only represent some most recent communication with the remote side, unless all transports have disconnected.
  • The application specifically queries. In this.case, the TrapEndpoint will specifically ensure that lastActivity has the most recent value.
Source:

canReconnectUntil

The last permitted timestamp for the client to re-establish connectivity. this.must be equal to or greater than canWakeupUntil, in order to maintain the same promise to the application.
Source:

canWakeupUntil

The last known timestamp where we can reliably wake up the underlying transports. If we have a wakeup mechanism, this.will be a non-negative value, and represents when we can unilaterally tell the application the connection is permanently dead (unless we can extend the wakeup mechanism).
Source:

keepaliveExpiry

The number of milliseconds that the endpoint should wait for a response (and/or attempt to reconnect/resend) to do an orderly close. After this time, the transport will simply deallocate all of its resources and vanish.
Source:

Methods

close()

Closes this Trap endpoint, terminating any outstanding Trap transports. Does nothing if the endpoint is already closed, is closing, or is in an error state.
Source:

configure(configuration)

Configures this TrapEndpoint, overwriting any previous configuration, and setting the new string to the new configuration. This will also reconfigure any constituent transports. This method should be used before using any of the programmatic configuration methods, as it may override them.
Parameters:
Name Type Description
configuration String A string representing the new configuration.
Source:

configureTransport(transportName, configurationKey, configurationValue)

Changes the configuration of a given transport. This is an alias to accessing the transport and configuring it directly. After configuration, the transport settings will be updated.

Care should be taken when using this method to not conflict with Trap's general management. In most cases, an endpoint will manage transport settings automatically, although some tweaks can be done on a per-transport basis.

General configuration keys can be found as static properties in TrapTransport. Specific options are relevant only to the given transport.

Parameters:
Name Type Description
transportName The name of the transport to configure.
configurationKey The unprefixed configuration key
configurationValue The new value of the key.
Source:
Throws:
TrapException If the transport does not exist (and thus cannot be configured).

disableAllTransports()

Convenience method to disable all transports at a given configurable object. This is primarily used to create controlled-environment Trap connections, where the available transports are not automatically set. Primarily targeted towards tests or other controlled environments, or when all transports need to be clamped down.
Source:

disableTransport(transportName)

Disables a transport. Unlike , this method will always succeed, even if the transport does not exist. This allows applications to safely remove transports they do not wish to use – if the transport does not exist, it will not be used.
Parameters:
Name Type Description
transportName String The transport to disable
Source:

enableTransport(transportName)

Enables a transport with a given name. Enabling a transport merely switches the enabled flag of the transport in the resident Trap configuration. It does not necessarily connect it.

Enabling a transport after a client endpoint has been asked to connect will cause the transport to be ignored until the reconnect procedure is triggered. For this reason, it is recommended that enabling/disabling transports is done before an endpoint is connected.

Parameters:
Name Type Description
transportName String The transport to enable.
Source:
Throws:
TrapException If the transport does not exist. This exception is thrown to prevent applications that rely on a certain transport from being surprised when the transport never connects. A typical case is a client disabling the http transport when websockets is not available.

getChannel(channelID) → {Trap.Channel}

Fetches the channel object associated with the given channel ID. If the channel was not created, creates it, allocating all required buffers.
Parameters:
Name Type Description
channelID Number The channel object to retrieve
Source:
Returns:
A new or existing channel object
Type
Trap.Channel

getConfiguration() → {String}

Gets the configuration of this endpoint. This is the configuration as it applies for this node; it does not represent the configuration another endpoint needs to have to connect here. See TrapListener#getClientConfiguration() for that. This method is useful for debugging.
Source:
Returns:
A string representing the current configuration of this TrapEndpoint.
Type
String

getMaxChunkSize() → {Number}

Source:
Returns:
Type
Number

getTransport(transportName)

Accesses a single transport by name. This is useful for advanced configuration of transports, debugging or highly specialised tweaking.
Parameters:
Name Type Description
transportName The name of the transport.
Source:
Throws:
TrapException If the transport does not exist.
Returns:
The TrapTransport instance representing the transport

getTransports()

Gets the current set of transports associated with this TrapEndpoint. These transports represent all the instances available to the endpoint, not necessarily the ones that are currently in use. Each transport has an individual state that determines if it is connected or not.
Source:
Returns:
A collection of transports associated with this endpoint.

isAlive(within, check, reconnect, timeout, callback)

Attempts to verify if the endpoint is alive, or has been alive within a certain number of milliseconds. Effectively, this.can be used to trigger a keepalive check of the endpoint if used with a within parameter of 0 and a check parameter of true.

this.function has a two-part purpose. The first is for the application to be able to check the last known liveness of the endpoint, to reduce the discovery time of a dead connection. The second is to trigger a check for a dead endpoint, when the application needs to know that it has active connectivity.

Note that in normal operation, the endpoint itself will report when it has disconnected; the application does not need to concern itself with this.detail unless it specifically needs to know that it has connectivity right now.

Warning: Calling isAlive on a Server Trap Endpoint (i.e. when none of the transports can perform the open() function) may cause a client to lose its connectivity. The client may not have discovered the underlying transport is dead yet, and may require more time to reconnect. A wakeup mechanism can be used to establish liveness, but the server's timeout value should be significantly more generous in order to accommodate the client's reconnect and/or wakeup procedure!

Parameters:
Name Type Description
within long Within how many milliseconds the last activity of the endpoint should have occurred before the endpoint should question whether it is alive.
check boolean Whether the endpoint should attempt to check for liveness, or simply return false if the last known activity of the endpoint is not later than within.
reconnect boolean Whether to attempt to force reconnection if the transports are not available within the given timeout. this.will ensure available liveness value reflects what is possible right now, although it may mean disconnecting transports that still may recover.
timeout long If check is true, how many milliseconds at most the liveness check should take before returning false anyway. The application can use this.value if it has a time constraint on it.
callback function true if the connection is currently alive (including if this.function successfully re-established the connection), false otherwise.
Source:

isTransportEnabled(transportName)

Queries if a transport is enabled. Preferable to calling and {@link TrapTransport#isEnabled()} as this method will not throw if a transport does not exist.
Parameters:
Name Type Description
transportName The transport whose state to query.
Source:
Returns:
true if a transport exists, and is enabled, false otherwise.

lastAlive()

Fetches the last known liveness timestamp of the endpoint. this.is the last time it received a message from the other end. this.includes all messages (i.e. also Trap messages such as keepalives, configuration, etc) so must not be confused with the last known activity of the other application. For example, in the case of a JavaScript remote endpoint, this.does not guarantee an evaluation error has not rendered the JSApp's main run loop as inoperable.
Source:
See:
Returns:
The timestamp of the last message received from the remote side.

onfailedsending()

Called when a Trap Endpoint knows it has failed to send some messages. this.can occur when the Trap Endpoint is killed forcibly, loses all its transports while still having an outgoing buffer, or fails to wake up a client that has disconnected all its transports normally.

Note that there are conditions when Trap may unwittingly lose data (such as data sent during a switch from unauthenticated -> authenticated session, when the authentication is triggered from the remote side), so the sum of data received by the other end, and called on this.method, may be different. Nevertheless, any data returned by this.method definitely failed to send.

Parameters:
Name Type Description
evt.datas A collection of transportable objects that failed sending. Usually byte arrays, but may contain TrapObject instances.
Source:

onmessage()

Called when the Trap endpoint has received byte data from the other end. this.method executes in a Trap thread, so it should only perform minimal operations before returning, in order to allow for maximum throughput.
Parameters:
Name Type Description
evt.buffer ArrayBuffer The bytes received
evt.string String A string constructed by parsing the bytes received as UTF-8
evt.object Object An object formed by parsing the string as JSON.
evt.channel Integer The Trap Channel the event was received on.
Source:

onstatechange()

Called when Trap changes state. Includes both the new state, and the previous one.
Parameters:
Name Type Description
evt.newState The state Trap changed to.
evt.oldState The previous state.
Source:

send(data, channel, useCompression)

Attempts to queue data for sending. If the queue length is exceeded, it may block or throw an exception, as per the queue type.

Please note that while send will accurately send the data over to the other endpoint, it is advisable to instead use if the data being sent is a serialized object. If the other endpoint is locally deployed, the TrapObject will never be serialized, thus saving on large amounts of processing power.

Parameters:
Name Type Description
data Object | String The data to send. If an object, is serialised as JSON automatically.
channel Number The channel to send on
useCompression Boolean Whether to use compression for this message or not.
Source:
Throws:
TrapException if the queue length is exceeded, or a timeout occurs on a blocking queue

setKeepaliveExpiry(newExpiry)

Sets the keepalive expiry timeout. Alias for TrapKeepalivePredictor#setKeepaliveExpiry(long) on the currently set predictor.
Parameters:
Name Type Description
newExpiry The new keepalive expiry time.
Source:
See:
  • TrapKeepalivePredictor#setKeepaliveExpiry(long)

setKeepaliveInterval(newInterval)

Sets a new keepalive interval for the trap endpoint. The keepalive interval has one of three possible meanings:
  • A value of TrapKeepalivePolicy#DISABLED will disable the keepalives.
  • A value of TrapKeepalivePolicy#DEFAULT will cause each transport to use its internal estimate of what a good keepalive is.
  • A value of 1 <= n <= 999999 will specify the number of seconds between keepalive messages.
Any change on the TrapEndpoint level will affect all transports associated with this endpoint, overwriting any individual configuration the transports may have had. The inverse does not apply.

See the Trap Keepalive documentation for details on the keepalives.

Parameters:
Name Type Description
newInterval The new keepalive interval or policy.
Source: