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
- # (void) doReq()
- # (Promise<Object>) post(path, data) Convenience method for making basic POST requests.
- # (Promise<Object>) get(path, data) Convenience method for making basic GET requests.
- # (Promise<Object>) makeRequest(method = 'GET', path = '', data = {}, cb = (function() {}), indiv = false) The generalised method through which ALL requests pass when using this class.
- # (void) authorise(req) TODO - when 14 is prevalent the fetchVersion can be removed.
- # (void) attachCustomHeaders(req) Attach custom headers to the request that were supplied to the Service constructor via the options object.
- # (Promise<Array<Object>>) enrichment(opts, cb) Bound Get the results of using a list enrichment widget to calculate statistics for a set of objects.
- # (Promise<Object>) search(options = {}, cb = (function() {})) Search for items in the database by any term or facet.
-
#
(Promise<PathInfo>)
makePath(path, subclasses = {}, cb = (function() {}))
Make a PathInfo object from a string Sugar for
service.fetchModel().then (m) -> m.makePath path, subclasses
- # (Promise<Number>) count(q, cb = (function() {})) Bound Find out how many rows a given query would return when run.
- # (Promise<Object>) findById(type, id, fields = ['**'], cb = (function() {})) Bound Retrieve a representation of a specific object.
- # (Promise<Array<Object>>) lookup(type, term, context, cb) Find all the objects in the database that match the search term.
- # (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.
- # (Promise<User>) whoami(cb) Bound Retrieve information about the currently authenticated 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.
- # (Promise<Array<?>>) doPagedRequest(q, path, page = {}, format, cb = (function() {})) Private Perform a request for results that accepts a parameter specifying the page to fetch.
- # (Promise<Array<?>>) table(q, page, cb) Bound Get a page of results in jsontable format.
- # (Promise<Array<Object>>) records(q, page, cb) Bound Get a page of results in jsonobject format.
- # (Promise<Array<Array<Object>>) rows(q, page, cb) Bound Get a page of results in json format.
- # (Promise<<Array<Object>) values(q, opts, cb) Bound Get a page of values.
- # (Promise<Array<Array<Object>>) tableRows(q, page, cb) Bound Get a page of results suitable for building the cells in a table.
- # (Promise<Object>) fetchTemplates(cb) Bound Get the templates this user currently has access to.
- # (Promise<Array<List>>) fetchLists(cb) Bound Get the lists this user currently has access to.
- # (Promise<Array<List>>) findLists(name = '', cb = (function() {})) Bound Get the lists this user currently has access to which match the given name.
- # (Promise<List>) fetchList(name, cb) Bound Get a list by name.
- # (Promise<Array<List>>) fetchListsContaining(opts, cb) Bound Get the lists that contain the given object.
- # (Promise<List>) combineLists(operation, options, cb) Combine two or more lists using the given operation.
- # (Promise<List>) merge() Combine two or more lists through a union operation.
- # (Promise<List>) intersect() Combine two or more lists through an intersection operation.
- # (Promise<List>) diff() Combine two more lists through a symmetric difference opertation.
- # (Promise<List>) complement(options = {}, cb = function() {}) Bound Create a new list from the complement of two groups of lists.
- # (Promise<Array<Object>>) fetchWidgets(cb) Bound Fetch the list widgets that are available from this service.
- # (void) fetchWidgetMap(cb) Bound
- # (Promise<Model>) fetchModel(cb) Bound Fetch the description of the data model for this service.
- # (Promise<Object<String, Array<String>>>) fetchSummaryFields(cb) Bound Fetch the configured summary-fields.
- # (Promise<Number>) fetchVersion(cb) Bound Fetch the number that describes the web-service capabilities.
- # (void) fetchClassKeys(cb) Bound
- # (void) fetchRelease(cb) Bound
- # (Promise<Query>) query(options, cb) Bound Promise to make a new Query.
- # (Promise<Query>) savedQuery(name, cb) Bound Load a saved query by name.
- # (Promise<Query>) templateQuery(name, cb) Bound Load a template query by name.
- # (Promise<Object>) manageUserPreferences(method, data, cb) Private Perform operations on a user's preferences.
- # (Promise<IDResolutionJob>) resolveIds(opts, cb) Bound Submit an ID resolution job.
- # (IDResolutionJob) resolutionJob(id) Retrieve an existing ID Resolution job
- # (Promise<List>) createList(opts = {}, ids = '', cb = function() {}) Bound Create a new list through the identifier upload service.
- # (Service) connectAs(token) Bound Return a new service with the same root url as this one, but connected as a different user.
- # (Promise<Service>) register(name, password, cb) Create a new user at the current service.
- # (Promise<String>) getDeregistrationToken(validity = FIVE_MIN, cb) Promise to get a deregistration token.
- # (Promise<String>) deregister(token, cb) Return a promise to delete a user account, and retrieve all of its data.
- # (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.
- # (Promise<Service>) logout(cb) Promise to return a service with the same root as this one, but not associated with any user account.
Constructor Details
#
(void)
constructor({root, token, errorHandler, DEBUG, help, noCache, headers})
Construct a new connection to a service.
Instance Method Details
#
(void)
doReq()
#
(Promise<Object>)
post(path, data)
Convenience method for making basic POST requests.
#
(Promise<Object>)
get(path, data)
Convenience method for making basic GET requests.
#
(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.
#
(void)
authorise(req)
TODO - when 14 is prevalent the fetchVersion can be removed.
#
(void)
attachCustomHeaders(req)
Attach custom headers to the request that were supplied to the Service constructor via the options object. Caution: This will override headers if they already exist on the req object.
#
(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.
#
(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.
#
(Promise<PathInfo>)
makePath(path, subclasses = {}, cb = (function() {}))
Make a PathInfo object from a string
Sugar for service.fetchModel().then (m) -> m.makePath path, subclasses
#
(Promise<Number>)
count(q, cb = (function() {}))
Bound
Find out how many rows a given query would return when run.
#
(Promise<Object>)
findById(type, id, fields = ['**'], cb = (function() {}))
Bound
Retrieve a representation of a specific object.
#
(Promise<Array<Object>>)
lookup(type, term, context, cb)
Find all the objects in the database that match the search term.
#
(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.
#
(Promise<User>)
whoami(cb)
Bound
Retrieve information about the currently authenticated 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.
#
(Promise<Array<?>>)
doPagedRequest(q, path, page = {}, format, cb = (function() {}))
Private
Perform a request for results that accepts a parameter specifying the page to fetch. Not intended for public consumption.
#
(Promise<Array<?>>)
table(q, page, cb)
Bound
Get a page of results in jsontable format.
#
(Promise<Array<Object>>)
records(q, page, cb)
Bound
Get a page of results in jsonobject format.
#
(Promise<Array<Array<Object>>)
rows(q, page, cb)
Bound
Get a page of results in json format.
#
(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 <a href='../class/Service.html#rows-dynamic'>Service#rows</a> method.
#
(Promise<Array<Array<Object>>)
tableRows(q, page, cb)
Bound
Get a page of results suitable for building the cells in a table.
#
(Promise<Object>)
fetchTemplates(cb)
Bound
Get the templates this user currently has access to.
#
(Promise<Array<List>>)
fetchLists(cb)
Bound
Get the lists this user currently has access to.
#
(Promise<Array<List>>)
findLists(name = '', cb = (function() {}))
Bound
Get the lists this user currently has access to which match the given name.
#
(Promise<List>)
fetchList(name, cb)
Bound
Get a list by name.
#
(Promise<Array<List>>)
fetchListsContaining(opts, cb)
Bound
Get the lists that contain the given object.
#
(Promise<List>)
combineLists(operation, options, cb)
Combine two or more lists using the given operation.
#
(Promise<List>)
merge()
Combine two or more lists through a union operation.
also available as {Service#union}.
#
(Promise<List>)
intersect()
Combine two or more lists through an intersection operation.
#
(Promise<List>)
diff()
Combine two more lists through a symmetric difference opertation.
#
(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.
#
(Promise<Array<Object>>)
fetchWidgets(cb)
Bound
Fetch the list widgets that are available from this service.
#
(void)
fetchWidgetMap(cb)
Bound
#
(Promise<Model>)
fetchModel(cb)
Bound
Fetch the description of the data model for 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.
#
(Promise<Number>)
fetchVersion(cb)
Bound
Fetch the number that describes the web-service capabilities.
#
(void)
fetchClassKeys(cb)
Bound
#
(void)
fetchRelease(cb)
Bound
#
(Promise<Query>)
query(options, cb)
Bound
Promise to make a new Query.
#
(Promise<Query>)
savedQuery(name, cb)
Bound
Load a saved query by name.
#
(Promise<Query>)
templateQuery(name, cb)
Bound
Load a template query by name.
#
(Promise<Object>)
manageUserPreferences(method, data, cb)
Private
Perform operations on a user's preferences.
#
(Promise<IDResolutionJob>)
resolveIds(opts, cb)
Bound
Submit an ID resolution job.
#
(IDResolutionJob)
resolutionJob(id)
Retrieve an existing ID Resolution job
#
(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].
#
(Service)
connectAs(token)
Bound
Return a new service with the same root url as this one, but connected as a different user.
#
(Promise<Service>)
register(name, password, cb)
Create a new user at the current service.
#
(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.
#
(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'.
#
(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.
#
(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.