BrowserChannel (Closure Library API Documentation

An application-specific version number that is sent to the server when connected.

Instance Methods

Public Protected Private

Defined in goog.net.BrowserChannel

addAdditionalParams_(uri)

Adds the additional parameters from the handler to the given URI.

Arguments:

uri :

(goog.Uri | null)

The URI to add the parameters to.

code »

cancelRequests_()

Cancels all outstanding requests.

code »

clearDeadBackchannelTimer_()

Clears the timer that indicates that our backchannel is no longer able to successfully receive data from the server.

code »

connect(testPath, channelPath, extraParams, opt_oldSessionId, opt_oldArrayId)

Starts the channel. This initiates connections to the server.

Arguments:

testPath :

The path for the test connection.

channelPath :

The path for the channel connection.

extraParams :

(Object | null)

Extra parameter keys and values to add to the requests.

opt_oldSessionId :

(string | undefined)

Session ID from a previous session.

opt_oldArrayId :

(number | undefined)

The last array ID from a previous session.

code »

connectChannel_()

Starts the regular channel which is run after the test channel is complete.

code »

connectTest_(testPath)

Starts the test channel to determine network conditions.

Arguments:

testPath :

The relative PATH for the test connection.

code »

correctHostPrefix(serverHostPrefix) ⇒

(null | string)

Decides which host prefix should be used, if any. If there is a handler, allows the handler to validate a host prefix provided by the server, and optionally override it.

Arguments:

serverHostPrefix :

(null | string)

The host prefix provided by the server.

Returns:

(null | string)

The host prefix to actually use, if any. Will return null if the use of host prefixes was disabled via setAllowHostPrefix().

code »

createDataUri(hostPrefix, path, opt_overridePort) ⇒

(goog.Uri | null)

Creates a data Uri applying logic for secondary hostprefix, port overrides, and versioning.

Arguments:

hostPrefix :

(null | string)

The host prefix.

path :

The path on the host (may be absolute or relative).

opt_overridePort :

(number | undefined)

Optional override port.

Returns:

(goog.Uri | null)

The data URI.

code »

createXhrIo(hostPrefix) ⇒

goog.net.XhrIo

Called when BC needs to create an XhrIo object. Override in a subclass if you need to customize the behavior, for example to enable the creation of XHR's capable of calling a secondary domain.

Arguments:

hostPrefix :

(null | string)

The host prefix, if we need an XhrIo object capable of calling a secondary domain.

Returns:

goog.net.XhrIo

A new XhrIo object.

code »

dequeueOutgoingMaps_() ⇒

Returns the request text from the outgoing maps and resets it.

Returns:

The encoded request text created from all the currently queued outgoing maps.

code »

disconnect()

Disconnects and closes the channel.

code »

ensureBackChannel_()

Ensures there is a backchannel request for receiving data from the server.

code »

ensureForwardChannel_()

Ensures that a forward channel request is scheduled.

code »

ensureInState_(var_args)

Helper to ensure the BrowserChannel is in the expected state.

Arguments:

var_args :

(number | undefined)

The channel must be in one of the indicated states.

code »

getAllowChunkedMode() ⇒

Returns whether chunked mode is allowed. In certain debugging situations, it's useful for the application to have a way to disable chunked mode for a user.

Returns:

Whether chunked mode is allowed.

code »

getAllowHostPrefix() ⇒

Returns whether the channel allows the use of a subdomain. There may be cases where this isn't allowed.

Returns:

Whether a host prefix is allowed.

code »

getBackChannelMaxRetries() ⇒

No description.

Returns:

The max number of back-channel retries, which is a constant.

code »

getBackChannelUri(hostPrefix, path) ⇒

(goog.Uri | null)

Gets the Uri used for the connection that receives data from the server.

Arguments:

hostPrefix :

(null | string)

The host prefix.

path :

The path on the host.

Returns:

(goog.Uri | null)

The back channel URI.

code »

getChannelDebug() ⇒

(goog.net.ChannelDebug | null)

Returns the browserchannel logger.

Returns:

(goog.net.ChannelDebug | null)

The channel debug object.

code »

getExtraHeaders() ⇒

(Object | null)

Returns the extra HTTP headers to add to all the requests sent to the server.

Returns:

(Object | null)

The HTTP headers, or null.

code »

getForwardChannelMaxRetries() ⇒

No description.

Returns:

The max number of forward-channel retries, which will be 0 in fail-fast mode.

code »

getForwardChannelUri(path) ⇒

(goog.Uri | null)

Gets the Uri used for the connection that sends data to the server.

Arguments:

path :

The path on the host.

Returns:

(goog.Uri | null)

The forward channel URI.

code »

getHandler() ⇒

(goog.net.BrowserChannel.Handler | null)

Returns the handler used for channel callback events.

Returns:

(goog.net.BrowserChannel.Handler | null)

The handler.

code »

getLastArrayId() ⇒

No description.

Returns:

The last array id received.

code »

getLastStatusCode() ⇒

Return the last status code received for a request.

Returns:

The last status code received for a request.

code »

getRetryTime_(retryCount) ⇒

No description.

Arguments:

retryCount :

Number of retries so far.

Returns:

Time in ms before firing next retry request.

code »

getSessionId() ⇒

Returns the session id of the channel. Only available after the channel has been opened.

Returns:

Session ID.

code »

getState() ⇒

goog.net.BrowserChannel.State.<number>

Returns the browser channel state.

Returns:

goog.net.BrowserChannel.State.<number>

The current state of the browser channel.

code »

handleBackchannelMissing_()

Handles a POST response from the server telling us that it has detected that we have no hanging GET connection.

code »

handlePostResponse_(responseValues)

Handles a POST response from the server.

Arguments:

responseValues :

(Array | null)

The key value pairs in the POST response.

code »

hasOutstandingRequests() ⇒

Returns whether there are outstanding requests servicing the channel.

Returns:

true if there are outstanding requests.

code »

isActive() ⇒

Gets whether this channel is currently active. This is used to determine the length of time to wait before retrying. This call delegates to the handler.

Returns:

Whether the channel is currently active.

code »

isBuffered() ⇒

Returns whether the channel is buffered or not. This state is valid for querying only after the test connection has completed. This may be queried in the goog.net.BrowserChannel.okToMakeRequest() callback. A channel may be buffered if the test connection determines that a chunked response could not be sent down within a suitable time.

Returns:

Whether the channel is buffered.

code »

isClosed() ⇒

Returns whether the channel is closed

Returns:

true if the channel is closed.

code »

makeForwardChannelRequest_(opt_retryRequest)

Makes a forward channel request using XMLHTTP.

Arguments:

opt_retryRequest :

(goog.net.ChannelRequest | null | undefined)

A failed request to retry.

code »

maybeRetryBackChannel_() ⇒

Schedules a back-channel retry, unless the max retries has been reached.

Returns:

true iff a retry was scheduled.

code »

maybeRetryForwardChannel_(request) ⇒

Schedules a forward-channel retry for the specified request, unless the max retries has been reached.

Arguments:

request :

(goog.net.ChannelRequest | null)

The failed request to retry.

Returns:

true iff a retry was scheduled.

code »

okToMakeRequest_() ⇒

Gives the handler a chance to return an error code and stop channel execution. A handler might want to do this to check that the user is still logged in, for example.

Returns:

If it's OK to make a request.

code »

onBackChannelDead_()

Handles the timer that indicates that our backchannel is no longer able to successfully receive data from the server.

code »

onClose_()

Called when the channel has been closed. It notifiers the handler of the event, and reports any pending or undelivered maps.

code »

onError_(error)

Called when we've determined the final error for a channel. It closes the notifiers the handler of the error and closes the channel.

Arguments:

error :

goog.net.BrowserChannel.Error.<number>

The error code for the failure.

code »

onInput_(respArray)

Processes the data returned by the server.

Arguments:

respArray :

(Array | null)

The response array returned by the server.

code »

onRequestComplete(request)

Callback from ChannelRequest that indicates a request has completed.

Arguments:

request :

(goog.net.ChannelRequest | null)

The request object.

code »

onRequestData(request, responseText)

Callback from ChannelRequest for when new data is received

Arguments:

request :

(goog.net.ChannelRequest | null)

The request object.

responseText :

The text of the response.

code »

onStartBackChannelTimer_()

Timer callback for ensureBackChannel_.

code »

onStartForwardChannelTimer_(opt_retryRequest)

Timer callback for ensureForwardChannel

Arguments:

opt_retryRequest :

(goog.net.ChannelRequest | null | undefined)

A failed request to retry.

code »

open_()

Establishes a new channel session with the the server.

code »

outstandingRequests_() ⇒

Returns the number of outstanding requests.

Returns:

The number of outstanding requests to the server.

code »

requeuePendingMaps_()

Requeues unacknowledged sent arrays for retransmission in the next forward channel request.

code »

sendMap(map)

Sends a request to the server. The format of the request is a Map data structure of key/value pairs. These maps are then encoded in a format suitable for the wire and then reconstituted as a Map data structure that the server can process.

Arguments:

map :

(Object | null)

The map to send.

code »

setAllowChunkedMode(allowChunkedMode)

Sets whether chunked mode is allowed. In certain debugging situations, it's useful for the application to have a way to disable chunked mode for a user.

Arguments:

allowChunkedMode :

Whether chunked mode is allowed.

code »

setAllowHostPrefix(allowHostPrefix)

Sets whether the channel allows the use of a subdomain. There may be cases where this isn't allowed, for example, logging in with troutboard where using a subdomain causes Apache to force the user to authenticate twice.

Arguments:

allowHostPrefix :

Whether a host prefix is allowed.

code »

setChannelDebug(channelDebug)

Set the browserchannel logger. TODO(user): Add interface for channel loggers or remove this function.

Arguments:

channelDebug :

(goog.net.ChannelDebug | null)

The channel debug object.

code »

setExtraHeaders(extraHeaders)

Sets extra HTTP headers to add to all the requests sent to the server.

Arguments:

extraHeaders :

(Object | null)

The HTTP headers, or null.

code »

setFailFast(failFast)

When set to true, this changes the behavior of the forward channel so it will not retry requests; it will fail after one network failure, and if there was already one network failure, the request will fail immediately.

Arguments:

failFast :

Whether or not to fail fast.

code »

setHandler(handler)

Sets the handler used for channel callback events.

Arguments:

handler :

(goog.net.BrowserChannel.Handler | null)

The handler to set.

code »

shouldRetryBackChannel_(outstandingBytes) ⇒

Determines whether we should start the process of retrying a possibly dead backchannel.

Arguments:

outstandingBytes :

The number of bytes for which the server has not yet received acknowledgement.

Returns:

Whether to start the backchannel retry timer.

code »

shouldUseSecondaryDomains() ⇒

Determines whether to use a secondary domain when the server gives us a host prefix. This allows us to work around browser per-domain connection limits. Currently, we only use secondary domains when using Trident's ActiveXObject, because it supports cross-domain requests out of the box. Even if we wanted to use secondary domains on Gecko/Webkit, they wouldn't work due to security restrictions on cross-origin XHRs. If you need to use secondary domains on other browsers, you'll need to override this method in a subclass, and make sure that those browsers use some messaging mechanism that works cross-domain.

Returns:

Whether to use secondary domains.

code »

signalError_(error)

Signals an error has occurred.

Arguments:

error :

goog.net.BrowserChannel.Error.<number>

The error code for the failure.

code »

startBackChannel_()

Begins a new back channel operation to the server.

code »

startForwardChannel_(opt_retryRequest)

Begins a new forward channel operation to the server.

Arguments:

opt_retryRequest :

(goog.net.ChannelRequest | null | undefined)

A failed request to retry.

code »

testConnectionBlocked(testChannel)

Callback from BrowserTestChannel for when the channel is blocked.

Arguments:

testChannel :

(goog.net.BrowserTestChannel | null)

The BrowserTestChannel.

code »

testConnectionFailure(testChannel, errorCode)

Callback from BrowserTestChannel for when the channel has an error.

Arguments:

testChannel :

(goog.net.BrowserTestChannel | null)

The BrowserTestChannel.

errorCode :

goog.net.ChannelRequest.Error.<number>

The error code of the failure.

code »

testConnectionFinished(testChannel, useChunked)

Callback from BrowserTestChannel for when the channel is finished.

Arguments:

testChannel :

(goog.net.BrowserTestChannel | null)

The BrowserTestChannel.

useChunked :

Whether we can chunk responses.

code »

testGoogleComCallback_(networkUp)

Callback for testGoogleCom during error handling.

Arguments:

networkUp :

Whether the network is up.

code »

Instance Properties

Defined in goog.net.BrowserChannel

	backChannelAttemptId_ : number The attempt id for the current back channel request. Starts at 1 and increments for each reconnect. The server uses this to log if our connection is flaky or not.	Code »
	backChannelRequest_ : (goog.net.ChannelRequest \| null) The ChannelRequest object for the backchannel.	Code »
	backChannelRetryCount_ : number Number of times it a row that we have retried the current back channel request and received no data.	Code »
	backChannelTimerId_ : (null \| number) Timer identifier for asynchronously making a back channel request.	Code »
	backChannelUri_ : (goog.Uri \| null) The absolute URI for the backchannel request.	Code »
	channelDebug_ : (goog.net.ChannelDebug \| null) The channel debug used for browserchannel logging	Code »
	channelVersion_ : number The channel version that we negotiated with the server for this session. Starts out as the version we request, and then is changed to the negotiated version after the initial open.	Code »
	clientVersion_ : string The application specific version that is passed to the server.	Code »
	connectionTest_ : (goog.net.BrowserTestChannel \| null) The BrowserTestChannel object which encapsulates the logic for determining interesting network conditions about the client.	Code »
	deadBackChannelTimerId_ : (null \| number) Timer identifier for the timer that waits for us to retry the backchannel in the case where it is dead and no longer receiving data.	Code »
	extraHeaders_ : (Object \| null) Extra HTTP headers to add to all the requests sent to the server.	Code »
	extraParams_ : (Object \| null) Extra parameters to add to all the requests sent to the server.	Code »
	failFast_ : boolean Whether to fail forward-channel requests after one try, or after a few tries.	Code »
	forwardChannelRequest_ : (goog.net.ChannelRequest \| null) The current ChannelRequest object for the forwardchannel.	Code »
	forwardChannelRetryCount_ : number Number of times we have retried the current forward channel request.	Code »
	forwardChannelTimerId_ : (null \| number) Timer identifier for asynchronously making a forward channel request.	Code »
	forwardChannelUri_ : (goog.Uri \| null) The absolute URI for the forwardchannel request.	Code »
	handler_ : (goog.net.BrowserChannel.Handler \| null) The handler that receive callbacks for state changes and data.	Code »
	hostPrefix_ : (null \| string) A subdomain prefix for using a subdomain in IE for the backchannel requests.	Code »
	lastArrayId_ : number The array identifier of the last array received from the server for the backchannel request.	Code »
	lastPostResponseArrayId_ : number The array identifier of the last array sent by the server that we know about.	Code »
	lastStatusCode_ : number The last status code received.	Code »
	nextMapId_ : number The id to use for the next outgoing map. This identifier uniquely identifies a sent map.	Code »
	nextRid_ : number The next id to use for the RID (request identifier) parameter. This identifier uniquely identifies the forward channel request.	Code »
	outgoingMaps_ : (Array \| null) An array of queued maps that need to be sent to the server.	Code »
	path_ : (null \| string) The relative path (in the context of the the page hosting the browser channel) for making requests to the server.	Code »
	pendingMaps_ : (Array \| null) An array of dequeued maps that we have either received a non-successful response for, or no response at all, and which therefore may or may not have been received by the server.	Code »
	state_ : goog.net.BrowserChannel.State.<number> The current state of the BrowserChannel. It should be one of the goog.net.BrowserChannel.State constants.	Code »
	useChunked_ : (boolean \| null) Whether the client's network conditions can support chunked responses.	Code »

Static Methods

goog.net.BrowserChannel.createChannelRequest(channel, channelDebug, opt_sessionId, opt_requestId, opt_retryId) ⇒

(goog.net.ChannelRequest | null)

Instantiates a ChannelRequest with the given parameters. Overidden in tests.

Arguments:

channel :

(goog.net.BrowserChannel | goog.net.BrowserTestChannel | null)

The BrowserChannel that owns this request.

channelDebug :

(goog.net.ChannelDebug | null)

A ChannelDebug to use for logging.

opt_sessionId :

(string | undefined)

The session id for the channel.

opt_requestId :

(number | string | undefined)

The request id for this request.

opt_retryId :

(number | undefined)

The retry id for this request.

Returns:

(goog.net.ChannelRequest | null)

The created channel request.

code »

goog.net.BrowserChannel.getStatEventTarget() ⇒

(goog.events.EventTarget | null)

Returns the singleton event target for stat events.

Returns:

(goog.events.EventTarget | null)

The event target for stat events.

code »

goog.net.BrowserChannel.isFatalError_(error, statusCode) ⇒

Returns whether or not the given error/status combination is fatal or not. On fatal errors we immediately close the session rather than retrying the failed request.

Arguments:

error :

(goog.net.ChannelRequest.Error.<number> | null)

The error code for the failed request.

statusCode :

The last HTTP status code.

Returns:

Whether or not the error is fatal.

code »

goog.net.BrowserChannel.notifyStatEvent(stat)

Helper function to call the stat event callback.

Arguments:

stat :

goog.net.BrowserChannel.Stat.<number>

The stat.

code »

goog.net.BrowserChannel.notifyTimingEvent(size, rtt, retries)

Helper function to notify listeners about POST request performance.

Arguments:

size :

Number of characters in the POST data.

rtt :

The amount of time from POST start to response.

retries :

The number of times the POST had to be retried.

code »

goog.net.BrowserChannel.onEndExecution()

Helper function to call the end hook

code »

goog.net.BrowserChannel.onStartExecution()

Helper function to call the start hook

code »

goog.net.BrowserChannel.setEndThreadExecutionHook(endHook)

Allows the application to set an execution hooks for when BrowserChannel stops processing requests. This is useful to track timing or logging special information. The function takes no parameters and return void.

Arguments:

endHook :

(Function | null)

The function for the end hook.

code »

goog.net.BrowserChannel.setStartThreadExecutionHook(startHook)

Allows the application to set an execution hooks for when BrowserChannel starts processing requests. This is useful to track timing or logging special information. The function takes no parameters and return void.

Arguments:

startHook :

(Function | null)

The function for the start hook.

code »

goog.net.BrowserChannel.setTimeout(fn, ms) ⇒

Wrapper around SafeTimeout which calls the start and end execution hooks with a try...finally block.

Arguments:

fn :

(Function | null)

The callback function.

ms :

The time in MS for the timer.

Returns: