pureweb.client. WebClient

The WebClient class manages communications between the client application and the service application via the PureWeb server. The critical functionality provided by this class includes:
  • Connecting the HTML5 client to the service application, and disconnecting from it.
  • Queueing commands to send to the service in response to client events.
  • Receiving dispatch responses from the service, usually in the form of image segments to display in a view.
Note: the WebClient class does not throw exceptions. To listen for events and retrieve the error information, use getResponseException.

Method Summary

addMultipartHandler
Registers a multipart handler.
connect
Connects the HTML5 client to the service application.
disconnect
Disconnects the client from the service application.
extractViewUriFromSessionUri
Returns a pureweb /view URL from an /app URL.
getAcquireException
Returns the last acquire exception, or null if there were none.
getConnectionParameters
Returns the map of query parameters sent when connecting.
getFramework
Returns the Framework parent instance of this WebClient object.
getMaxRedirects
Returns a value indicating the maximum number of redirects that the connect method will follow before failing.
getMinimumRequestInterval
Returns the minimum request interval, in milliseconds.
getMultiWindow
Returns the MulitWindow member of this WebClient object.
getRequestException
Returns the last request exception.
getResourceUrl
Creates a URL that can be used to retrieve a resource stored by the service application, and returns this URL.
getResponseException
Returns the last response exception.
getSessionId
Returns the session ID for this connection.
getSessionShareUrlAsync
Requests a session share URL from the service, for collaboration purposes; this request is asynchronous.
getSessionState
Returns the current state of the session.
getSessionStorage
Returns the SessionStorage member of this WebClient object.
getSessionUri
Returns the URL of the service application to which the client is connected.
invalidateSessionShareUrlAsync
Invalidates the specified session share URL asynchronously.
isAppUri
Returns a Boolean value that indicates whether the specified URI is a app URI.
isaSessionUri
Returns a Boolean value that indicates whether the specified URI is a session URI.
isaShareUri
Returns a Boolean value that indicates whether the specified URI is a share URI.
isConnected
Returns a Boolean value that indicates whether the client is connected.
isMobile
Returns a Boolean value that indicates whether this is a mobile client.
isStalled
Returns a Boolean value that indicates whether this instance is stalled or not.
isUriConnectable
Returns a Boolean value that indicates whether the specified URI is a URI that PureWeb knows how to connect to Will return true if it is, or false otherwise.
isViewUri
Returns a Boolean value that indicates whether the specified URI is a view URI.
joinSession
Connects to an existing collaboration session using a share URL.
queueCommand
Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application.
queueRequest
Queues a service request for asynchronous execution.
removeMultipartHandler
Removes the multipart handler with the specified name.
resumeServerUpdate
Un-Suppresses server updates.
retrieveObject
Retrieves a resource (binary object) created by the service application.
setCommandFilteringEnabled
Enables or disables client-side command filtering.
setConnectionParameters
Sets the map of query parameters passed when connecting, and returns this map.
setMaxRedirects
Sets a value indicating the maximum number of redirects the connect method will follow before failing.
setMinimumRequestInterval
Sets a value for the minimum amount of time that must elapse between subsequent requests.
supportsBinary
Returns a Boolean value that indicates whether the client supports binary responses.
supportsRetrieveObject
Returns a Boolean value that indicates whether the client can retrieve objects using xhr in binary format.
supportsWebsockets
Returns a Boolean value that indicates whether the client supports web sockets.
suppressServerUpdate
Suppresses server updates.

Constructor

new WebClient(framework)

Initializes a new instance of WebClient.
Parameters:
Name Type Description
framework pureweb.client.Framework The framework this WebClient is part of.
Throws:
If the framework is null or undefined:
pureweb.IllegalArgumentException

Extends

Members

<static, constant> BYTES_PER_MEGABIT → number

Number of bytes per megabit.

<static> EventType → string

An enumeration of the types of events for which client applications can listen on WebClient.
Properties:
Name Type Default Description
CONNECTED_CHANGED string The event that gets dispatched when the client connects to or disconnects from the service application.
STALLED_CHANGED string The event that gets dispatched when the connection to the service application stalls (possibly indicating the connection has been lost), or recovers from a stall.
SESSION_STATE_CHANGED string The event that gets dispatched when the session state changes.
MULTIPART_HANDLER_EXCEPTION_OCCURRED string The event that gets dispatched when an exception occurs while trying to invoke the command handler callback function.

latencypureweb.client.diagnostics.TimedEventProfiler

A profiler that measures the round-trip latency between the client and the service application.

<protected> logger → goog.debug.Logger

Define logger.

mbpspureweb.client.diagnostics.RateProfiler

A profiler that measures the network throughput between the client and the service application.

<static, constant> PARSER_ERROR_TAG → string

ParserError tag.

<static, constant> REQUEST_TIMEOUT → number

The timeout for all non-websocket based requests (this includes acquiring application URLs & retrieveObject)

requestBuildingpureweb.client.diagnostics.EventProfiler

A profiler that measures the time required to build the requests to send to the service (including filtering).

<static, constant> RESPONSE_EXCEPTION_MESSAGE_TAG → string

Message tag.

<static, constant> RESPONSE_EXCEPTION_RUNTIME_TYPE_TAG → string

RunTimeType tag.

<static, constant> RESPONSE_EXCEPTION_TAG → string

Response exception tag.

<static, constant> RESPONSE_ID_TAG → string

CommandResponses XML tag constants.

responseHandlerspureweb.client.diagnostics.EventProfiler

A profiler that measures the time taken to process incoming data by all multipart response handlers.

responseParsingpureweb.client.diagnostics.EventProfiler

A profiler that measures the time taken to parse multipart messages from the data stream received from the service.

Method Detail

addMultipartHandler(name, multipartHandler)

Registers a multipart handler.
Parameters:
Name Type Description
name string The name of the handler.
multipartHandler function The multipart response handler function; it takes three arguments: the first specifies the mime type of the response, the second specifies the bytes of the response, and the third is an object containing additional response parameters.
Throws:
If an argument is null:
pureweb.IllegalArgumentException

connect(uri, authinfo, opt_logoutOnClose, opt_connectSessionParams)

Connects the HTML5 client to the service application.
Parameters:
Name Type Argument Description
uri string The URL of the service application to which the client will connect.
authinfo Object <optional>
Authentication information (username and password), if available.
opt_logoutOnClose boolean <optional>
Indicates whether to terminate The logged-in session when this connection ends.
opt_connectSessionParams Object <optional>
Additional query parameters to pass when connecting, if any.
Throws:

disconnect()

Disconnects the client from the service application.
Throws:
If the client is not connected:
pureweb.InvalidOperationException

extractViewUriFromSessionUri(uri) → {string}

Returns a pureweb /view URL from an /app URL.
Parameters:
Name Type Description
uri string The URI to test.

getAcquireException() → {pureweb.client.AcquireException|null}

Returns the last acquire exception, or null if there were none.

getConnectionParameters() → {Object}

Returns the map of query parameters sent when connecting.

getFramework() → {pureweb.client.Framework}

Returns the Framework parent instance of this WebClient object.

getMaxRedirects() → {number}

Returns a value indicating the maximum number of redirects that the connect method will follow before failing.

getMinimumRequestInterval() → {number}

Returns the minimum request interval, in milliseconds. This represents the minimum amount of time that must elapse between subsequent requests.

getMultiWindow() → {pureweb.client.MultiWindow}

Returns the MulitWindow member of this WebClient object.

getRequestException() → {pureweb.client.RequestException|null}

Returns the last request exception.

getResourceUrl(resourceId) → {string}

Creates a URL that can be used to retrieve a resource stored by the service application, and returns this URL.
Parameters:
Name Type Description
resourceId string The ID of the resource.
Throws:
If the client is not connected:
pureweb.InvalidOperationException

getResponseException() → {pureweb.client.ResponseException|null}

Returns the last response exception.

getSessionId() → {string}

Returns the session ID for this connection.

getSessionShareUrlAsync(password, descriptor, timeout, criteria, callback)

Requests a session share URL from the service, for collaboration purposes; this request is asynchronous.
Parameters:
Name Type Description
password string The password that the participants will need to enter when using the share URL to join a session.
descriptor string This parameter is not used at this time and can be safely ignored.
timeout number The length of time (in milliseconds) that the share URL will remain valid for new collaborators to join (collaborators already in the session are not affected when this timeout lapses).
criteria string This parameter is not used at this time and can be safely ignored.
callback function The callback function to execute when the share URL is received, or the error to return (shareUrl, error).

getSessionState() → {pureweb.client.SessionState}

Returns the current state of the session.

getSessionStorage() → {pureweb.client.SessionStorage}

Returns the SessionStorage member of this WebClient object.

getSessionUri() → {string}

Returns the URL of the service application to which the client is connected.

invalidateSessionShareUrlAsync(shareUrl, callback)

Invalidates the specified session share URL asynchronously. When a share URL is invalidated, new collaboration participants are not allowed to access the URL, but this has no impact on existing participants already in the session.
Parameters:
Name Type Description
shareUrl string The share URL to invalidate.
callback function The function that will be called once the share URL has been rendered invalid, with an optional error message parameter.

isAppUri(uri) → {boolean}

Returns a Boolean value that indicates whether the specified URI is a app URI. Will return true if it is, or false otherwise.
Parameters:
Name Type Description
uri string The URI to test.

isaSessionUri(uri) → {boolean}

Returns a Boolean value that indicates whether the specified URI is a session URI. Will return true if it is, or false otherwise.
Parameters:
Name Type Description
uri string The URI to test.

isaShareUri(uri) → {boolean}

Returns a Boolean value that indicates whether the specified URI is a share URI. Will return true if it is, or false otherwise.
Parameters:
Name Type Description
uri string The URI to test.

isConnected() → {boolean}

Returns a Boolean value that indicates whether the client is connected. Will return true if it is, or false otherwise.

isMobile() → {boolean}

Returns a Boolean value that indicates whether this is a mobile client. Will return true if it is, or false otherwise.

isStalled() → {boolean}

Returns a Boolean value that indicates whether this instance is stalled or not. Will return true if it is, or false otherwise.

isUriConnectable(uri) → {boolean}

Returns a Boolean value that indicates whether the specified URI is a URI that PureWeb knows how to connect to Will return true if it is, or false otherwise.
Parameters:
Name Type Description
uri string The URI to test.

isViewUri(uri) → {boolean}

Returns a Boolean value that indicates whether the specified URI is a view URI. Will return true if it is, or false otherwise.
Parameters:
Name Type Description
uri string The URI to test.

joinSession(uri, password)

Connects to an existing collaboration session using a share URL.
Parameters:
Name Type Description
uri string The URL of the service application to connect to.
password string The password set for the collaboration session.
Throws:
If the URI is not a share URL:
pureweb.IllegalArgumentException

queueCommand(command, params, callback)

Adds the specified command, including any of its arguments, to the outgoing command queue, which delivers the commands to the service application.
Parameters:
Name Type Argument Description
command string The name of the command.
This must match exactly the name as it was provided when the command's handler was first registered on the service.
params Object | Element <optional>
Any additional command parameters, expressed as key-value pairs.
callback function <optional>
The return function supplied by the caller.

queueRequest(request)

Queues a service request for asynchronous execution.
Parameters:
Name Type Description
request pureweb.client.ServiceRequest The service request to execute.
Throws:
InvalidOperationException If the client is not connected.

removeMultipartHandler(name) → {boolean}

Removes the multipart handler with the specified name. Will return true if the specified handler exists and was successfully removed, or false otherwise.
Parameters:
Name Type Argument Description
name string <nullable>
The name of the handler to remove.
Throws:
If an argument is null:
pureweb.IllegalArgumentException

resumeServerUpdate()

Un-Suppresses server updates.

retrieveObject(key, callback)

Retrieves a resource (binary object) created by the service application. For more information, refer to the ResourceManager class in the service API.

Note: If the browser supports Blob, the binary object is passed to the specified callback function as a Blob; otherwise the binary object is passed as a string with the following mime type: text/plain;charset=x-user-defined.
Parameters:
Name Type Description
key string The unique identifier assigned to the resource by the service.
callback function The callback function to invoke when the binary object is downloaded, or the download failed. If the download is successful the first parameter specifies the object Blob and the second parameter is null. If unsuccessful, the first parameter is null, and the second parameter is a string containing the error message.
Throws:
If the client is not connected:
pureweb.InvalidOperationException

setCommandFilteringEnabled(filterCommands)

Enables or disables client-side command filtering.
Parameters:
Name Type Description
filterCommands boolean True to enable client-side command filtering, and false to disable.

setConnectionParameters() → {Object}

Sets the map of query parameters passed when connecting, and returns this map.

setMaxRedirects(maxRedirects)

Sets a value indicating the maximum number of redirects the connect method will follow before failing. Must be called before the call to connect.
Parameters:
Name Type Description
maxRedirects number The maximum number of redirects.
Throws:
If maxRedirects is not a number greater than zero:
pureweb.IllegalArgumentException

setMinimumRequestInterval(minimumRequestInterval)

Sets a value for the minimum amount of time that must elapse between subsequent requests.
Parameters:
Name Type Description
minimumRequestInterval number The minimum request interval, in milliseconds.
Throws:
If minimumRequestInterval is not a number greater than zero:
pureweb.IllegalArgumentException

supportsBinary() → {boolean}

Returns a Boolean value that indicates whether the client supports binary responses. Will return true if it does, or false otherwise.

supportsRetrieveObject() → {boolean}

Returns a Boolean value that indicates whether the client can retrieve objects using xhr in binary format. Will return true if it does, or false otherwise.

supportsWebsockets() → {boolean}

Returns a Boolean value that indicates whether the client supports web sockets. Will return true if it does, or false otherwise.

suppressServerUpdate()

Suppresses server updates.