Class: ClientEndpoint

ClientEndpoint

A Trap.ClientEndpoint is a Trap.Endpoint capable of opening an outgoing connection, commonly to a TrapListener. It is able to reconnect transports at will, unlike a ServerTrapEndpoint. This is the main entry point for JavaScript. Create a Trap.ClientEndpoint like so 

client = new Trap.ClientEndpoint("http://trapserver.com:8888");
client.onopen = function() {
};
client.onmessage = function(evt) {
};

The client will open automatically once instantiated. Assign at least the onopen and onmessage callbacks (and preferably onerror) in order to get a working client.

new ClientEndpoint(configuration)

Instantiates a new Trap Client.
Parameters:
Name Type Description
configuration.useBinary Boolean Enables (default) or disables binary support.
configuration.autoConfigure Boolean Enables (default) or disables automatic configuration
configuration.remote String A URI or TrapConfiguration to the remote host.
configuration String The alternate means to instantiate a ClientEndpoint is to supply it with a single string constituting a complete configuration.
Source:

Extends

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.
Inherited From:
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.
Inherited From:
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).
Inherited From:
Source:

failedTransports

The transports that have failed in some non-fatal way. There will be an attempt taken in the future to recover them.
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.
Inherited From:
Source:

transportsToConnect

The list of transports that have not been tried before or after all transports failed and being tried again.
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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
Inherited From:
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.
Inherited From:
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
Inherited From:
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.
Inherited From:
Source:
Returns:
A string representing the current configuration of this TrapEndpoint.
Type
String

getMaxChunkSize() → {Number}

Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
Source: