Namespace: bitbucket/util/server

Methods

<static> ajax(options) → {jqXHR}

This function closely resembles the jQuery.ajax() function with a few notable exceptions.

First, it only accepts the options signature - all options including url must be included on the options object.

Second, it adds default error handling for all HTTP error codes and for cases where logged in state changes.

Third, it overrides the statusCode option to allow you to specify your own error handling per-HTTP code.

Parameters:

Name	Type	Description
options	Object	A map of option values. All options accepted by jQuery.ajax are accepted here.

Source:

• util/server.js, line 413

Returns:

• A jQuery XHR object.

Type

jqXHR

Example

require('bitbucket/util/server').ajax({
    url : '/plugins/servlet/my-plugin'
    statusCode : {
        400 : false, // do not do any default handling for HTTP 400
        404 : function(xhr, textStatus, errorThrown, dominantError) {
            // return false; // do not handle this by default
            // return myDeferred.promise(); // resolve the request with my custom promise
            return { shouldReload : true }; // open a dialog requesting the user to reload the page.
        }
    }
});

<static> poll(options) → {Promise}

This function builds on rest by adding polling. You can use it to make a request repeatedly, until
a "finished" response is returned. This is useful, for example, when waiting for the server to complete a background task
like deleting a repository or waiting for maintenance to complete.

Parameters:

Name	Type	Description
options	Object	See bitbucket/util/server.rest for the options accepted. Properties Name Type Argument Default Description pollTimeout number | boolean <optional> 60000 The number of milliseconds to poll before ending the poll as a failure. May pass false to indicate no timeout. interval number <optional> 500 The number of milliseconds between each AJAX response and subsequent request. delay number <optional> 0 The number of milliseconds before the first AJAX call. tick function A function to call with each AJAX response's callback parameters. It should return truthy to end polling successfully, undefined to continue polling, or falsy to end polling as a failure.

Source:

• util/server.js, line 502

Returns:

A jQuery Promise with added pause() and resume() methods.

Type

Promise

Example

require('bitbucket/util/server').poll({
    url : '/plugin/servlet/expensive-task-checker',
    tick : function(data, textStatus, xhr) {
        if (data.expensiveTaskComplete) {
            return true; // success
        }
        if (data.expensiveTaskAborted) {
            return false; // failure
        }
        // return undefined; // keep polling. return undefined is implied.
    }
});

<static> rest(options) → {jqXHR}

This function builds on bitbucket/util/server.ajax to add some defaults. It will:

• Default the content type and Accept header to JSON (but this can be overridden).
• Add X-AUSERNAME and X-AUSERID headers for the current user, so the server knows which user we are attempting to make the request as.
• Stringify any JSON objects passed through the data option.
• Adds a fourth argument to the success handler that contains the JSON object parsed from the response body.
• Adds a fourth argument to the error handler that contains a description of how the error would have been handled by default.

Parameters:

Name	Type	Description
options	Object	See bitbucket/util/server.ajax for a description of the accepted options.

Source:

• util/server.js, line 442

Returns:

• A jQuery XHR object.

Type

jqXHR

Example

require('bitbucket/util/server').rest({
    type : 'DELETE',
    url : '/rest/my-plugin/latest/things/1'
    statusCode : {
        404 : function() {
            return $.Deferred().resolve('Already deleted.');
        }
    }
});