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) constructor() Constructor Construct a new connection to a service.
- - (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.
- - (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, cb) 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<?>>) 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<IDResolutionJob>) resolveIds(opts, cb) Bound Submit an 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()
Construct a new connection to a service.
Instance Method Details
- (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.
- (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, cb) (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<?>>) 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 Service#rows 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<IDResolutionJob>) resolveIds(opts, cb) (bound)
Submit an 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.