Class: engine

pxdb.engine(Base)

The engine class is used to connect to a PXDB installation, authenticate, handle GraphQL queries, and generate Backbone model and collection classes to encapsulate those queries and their results. The engine is the basic mechanism for all interaction with PXDB.

Constructor

new engine(Base)

Creates a new PXDB connection engine.

Parameters:
Name Type Description
Base string

URL of the PXDB installation.

Source:

Members

callbacks

These are callback bindings for the setup process of engine.init(), and for the refreshing of access tokens. The value of each key must be an object, with two properties: "success" and "error". These properties must be functions which take one parameter: "data" for success, "error" for error.

Each is called after a specific stage of the init process:

  • setup: Retrieving the base config info from PXDB.
  • login: Logging in.
  • tenantbase: Retrieving the tenant base URL.
  • tenantroutes: Retrieving the routes defined for the tenant.
  • tenantschema: Retrieving the tenant schema and generating the Backbone classes.
  • rpb_schema: Retrieving the roles_pbac schema and generating its Backbone classes.

Additionally, token_refresh is called after calling the token_refresh() method to refresh the access token.

Default error handlers are provided, which emit the error JSON to console.log.

Source:

classes

Backbone classes generated by init() during the tenant_schema phase are stored on this member. See pxdb.create_backbone_classes() for information on the structure of this object.

Each model class will be a subclass of PXDB_MODEL, and each collection class a subclass of PXDB_COLLECTION.

Source:

errorstrings

These are error message templates defined for validation checking of the GraphQL queries and mutations. They are called when validations fail.

Source:

roleid

The ID of the logged in role using this engine. Set by init() after the tenantbase phase.

Source:

rpb_classes

Backbone classes generated by init() during the rpb_schema phase are stored on this member. See pxdb.create_backbone_classes() for information on the structure of this object.

Each model class will be a subclass of PXDB_MODEL, and each collection class a subclass of PXDB_COLLECTION.

Source:

type_validations

These are validation hooks for built-in datatypes in GraphQL, used by the Backbone Model classes' validate() method. The validations are simple type checks.

This object can be extended with validation functions for new scalar data types that a GraphQL schema defines, for instance, DateTime or Geometry. New validation functions should be set on a property name that matches the type name, without the ! for "required"; the functions must take a single argument and return a boolean, true if the argument is properly formatted for the type, false otherwise.

These functions are not meant for validating composite GraphQL types: those types correspond to models and collections, and the model validation method checks their validity.

Predefined validations:

  • ID: Always true. IDs are never set by mutations.
  • Int: v => _.isInteger(v)
  • Float: v => _.isNumber(v)
  • Boolean: v => _.isBoolean(v),
  • String: v => _.isString(v)
Source:

urls

The URLs configured for this engine are stored here. Before calling init(), the only property of this object will be 'base', the base URL passed in to the constructor. Once initialized, this object will have the following properties:

  • base: Base installation URL.
  • auth: Authentication URL.
  • tenant: Tenant urls:
    • base: Base of the tenant's URL schema.
    • query: GraphQL target for all database queries.
  • roles_pbac: GraphQL target for working with roles, role classes, and policy rules.
  • ows: URL for Mapserver OWS queries. Only enabled if this tenant has geospatial capabilities.
Source:

Methods

aggregate_query(fname, tabname, columns, Optional) → {array}

Runs an aggregate query using the PxDB Aggregates function namespace; PxDB will run a subquery against a table and then pass the first column of that subquery to an aggregate function. Any additional columns are used to group the aggregate results, as a SQL "group by" clause. The JSON results will be returned as an array of objects.

NB: If the columns parameter contains subselections, the return query will name the subselected columns based on the selection path. For instance, a selection like this: ['foo', {bar: ['baz']}] would yield a column named 'bar_baz' in the returned rows.

Parameters:
Name Type Description
fname string

Name of the aggregate function. Required.

tabname string

Name of the table to query against. Required. Must be a table type in the GraphQL schema.

columns array

Column selection list. Format is the same as for calling the selection() method on a model or collection, including subselections. Required, and at least one column is required. The first named column will be the argument to the aggregate function, and must be a column in the target table, not a subselection.

Optional object

Additional, optional arguments.

Properties
Name Type Description
filter string

A PxDB filter expression applied to the subquery. This will restrict what data the aggregate query sees.

having string

PxDB filter expression applied to the aggregate query. This acts as a "having" clause, restricting output of the aggregate query.

ordering array

Ordering spec for the aggregate query output.

limit integer

Limits output to this number of rows.

offset integer

Offset the first row returned by this number.

Source:
Returns:

Array of row objects.

Type
array

graphql_endpoint()

Returns a GraphQL endpoint for use in making GraphQL queries. If the user of this library wishes to make GraphQL queries directly, instead of using the Backbone classes, this may be useful. Otherwise, no need to call it directly.

Source:

init(login, password, tenantid)

Log in and set up URLs, schema, and Backbone classes. Several AJAX requests are involved with this process:

  • setup: GET request is sent to the base URL provided to the constructor, to ensure it is a proper PXDB installation and get the auth URL path. Error at this point means the URL is wrong.

  • login: If login and password are provided, POST to the auth URL to log in. The request returns access and refresh JWT tokens. Error at this point means the credentials are incorrect.

OR

  • token_refresh: If only a refresh token is provided in the login parameter, GET on the auth URL to refresh the access token. The request returns a fresh access token. Error at this point means the token is invalid or expired.

  • tenantbase: GET on the base URL again, with the access token set, returns the role's tenant URL path. Error is extremely unlikely and indicative of a server-side problem.

  • tenantroutes: GET on the tenant URL returns the tenant's available routes. Again, error is extremely unlikely and indicative of a server-side issue.

  • tenantschema: GET on the tenant's query route to retrieve the GraphQL schema. Again, error is unlikely.

The callbacks object contains information on handling errors, as well as adding success callbacks.

Parameters:
Name Type Description
login string

Role login.

password string

Role password.

tenantid int

Tenant ID for the role.

Deprecated:
  • This method is deprecated in favor of login. Do not use this method for any new code.
Source:

login(login, password, tenantid)

Log in and set up URLs, schema, and Backbone classes. Several phases are involved with this process:

  • login: If login and password are provided, POST to the auth URL to log in. The request returns all data required to set up the authentication tokens, URLs, schemas, and Backbone classes. Error at this point means the credentials are incorrect.

OR

  • token_refresh: If only a refresh token is provided in the login parameter, GET on the auth URL to refresh the access token. The request returns a fresh access token. Error at this point means the token is invalid or expired.

  • tenantroutes: The routes are populated from the returned data.

  • tenantschema: The GraphQL schema is parsed and Backbone classes are generated.

  • rpb_schema: The GraphQL roles_pbac schema is parsed and its Backbone classes are generated.

The callbacks object contains information on handling errors, as well as adding success callbacks.

Parameters:
Name Type Description
login string

Role login.

password string

Role password.

tenantid int

Tenant ID for the role.

Source:

token_refresh()

Refreshes the JWT access token using the refresh token. Access tokens are valid for one hour, so this will be needed in error handlers to handle 401 errors on query. If the response to this method is 401, the refresh token has expired; refresh tokens have a lifetime of 24 hours, so this is unlikely.

Source: