Class: Connection

Connection(baseUrl, optionsopt, urlopt, nullable)

A connection to a back-end.

Constructor

new Connection(baseUrl, optionsopt, urlopt, nullable)

Creates a new Connection.

Parameters:
Name Type Attributes Default Description
baseUrl string

The versioned URL or the back-end instance.
options Options <optional>
 {}

Additional options for the connection.
url string <optional>
<nullable>
 null

User-provided URL of the backend connected to.
Source:

Members

(protected) authProvider :AuthProvider|null

Current auth provider

Type:
Source:

(protected) authProviderList :Array.<AuthProvider>|null

Auth Provider cache

Type:
Source:

(protected) baseUrl :string

The versioned URL or the back-end instance.

Type:
  • string
Source:

(protected) capabilitiesObject :Capabilities|null

Capability cache

Type:
Source:

(protected) listeners :object.<(string|function())>

Listeners for events.

Type:
  • object.<(string|function())>
Source:

(protected) options :Options

Additional options for the connection.

Type:
Source:

(protected) processes :ProcessRegistry

Process cache

Type:
  • ProcessRegistry
Source:

(protected) url :string|null

User-provided URL of the backend connected to.

null if not given and the connection was directly made to a versioned instance of the back-end.

Type:
  • string | null
Source:

Methods

(async, protected) _delete(path) → {Promise.<AxiosResponse>}

Sends a DELETE request.

Parameters:
Name Type Description
path string
Source:
Throws:
Error
Returns:
Type
Promise.<AxiosResponse>

(async, protected) _get(path, query, responseType) → {Promise.<AxiosResponse>}

Sends a GET request.

Parameters:
Name Type Description
path string
query object.<string, *>
responseType string

Response type according to axios, defaults to json.
Source:
See:
Throws:
Error
Returns:
Type
Promise.<AxiosResponse>

(protected) _getLinkHref(links, rel) → {string|null}

Get the a link with the given rel type.

Parameters:
Name Type Default Description
links Array.<Link>

An array of links.
rel string next

Relation type to find, defaults to next.
Source:
Throws:
Error
Returns:
Type
string | null

(protected) _normalizeUserProcess(process, additional) → {object.<string, *>}

Takes a UserProcess, BuilderNode or a plain object containing process nodes and converts it to an API compliant object.

Parameters:
Name Type Description
process UserProcess | BuilderNode | object.<string, *>

Process to be normalized.
additional object.<string, *>

Additional properties to be merged with the resulting object.
Source:
Returns:
Type
object.<string, *>

(async, protected) _patch(path, body) → {Promise.<AxiosResponse>}

Sends a PATCH request.

Parameters:
Name Type Description
path string
body *
Source:
Throws:
Error
Returns:
Type
Promise.<AxiosResponse>

(async, protected) _post(path, body, responseType, abortControlleropt, nullable) → {Promise.<AxiosResponse>}

Sends a POST request.

Parameters:
Name Type Attributes Default Description
path string
body *
responseType string

Response type according to axios, defaults to json.
abortController AbortController <optional>
<nullable>
 null

An AbortController object that can be used to cancel the request.
Source:
See:
Throws:
Error
Returns:
Type
Promise.<AxiosResponse>

(async, protected) _put(path, body) → {Promise.<AxiosResponse>}

Sends a PUT request.

Parameters:
Name Type Description
path string
body *
Source:
Throws:
Error
Returns:
Type
Promise.<AxiosResponse>

(async, protected) _send(options, abortControlleropt, nullable) → {Promise.<AxiosResponse>}

Sends a HTTP request.

Options mostly conform to axios, see https://github.com/axios/axios#request-config.

Automatically sets a baseUrl and the authorization information. Default responseType is json.

Tries to smoothly handle error responses by providing an object for all response types, instead of Streams or Blobs for non-JSON response types.

Parameters:
Name Type Attributes Default Description
options object.<string, *>
abortController AbortController <optional>
<nullable>
 null

An AbortController object that can be used to cancel the request.
Source:
See:
Throws:
Error
Returns:
Type
Promise.<AxiosResponse>

(protected) _toResponseArray(arr, response) → {ResponseArray}

Adds additional response details to the array.

Adds links and federation:missing.

Parameters:
Name Type Description
arr Array.<*>
response object.<string, *>
Source:
Returns:
Type
ResponseArray

(async) authenticateBasic(username, password)

Authenticates with username and password against a back-end supporting HTTP Basic Authentication.

DEPRECATED in favor of using listAuthProviders and BasicProvider.

Parameters:
Name Type Description
username string
password string
Deprecated:
  • Yes
Source:
See:

(async) buildProcess(id) → {Promise.<Builder>}

Returns an object to simply build user-defined processes based upon pre-defined processes.

Parameters:
Name Type Description
id string

A name for the process.
Source:
See:
Throws:
Error
Returns:
Type
Promise.<Builder>

capabilities() → {Capabilities}

Returns the capabilities of the back-end.

Source:
Returns:

Capabilities

Type
Capabilities

(async) computeResult(process, planopt, nullable, budgetopt, nullable, abortControlleropt, nullable) → {Promise.<SyncResult>}

Executes a process synchronously and returns the result as the response.

Please note that requests can take a very long time of several minutes or even hours.

Parameters:
Name Type Attributes Default Description
process Process

A user-defined process.
plan string <optional>
<nullable>
 null

The billing plan to use for this computation.
budget number <optional>
<nullable>
 null

The maximum budget allowed to spend for this computation.
abortController AbortController <optional>
<nullable>
 null

An AbortController object that can be used to cancel the processing request.
Source:
Returns:
  • An object with the data and some metadata.
Type
Promise.<SyncResult>

(async) createJob(process, titleopt, nullable, descriptionopt, nullable, planopt, nullable, budgetopt, nullable, additionalopt) → {Promise.<Job>}

Creates a new batch job at the back-end.

Parameters:
Name Type Attributes Default Description
process Process

A user-define process to execute.
title string <optional>
<nullable>
 null

A title for the batch job.
description string <optional>
<nullable>
 null

A description for the batch job.
plan string <optional>
<nullable>
 null

The billing plan to use for this batch job.
budget number <optional>
<nullable>
 null

The maximum budget allowed to spend for this batch job.
additional object.<string, *> <optional>
 {}

Proprietary parameters to pass for the batch job.
Source:
Throws:
Error
Returns:

The stored batch job.

Type
Promise.<Job>

(async) createService(process, type, titleopt, nullable, descriptionopt, nullable, enabledopt, configurationopt, planopt, nullable, budgetopt, nullable, additionalopt) → {Promise.<Service>}

Creates a new secondary web service at the back-end.

Parameters:
Name Type Attributes Default Description
process Process

A user-defined process.
type string

The type of service to be created (see Connection.listServiceTypes()).
title string <optional>
<nullable>
 null

A title for the service.
description string <optional>
<nullable>
 null

A description for the service.
enabled boolean <optional>
 true

Enable the service (true, default) or not (false).
configuration object.<string, *> <optional>
 {}

Configuration parameters to pass to the service.
plan string <optional>
<nullable>
 null

The billing plan to use for this service.
budget number <optional>
<nullable>
 null

The maximum budget allowed to spend for this service.
additional object.<string, *> <optional>
 {}

Proprietary parameters to pass for the batch job.
Source:
Throws:
Error
Returns:

The stored service.

Type
Promise.<Service>

(async) describeAccount() → {Promise.<UserAccount>}

Get information about the authenticated user.

Updates the User ID if available.

Source:
Throws:
Error
Returns:

A response compatible to the API specification.

Type
Promise.<UserAccount>

(async) describeCollection(collectionId) → {Promise.<Collection>}

Get further information about a single collection.

The collection returned always complies to the latest STAC version (currently 1.0.0).

Parameters:
Name Type Description
collectionId string

Collection ID to request further metadata for.
Source:
Throws:
Error
Returns:
  • A response compatible to the API specification.
Type
Promise.<Collection>

(async) describeProcess(processId, namespaceopt, nullable) → {Promise.<?Process>}

Get information about a single process.

Parameters:
Name Type Attributes Default Description
processId string

Collection ID to request further metadata for.
namespace string <optional>
<nullable>
 null

Namespace of the process (default to null, i.e. pre-defined processes). EXPERIMENTAL!
Source:
See:
Throws:
Error
Returns:
  • A single process as object, or null if none is found.
Type
Promise.<?Process>

(async) download(url, authorize) → {Promise.<(Stream.Readable|Blob)>}

Downloads data from a URL.

May include authorization details where required.

Parameters:
Name Type Description
url string

An absolute or relative URL to download data from.
authorize boolean

Send authorization details (true) or not (false).
Source:
Throws:
Error
Returns:
  • Returns the data as Stream in NodeJS environments or as Blob in browsers
Type
Promise.<(Stream.Readable|Blob)>

(async) downloadResult(process, targetPath, planopt, nullable, budgetopt, nullable, abortControlleropt, nullable)

Executes a process synchronously and downloads to result the given path.

Please note that requests can take a very long time of several minutes or even hours.

This method has different behaviour depending on the environment. If a NodeJs environment, writes the downloaded file to the target location on the file system. In a browser environment, offers the file for downloading using the specified name (folders are not supported).

Parameters:
Name Type Attributes Default Description
process Process

A user-defined process.
targetPath string

The target, see method description for details.
plan string <optional>
<nullable>
 null

The billing plan to use for this computation.
budget number <optional>
<nullable>
 null

The maximum budget allowed to spend for this computation.
abortController AbortController <optional>
<nullable>
 null

An AbortController object that can be used to cancel the processing request.
Source:
Throws:
Error

(protected) emit(event, …args)

Emits the given event.

Parameters:
Name Type Attributes Description
event string
args * <repeatable>
Source:

getAuthProvider() → {AuthProvider|null}

Returns the AuthProvider.

Source:
Returns:
Type
AuthProvider | null

getBaseUrl() → {string}

Returns the URL of the versioned back-end instance currently connected to.

Source:
Returns:

The versioned URL or the back-end instance.

Type
string

(async) getFile(path) → {Promise.<UserFile>}

Opens a (existing or non-existing) file without reading any information or creating a new file at the back-end.

Parameters:
Name Type Description
path string

Path to the file, relative to the user workspace.
Source:
Throws:
Error
Returns:

A file.

Type
Promise.<UserFile>

(async) getJob(id) → {Promise.<Job>}

Get all information about a batch job.

Parameters:
Name Type Description
id string

Batch Job ID.
Source:
Throws:
Error
Returns:

The batch job.

Type
Promise.<Job>

getOidcProviderFactory() → {oidcProviderFactoryFunction|null}

Get the OpenID Connect provider factory.

Returns null if OIDC is not supported by the client or an instance can't be created for whatever reason.

Source:
See:
Returns:
Type
oidcProviderFactoryFunction | null

(async) getService(id) → {Promise.<Service>}

Get all information about a secondary web service.

Parameters:
Name Type Description
id string

Service ID.
Source:
Throws:
Error
Returns:

The service.

Type
Promise.<Service>

getUrl() → {string}

Returns the user-provided URL of the back-end currently connected to.

Source:
Returns:

The URL or the back-end.

Type
string

(async) getUserProcess(id) → {Promise.<UserProcess>}

Get all information about a user-defined process.

Parameters:
Name Type Description
id string

Identifier of the user-defined process.
Source:
Throws:
Error
Returns:

The user-defined process.

Type
Promise.<UserProcess>

(async, protected) init() → {Promise.<Capabilities>}

Initializes the connection by requesting the capabilities.

Source:
Returns:

Capabilities

Type
Promise.<Capabilities>

isAuthenticated() → {boolean}

Returns whether the user is authenticated (logged in) at the back-end or not.

Source:
Returns:

true if authenticated, false if not.

Type
boolean

(async) listAuthProviders() → {Promise.<Array.<AuthProvider>>}

List all authentication methods supported by the back-end.

Source:
See:
Throws:
Error
Returns:

An array containing all supported AuthProviders (including all OIDC providers and HTTP Basic).

Type
Promise.<Array.<AuthProvider>>

(async, generator) listCollectionItems(collectionId, spatialExtentopt, nullable, temporalExtentopt, nullable, limitopt, nullable) → {Promise.<ItemCollection>}

Loads items for a specific image collection. May not be available for all collections.

The items returned always comply to the latest STAC version (currently 1.0.0).

This is an experimental API and is subject to change.

Parameters:
Name Type Attributes Default Description
collectionId string

Collection ID to request items for.
spatialExtent Array.<number> <optional>
<nullable>
 null

Limits the items to the given bounding box in WGS84:

  1. Lower left corner, coordinate axis 1
  2. Lower left corner, coordinate axis 2
  3. Upper right corner, coordinate axis 1
  4. Upper right corner, coordinate axis 2
temporalExtent Array <optional>
<nullable>
 null

Limits the items to the specified temporal interval. The interval has to be specified as an array with exactly two elements (start, end) and each must be either an RFC 3339 compatible string or a Date object. Also supports open intervals by setting one of the boundaries to null, but never both.
limit number <optional>
<nullable>
 null

The amount of items per request/page as integer. If null (default), the back-end decides.
Source:
Throws:
Error
Yields:
A response compatible to the API specification.
Type
Promise.<ItemCollection>

(async) listCollections() → {Promise.<Collections>}

List all collections available on the back-end.

The collections returned always comply to the latest STAC version (currently 1.0.0).

Source:
Throws:
Error
Returns:

A response compatible to the API specification.

Type
Promise.<Collections>

(async) listFiles() → {Promise.<ResponseArray.<UserFile>>}

Lists all files from the user workspace.

Source:
Throws:
Error
Returns:

A list of files.

Type
Promise.<ResponseArray.<UserFile>>

(async) listFileTypes() → {Promise.<FileTypes>}

List the supported output file formats.

Source:
Throws:
Error
Returns:

A response compatible to the API specification.

Type
Promise.<FileTypes>

(async) listJobs(oldJobsopt) → {Promise.<ResponseArray.<Job>>}

Lists all batch jobs of the authenticated user.

Parameters:
Name Type Attributes Default Description
oldJobs Array.<Job> <optional>
 []

A list of existing jobs to update.
Source:
Throws:
Error
Returns:

A list of jobs.

Type
Promise.<ResponseArray.<Job>>

(async) listProcesses(namespaceopt, nullable) → {Promise.<Processes>}

List processes available on the back-end.

Requests pre-defined processes by default. Set the namespace parameter to request processes from a specific namespace.

Note: The list of namespaces can be retrieved by calling listProcesses without a namespace given. The namespaces are then listed in the property namespaces.

Parameters:
Name Type Attributes Default Description
namespace string <optional>
<nullable>
 null

Namespace of the processes (default to null, i.e. pre-defined processes). EXPERIMENTAL!
Source:
Throws:
Error
Returns:
  • A response compatible to the API specification.
Type
Promise.<Processes>

(async) listServices(oldServicesopt) → {Promise.<ResponseArray.<Job>>}

Lists all secondary web services of the authenticated user.

Parameters:
Name Type Attributes Default Description
oldServices Array.<Service> <optional>
 []

A list of existing services to update.
Source:
Throws:
Error
Returns:

A list of services.

Type
Promise.<ResponseArray.<Job>>

(async) listServiceTypes() → {Promise.<object.<string, ServiceType>>}

List the supported secondary service types.

Source:
Throws:
Error
Returns:

A response compatible to the API specification.

Type
Promise.<object.<string, ServiceType>>

(async) listUdfRuntimes() → {Promise.<object.<string, UdfRuntime>>}

List the supported UDF runtimes.

Source:
Throws:
Error
Returns:

A response compatible to the API specification.

Type
Promise.<object.<string, UdfRuntime>>

(async) listUserProcesses(oldProcessesopt) → {Promise.<ResponseArray.<UserProcess>>}

Lists all user-defined processes of the authenticated user.

Parameters:
Name Type Attributes Default Description
oldProcesses Array.<UserProcess> <optional>
 []

A list of existing user-defined processes to update.
Source:
Throws:
Error
Returns:

A list of user-defined processes.

Type
Promise.<ResponseArray.<UserProcess>>

(protected) normalizeNamespace(namespacenullable) → (nullable) {string}

Normalisation of the namespace to a value that is compatible with the OpenEO specs - EXPERIMENTAL.

This is required to support UDP that are shared as public. These can only be executed with providing the full URL (e.g. https:///processes//<process_id>) as the namespace value in the processing graph. For other parts of the API (such as the listing of the processes, only the name of the namespace is required.

This function will extract the short name of the namespace from a shareable URL.

Parameters:
Name Type Attributes Description
namespace string <nullable>

Namespace of the process
Source:
Returns:
Type
string

off(event)

Removes a listener from the given event.

Parameters:
Name Type Description
event string
Source:

on(event, callback)

Registers a listener with the given event.

Currently supported:

  • authProviderChanged(provider): Raised when the auth provider has changed.
  • tokenChanged(token): Raised when the access token has changed.
  • processesChanged(type, data, namespace): Raised when the process registry has changed (i.e. a process was added, updated or deleted).
Parameters:
Name Type Description
event string
callback function
Source:

(async, protected) refreshProcessCache() → {Promise}

Refresh the cache for processes.

Source:
Returns:
Type
Promise

setAuthProvider(provider)

Sets the AuthProvider.

Parameters:
Name Type Description
provider AuthProvider
Source:

setAuthToken(type, providerId, token) → {AuthProvider}

Sets the authentication token for the connection.

This creates a new custom AuthProvider with the given details and returns it. After calling this function you can make requests against the API.

This is NOT recommended to use. Only use if you know what you are doing. It is recommended to authenticate through listAuthProviders or related functions.

Parameters:
Name Type Description
type string

The authentication type, e.g. basic or oidc.
providerId string

The provider identifier. For OIDC the id of the provider.
token string

The actual access token as given by the authentication method during the login process.
Source:
Returns:
Type
AuthProvider

setOidcProviderFactory(providerFactoryFuncopt, nullable)

Sets a factory function that creates custom OpenID Connect provider instances.

You only need to call this if you have implemented a new AuthProvider based on the AuthProvider interface (or OIDCProvider class), e.g. to use a OIDC library other than oidc-client-js.

Parameters:
Name Type Attributes Default Description
providerFactoryFunc oidcProviderFactoryFunction <optional>
<nullable>
 null
Source:
See:

(async) setUserProcess(id, process) → {Promise.<UserProcess>}

Creates a new stored user-defined process at the back-end.

Parameters:
Name Type Description
id string

Unique identifier for the process.
process Process

A user-defined process.
Source:
Throws:
Error
Returns:

The new user-defined process.

Type
Promise.<UserProcess>

(async) uploadFile(source, targetPathopt, nullable, statusCallbackopt, nullable, abortControlleropt, nullable) → {Promise.<UserFile>}

Uploads a file to the user workspace. If a file with the name exists, overwrites it.

This method has different behaviour depending on the environment. In a nodeJS environment the source must be a path to a file as string. In a browser environment the source must be an object from a file upload form.

Parameters:
Name Type Attributes Default Description
source *

The source, see method description for details.
targetPath string <optional>
<nullable>
 null

The target path on the server, relative to the user workspace. Defaults to the file name of the source file.
statusCallback uploadStatusCallback <optional>
<nullable>
 null

Optionally, a callback that is executed on upload progress updates.
abortController AbortController <optional>
<nullable>
 null

An AbortController object that can be used to cancel the upload process.
Source:
Throws:
Error
Returns:
Type
Promise.<UserFile>

(async) validateProcess(process) → {Promise.<Array.<ApiError>>}

Validates a user-defined process at the back-end.

Parameters:
Name Type Description
process Process

User-defined process to validate.
Source:
Throws:
Error
Returns:

errors - A list of API compatible error objects. A valid process returns an empty list.

Type
Promise.<Array.<ApiError>>