Class: Service

Defined in: src/service.coffee

Overview

The representation of a connection to an InterMine web-service.

The Service class is the entry-point into the imjs library, and the focal point for communication with the server. Connections to specific services are instantiated with reference to their base url and optional authentication information for accessing private user data. If data is required from more than one user at the same service, multiple connection objects should be instantiated, each authenticated to the appropriate user (requests that return data that can be cached between users will be made as most once, unless the service is connected with the 'noCache' option.

Instance Method Summary

Constructor Details

- (void) constructor()

Construct a new connection to a service.

Parameters:

  • options (Object) — The configuration information used by the service

Options Hash: (options):

  • root (String) — The base URL of the webservice (required). This is typically of the form "http://HOST/PATH", eg: "http://www.flymine.org/query"
  • token (String) — An authentication token (optional)
  • errorHandler ((err) ->) — A function that handles errors. (optional) If any errors occur when making HTTP calls to the server, the errors will be logged by this global error handler, which by default logs to the console. This can be changed by passing an alternative error handler, such as (->) to suppress error logging.
  • DEBUG (boolean) — Whether to log extra debug information (optional).
  • help (String) — An email address to show to the user if help is needed (optional).
  • noCache (boolean) — Set this flag to true to prevent the use of the global results caches for non-volatile data (models, versions, etc). Each service instance will still continue to use its own private cache.

Instance Method Details

- (Promise<Object>) post(path, data)

Convenience method for making basic POST requests.

Parameters:

  • path (String) — The endpoint to post to.
  • data (Object<String, String>, Array<[String, String]>) — parameters to send (optional)

Returns:

  • (Promise<Object>) — A promise to yield a response object.

- (Promise<Object>) get(path, data)

Convenience method for making basic GET requests.

Parameters:

  • path (String) — The endpoint to get from.
  • data (Object<String, String>, Array<[String, String]>) — parameters to send (optional)

Returns:

  • (Promise<Object>) — A promise to yield a response object.

- (Promise<Object>) makeRequest(method = 'GET', path = '', data = {}, cb = (function() {}), indiv = false)

The generalised method through which ALL requests pass when using this class. You should not use this method; instead use one of the specific methods on this class (such as Service#fetchModel, or Service#fetchVersion) or one of the methods on the Query object.

TL/DR: Don't. Finger weg.

All parameters are optional.

Parameters:

  • method (String) — The HTTP method to use (one of GET, POST, PUT, DELETE).
  • path (String) — The path fragment of the endpoint to use. The service's root will be prepended to obtain the full URI.
  • data (Object, Array) — The parameters to send to the service.
  • cb ((data) ->) — A function that will be called on the results when received.
  • indiv (boolean) — A flag determinig whether to treat the results as a single block, or whether to yield individual results to the cb item by item. This only makes sense in the node.js context. Don't use this.

Returns:

  • (Promise<Object>) — A promise to yield a response object.

- (void) authorise(req)

TODO - when 14 is prevalent the fetchVersion can be removed.

- (Promise<Array<Object>>) enrichment(opts, cb) (bound)

Get the results of using a list enrichment widget to calculate statistics for a set of objects. An enrichment calculation attempts to find related items that are particularly characteristic of the items in this list.

Parameters:

  • opts (Object<String, String>) — The parameters to pass to the calculation.
  • cb (->) — A function to call with the results when they have been received (optional).

Options Hash: (opts):

  • list (String) — The name of the list to analyse.
  • widget (String) — The name of the enrichment calculation to use.
  • maxp (Number) — The maximum permissible p-value (optional, default = 0.05).
  • correction (String) — The correction algorithm to use (default = Holm-Bonferroni).
  • population (String) — The name of a list to use as a background population (optional).
  • filter (String) — An extra value that some widget calculations accept.

Returns:

  • (Promise<Array<Object>>) — A promise to get results.

- (Promise<Object>) search(options = {}, cb = (function() {}))

Search for items in the database by any term or facet.

This method performs a wide-ranging free-text search (powered by Lucene) for items in the database matching a given term. The data returned is limited to a precalculated document of key-fields for each object. To further explore the dataset, the user will want to construct more sophisticated queries. See Query.

The yielded result has a results property and a facets property.

Parameters:

  • options (Object) — A collection of parameters.
  • An ((Array.<Object>, Object, Object) ->) — optional call-back function.

Options Hash: (options):

  • q (String) — The term to search by.
  • facets (Object<String, String>) — A set of facet constraints.

Returns:

  • (Promise<Object>) — A promise to search the database.

- (Promise<PathInfo>) makePath(path, subclasses = {}, cb = (function() {}))

Make a PathInfo object from a string

Sugar for service.fetchModel().then (m) -> m.makePath path, subclasses

Parameters:

  • path (String) — The path string.
  • subclasses (Object<String, String>) — The subclass info.
  • cb (Function<Error, PathInfo, Void>) — An optional callback.

Returns:

  • (Promise<PathInfo>) — A promise to yield a PathInfo object.

- (Promise<Number>) count(q, cb = (function() {})) (bound)

Find out how many rows a given query would return when run.

Parameters:

  • The (Query|PathInfo|String|Object) — query to run. If it is not already instantiated as a Query object, it will be, so the JSON definition of a query can be used here. Alternatively a single path argument (as a PathInfo object or as a string) may be used, in which cases the count of all unique values for that path will be returned.
  • cb ((Number) ->) — A callback that receives a number. Optional.

Returns:

  • (Promise<Number>) — A promise to yield a count.

- (Promise<Object>) findById(type, id, cb) (bound)

Retrieve a representation of a specific object.

Parameters:

  • type (String) — The type of the object to find (eg: Gene)
  • id (Number) — The internal DB id of the object.
  • A ((obj) ->) — callback that receives an object. (optional).

Returns:

  • (Promise<Object>) — A promise to yield an object.

- (Promise<Array<Object>>) lookup(type, term, context, cb)

Find all the objects in the database that match the search term.

Parameters:

  • type (String) — The type of the object to find (eg: Gene)
  • term (String) — A search term to use. This may use wild-cards and comma separated sub-terms. eg: "eve, zen, bib, r, H"
  • cb ((Array<Object>) ->) — A callback that receives an Array of objects. (optional).

Returns:

  • (Promise<Array<Object>>) — A promise to yield an array of objects.

- (Promise<Array<Object>>) find(type, term, context, cb)

Find the single object that matches the given term, or report an error if none is found, or more than one is found.

Parameters:

  • type (String) — The type of the object to find (eg: Gene)
  • term (String) — A search term to use. This may use wild-cards and comma separated sub-terms. eg: "eve, zen, bib, r, H"
  • cb ((Array<Object>) ->) — A callback that receives an Array of objects. (optional).

Returns:

  • (Promise<Array<Object>>) — A promise to yield an array of objects.

- (Promise<User>) whoami(cb) (bound)

Retrieve information about the currently authenticated user.

Parameters:

  • cb ((User) ->) — A callback the receives a User object.

Returns:

  • (Promise<User>) — A promise to yield a user.

- (void) fetchUser(args...) (bound)

Alias for Service#whoami

- (Promise<Array<Object>, Number>) pathValues(path, typeConstraints = {}, cb) (bound)

Retrieve a list of values that a path can have. This functionality is expected to be of use when developing auto-completion interfaces.

Parameters:

  • path (.toString|PathInfo) — The path to evaluate.
  • typeConstraints (Object<String, String>) — The type constraints on this path. (only required if there are any. Default = {}).
  • cb ((Array<Object>|Number) ->) — An optional callback.

Returns:

  • (Promise<Array<Object>, Number>) — A promise to return a list of objects with two properties ('count' and 'value').

See also:

  • {Query#summarise}

- (Promise<Array<?>>) table(q, page, cb) (bound)

Get a page of results in jsontable format.

Parameters:

  • q (Query|Object) — The query to request results for. If not a Query, the object will be lifted to one via Service#query
  • page (Object) — An object specifying the page (optional).
  • cb (->) — A call-back to which results will be yielded. (optional).

Options Hash: (page):

  • start (Number) — The index of the first result to retrieve (default = 0).
  • size (Number) — The maximum number of results to retrieve (default = null, ie. 'all').

Returns:

  • (Promise<Array<?>>) — A promise to yield results.

- (Promise<Array<Object>>) records(q, page, cb) (bound)

Get a page of results in jsonobject format.

Parameters:

  • q (Query|Object) — The query to request results for. If not a Query, the object will be lifted to one via Service#query
  • page (Object) — An object specifying the page (optional).
  • cb (->) — A call-back to which results will be yielded. (optional).

Options Hash: (page):

  • start (Number) — The index of the first result to retrieve (default = 0).
  • size (Number) — The maximum number of results to retrieve (default = null, ie. 'all').

Returns:

  • (Promise<Array<Object>>) — A promise to yield results.

- (Promise<Array<Array<Object>>) rows(q, page, cb) (bound)

Get a page of results in json format.

Parameters:

  • q (Query|Object) — The query to request results for. If not a Query, the object will be lifted to one via Service#query
  • page (Object) — An object specifying the page (optional).
  • cb (->) — A call-back to which results will be yielded. (optional).

Options Hash: (page):

  • start (Number) — The index of the first result to retrieve (default = 0).
  • size (Number) — The maximum number of results to retrieve (default = null, ie. 'all').

Returns:

  • (Promise<Array<Array<Object>>) — A promise to yield results.

- (Promise<<Array<Object>) values(q, opts, cb) (bound)

Get a page of values.

   If a PathInfo object or a String, then the pathValues method
   will be run instead (backward compatibility). Otherwise the first
   argument will be treated as a query as per the Service#rows method.

Parameters:

  • q (Query|Object|PathInfo|String) — The query to request results for.
  • opts (Object) — Either a page, or options for pathValues.
  • cb (->) — A call-back to which results will be yielded. (optional).

Returns:

  • (Promise<<Array<Object>) — A promise to yield results.

- (Promise<Array<Array<Object>>) tableRows(q, page, cb) (bound)

Get a page of results suitable for building the cells in a table.

Parameters:

  • q (Query|Object) — The query to request results for. If not a Query, the object will be lifted to one via Service#query
  • page (Object) — An object specifying the page (optional).
  • cb (->) — A call-back to which results will be yielded. (optional).

Options Hash: (page):

  • start (Number) — The index of the first result to retrieve (default = 0).
  • size (Number) — The maximum number of results to retrieve (default = null, ie. 'all').

Returns:

  • (Promise<Array<Array<Object>>) — A promise to yield results.

- (Promise<Object>) fetchTemplates(cb) (bound)

Get the templates this user currently has access to.

Parameters:

  • cb ((Error?, Array<Object>) ->) — A callback (optional).

Returns:

  • (Promise<Object>) — A promise to yield a mapping of templates.

- (Promise<Array<List>>) fetchLists(cb) (bound)

Get the lists this user currently has access to.

Parameters:

  • cb ((Array<List>) ->) — A callback (optional).

Returns:

  • (Promise<Array<List>>) — A promise to yield an array of List objects.

- (Promise<Array<List>>) findLists(name = '', cb = (function() {})) (bound)

Get the lists this user currently has access to which match the given name.

Parameters:

  • name (String) — The name the lists we want to find must have (may include wildcards). (Optional - default = '', ie. all lists).
  • cb ((Array<List>) ->) — A callback (optional).

Returns:

  • (Promise<Array<List>>) — A promise to yield an array of List objects.

- (Promise<List>) fetchList(name, cb) (bound)

Get a list by name.

Parameters:

  • name (String) — The exact name of the list.
  • cb (->) — A callback function (optional).

Returns:

  • (Promise<List>) — A promise to yield a List.

- (Promise<Array<List>>) fetchListsContaining(opts, cb) (bound)

Get the lists that contain the given object.

Parameters:

  • opts (Object) — The options that specify which object.
  • cb (->) — A callback function (Optional).

Options Hash: (opts):

  • publicId (String) — The stable identifier of the object (eg. for a Gene, the symbol).
  • extraValue (String) — A disambiguating value (eg. for a Gene, the name of the Organism it belongs to).
  • id (#toString) — If known, an object may be referenced by its internal DB id instead. These are NOT stable between releases of the webapp, so should never be stored.

Returns:

  • (Promise<Array<List>>) — A promise to yield an array of List objects.

- (Promise<List>) combineLists(operation, options, cb)

Combine two or more lists using the given operation.

Parameters:

  • operation (String) — One of ['merge', 'intersect', 'diff'].
  • options (Object) — The options that describe what to combine.
  • cb ((List) ->) — A callback function. (optional).

Options Hash: (options):

  • name (String) — The name of the new list.
  • description (String) — The description of the new list. (optional - defaults to "operation of listA, listB")
  • lists (Array<String>) — The lists to combine.
  • tags (Array<String>) — A set of tags to apply to the new list (optional).

Returns:

  • (Promise<List>) — A promise to yield a List object.

- (Promise<List>) merge()

Combine two or more lists through a union operation.

also available as {Service#union}.

Parameters:

  • options (Object) — The options that describe what to combine.
  • cb ((List) ->) — A callback function. (optional).

Options Hash: (options):

  • name (String) — The name of the new list.
  • description (String) — The description of the new list. (optional - defaults to "operation of listA, listB")
  • lists (Array<String>) — The lists to combine.
  • tags (Array<String>) — A set of tags to apply to the new list (optional).

Returns:

  • (Promise<List>) — A promise to yield a List object.

- (Promise<List>) intersect()

Combine two or more lists through an intersection operation.

Parameters:

  • options (Object) — The options that describe what to combine.
  • cb ((List) ->) — A callback function. (optional).

Options Hash: (options):

  • name (String) — The name of the new list.
  • description (String) — The description of the new list. (optional - defaults to "operation of listA, listB")
  • lists (Array<String>) — The lists to combine.
  • tags (Array<String>) — A set of tags to apply to the new list (optional).

Returns:

  • (Promise<List>) — A promise to yield a List object.

- (Promise<List>) diff()

Combine two more lists through a symmetric difference opertation.

Parameters:

  • options (Object) — The options that describe what to combine.
  • cb ((List) ->) — A callback function. (optional).

Options Hash: (options):

  • name (String) — The name of the new list.
  • description (String) — The description of the new list. (optional - defaults to "operation of listA, listB")
  • lists (Array<String>) — The lists to combine.
  • tags (Array<String>) — A set of tags to apply to the new list (optional).

Returns:

  • (Promise<List>) — A promise to yield a List object.

- (Promise<List>) complement(options = {}, cb = function() {}) (bound)

Create a new list from the complement of two groups of lists. The complement is often what is meant by the concept of subtraction, in that the result of this operation will always be a proper subset of the union of the references.

Parameters:

  • options (Object) — The parameters to this option.
  • cb ((List) ->) — cb An optional callback.

Options Hash: (options):

  • name (String) — The name for the new list. (optional, defaults to "The reverse complement of B in A")
  • description (String) — The description of the new list (optional, defailts to "The reverse complement of B in A")
  • tags (String|Array<String>) — The tags the new list should have.
  • from (String|List|Array<String|List>) — The lists that serve as the left hand side in the complement, ie. the union of lists we will subtract items from.
  • exclude (String|List|Array<String|List>) — The lists that serve as the right hand side in the complement, ie. the union of lists we will subtract from the reference lists.

Returns:

  • (Promise<List>) — A promise to yield a List.

- (Promise<Array<Object>>) fetchWidgets(cb) (bound)

Fetch the list widgets that are available from this service.

Returns:

  • (Promise<Array<Object>>) — A promise to yield a list of widgets.

- (void) fetchWidgetMap(cb) (bound)

- (Promise<Model>) fetchModel(cb) (bound)

Fetch the description of the data model for this service.

Returns:

  • (Promise<Model>) — A promise to yield metadata about this service.

- (Promise<Object<String, Array<String>>>) fetchSummaryFields(cb) (bound)

Fetch the configured summary-fields. The summary fields describe which fields should be used to summarise each class.

Returns:

  • (Promise<Object<String, Array<String>>>) — A promise to yield a mapping from class-name to a list of paths.

- (Promise<Number>) fetchVersion(cb) (bound)

Fetch the number that describes the web-service capabilities.

Returns:

  • (Promise<Number>) — A promise to yield a version number.

- (void) fetchClassKeys(cb) (bound)

- (void) fetchRelease(cb) (bound)

- (Promise<Query>) query(options, cb) (bound)

Promise to make a new Query.

Parameters:

  • options (Object) — The JSON representation of the query. See Query#constructor for more information on the structure of these options.
  • cb ((Error?, Query) ->) — An optional callback to be called when the query is made.

Returns:

  • (Promise<Query>) — A promise to yield a new Query.

- (Promise<Query>) savedQuery(name, cb) (bound)

Load a saved query by name.

Parameters:

  • name (String) — The name of the query.
  • cb ((Error?, Query) ->) — An optional node-style callback.

Returns:

  • (Promise<Query>) — A promise to yield a query.

- (Promise<Query>) templateQuery(name, cb) (bound)

Load a template query by name.

Parameters:

  • name (String) — The name of the template
  • cb ((Error?, Query) ->) — An optional node-style callback.

Returns:

  • (Promise<Query>) — A promise to return a query.

- (Promise<IDResolutionJob>) resolveIds(opts, cb) (bound)

Submit an ID resolution job.

Parameters:

  • opts (Object) — The parameters to the id resolution service.
  • cb (->) — An optional callback.

Options Hash: (opts):

  • identifiers (Array<String>) — The identifiers you want to resolve.
  • type (String) — The type of objects these identifiers refer to.
  • extra (String) — Extra values that can be used to disambiguate values (optional).
  • caseSensitive (boolean) — Whether these identifiers should be treated as case-sensitive. (optional).
  • wildCards (boolean) — Whether wild-cards should be allowed in these identifiers. (optional).

Returns:

- (Promise<List>) createList(opts = {}, ids = '', cb = function() {}) (bound)

Create a new list through the identifier upload service.

This service takes a source of identifiers and attempts to resolve them automatically and create a new list for the results. If you require more fine-grained control over this functionality then see [Service#resolveIds].

Parameters:

  • opts (Object) — The options for this list upload.
  • ids (Array<String>|String) — The identifiers to resolve.
  • cb ((Error, List) -> Any) — A function that receives a List.

Options Hash: (opts):

  • name (String) — The name for this list (required).
  • type (String) — The type of objects (eg. Gene) these are identifiers of (required).
  • description (String) — A description for the new list (optional).
  • extraValue (String) — A disambiguating value (optional).
  • tags (Array<String>) — A list of tags to apply to the new list (optional).

Returns:

  • (Promise<List>) — A promise to yield a List.

- (Service) connectAs(token) (bound)

Return a new service with the same root url as this one, but connected as a different user.

Parameters:

  • token (String) — The token for the user to connect as.

Returns:

  • (Service) — A new connection to a service.

- (Promise<Service>) register(name, password, cb)

Create a new user at the current service.

Parameters:

  • name (String) — The name of the new user. Used a login.
  • password (String) — The cleartext version of the user's password.
  • cb ((Error, Service) -> Any) — An optional callback.

Returns:

  • (Promise<Service>) — A promise to yield a new service for use with the new user.

- (Promise<String>) getDeregistrationToken(validity = FIVE_MIN, cb)

Promise to get a deregistration token.

To provide some security to the account deregistration process account deactivation is a two-stage process - first a deregistration token must be acquired, and only then can a request to delete a user be made.

Parameters:

  • The (Number) — number of seconds the token should be valid (default = 5 minutes).
  • An ((Error, String) -> Any) — optional callback.

Returns:

  • (Promise<String>) — A promise to return a token which can be used to delete an account.

- (Promise<String>) deregister(token, cb)

Return a promise to delete a user account, and retrieve all of its data.

Before the user this service is connected to can be deleted, a deregistration token must be obtained via a call to 'getDeregistrationToken'.

Parameters:

  • The (String) — deregistration token to activate.
  • An ((Error, String) -> Any) — optional callback

Returns:

  • (Promise<String>) — A promise to yield all the userdata for an account as XML.

- (Promise<Service>) login(name, password, cb)

Promise to return a service with the same root as this one, but associated with a different user account - the one specified by the login details.

Parameters:

  • cb ((Error, Service) -> Any) — An optional callback

Returns:

  • (Promise<Service>) — A promise to yield a service.

- (Promise<Service>) logout(cb)

Promise to return a service with the same root as this one, but not associated with any user account. Attempts to use the yielded service to make list requests and other requests that require authenticated access will fail.

Parameters:

  • cb ((Error, Service) -> Any) — An optional callback

Returns:

  • (Promise<Service>) — A promise to yield a service.