diff --git a/docs/connector.md b/docs/connector.md index f1d51e07..b83387d0 100644 --- a/docs/connector.md +++ b/docs/connector.md @@ -1,5 +1,134 @@ -# loopback-connector +# loopback-data-connector + +Loopback connectors provide access to backend systems including databases, REST APIs +and other services. Connectors are not used directly by application code. We create +a DataSource to interact with the connector. + +For example, + + var DataSource = require('loopback-data').DataSource; + var oracleConnector = require('loopback-connector-oracle'); + + var ds = new DataSource(oracleConnector, { + host : '166.78.158.45', + database : 'XE', + username : 'strongloop', + password : 'str0ng100pjs', + debug : true + }); + +The connector argument passed the DataSource constructor can be one of the following: + +* The connector module from `require(connectorName)` +* The full name of the connector module, such as 'loopback-connector-oracle' +* The short name of the connector module, such as 'oracle', which will be converted to 'loopback-connector-' +* A local module under ./connectors/ folder + +## Generic connector implmentations + +A connector module can implement the following methods to interact with the datasource. + + exports.initialize = function (dataSource, postInit) { + + var settings = dataSource.settings || {}; // The settings is passed in from the dataSource + + var connector = new MyConnector(settings); // Construct the connector instance + dataSource.connector = connector; // Attach connector to dataSource + connector.dataSource = dataSource; // Hold a reference to dataSource + + /** + * Connector instance can have an optional property named as DataAccessObject that provides + * static and prototype methods to be mixed into the model constructor. The property can be defined + * on the prototype. + */ + connector.DataAccessObject = function {}; + + /** + * Connector instance can have an optional function to be called to handle data model definitions. + * The function can be defined on the prototype too. + * @param model The name of the model + * @param properties An object for property definitions keyed by propery names + * @param settings An object for the model settings + */ + connector.define = function(model, properties, settings) { + ... + }; + + connector.connect(..., postInit); // Run some async code for initialization + // process.nextTick(postInit); + } + +Another way is to directly export the connection function which takes a settings object. + + module.exports = function(settings) { + ... + } + +## CRUD connector implmentations + +To support CRUD operations for a model class that is attached to the dataSource/connector, the connector needs to provide +the following functions: + + /** + * Create a new model instance + */ + CRUDConnector.prototype.create = function (model, data, callback) { + }; + + /** + * Save a model instance + */ + CRUDConnector.prototype.save = function (model, data, callback) { + }; + + /** + * Check if a model instance exists by id + */ + CRUDConnector.prototype.exists = function (model, id, callback) { + }; + + /** + * Find a model instance by id + */ + CRUDConnector.prototype.find = function find(model, id, callback) { + }; + + /** + * Update a model instance or create a new model instance if it doesn't exist + */ + CRUDConnector.prototype.updateOrCreate = function updateOrCreate(model, data, callback) { + }; + + /** + * Delete a model instance by id + */ + CRUDConnector.prototype.destroy = function destroy(model, id, callback) { + }; + + /** + * Query model instances by the filter + */ + CRUDConnector.prototype.all = function all(model, filter, callback) { + }; + + /** + * Delete all model instances + */ + CRUDConnector.prototype.destroyAll = function destroyAll(model, callback) { + }; + + /** + * Count the model instances by the where criteria + */ + CRUDConnector.prototype.count = function count(model, callback, where) { + }; + + /** + * Update the attributes for a model instance by id + */ + CRUDConnector.prototype.updateAttributes = function updateAttrs(model, id, data, callback) { + }; + + -Loopback data sources are backed by connectors that communicates with backend systems including databases, REST APIs -and other services. diff --git a/docs/data-source.md b/docs/data-source.md index 9400c478..aceb6773 100644 --- a/docs/data-source.md +++ b/docs/data-source.md @@ -1,42 +1,43 @@ -loopback-connector-schema(3) - Everything about schema, data types and model definition. -==================== +# loopback-data-datasource + +Everything about datasource, data types and model definition. ## DESCRIPTION -Schema is a factory for classes. Schema connected with specific database using -adapter. +DataSource is a factory for model classes. DataSource connected with specific database or other +backend system using connector. -All classes within single schema shares same adapter type and one database -connection. But it's possible to use more than one schema to connect with +All model classes within single datasource shares same connector type and one database +connection. But it's possible to use more than one datasource to connect with different databases. ## EVENTS -Instances of Schema are event emitters, events supported by default: +Instances of DataSource are event emitters, events supported by default: * `.on('connected', function() {})`: Fired when db connection established. Params: none. * `.on('log', function(msg, duration) {})`: - Fired when adapter logged line. Params: String message, Number duration + Fired when connector logged line. Params: String message, Number duration ## USAGE -### Creating schema +### Creating dataSource -`Schema` constructor available on `loopback-data` module: +`DataSource` constructor available on `loopback-data` module: - var Schema = require('loopback-data').Schema; + var DataSource = require('loopback-data').DataSource; -Schema constructor accepts two arguments. First argument is adapter. It could be -adapter name or adapter package: +DataSource constructor accepts two arguments. First argument is connector. It could be +connector name or connector package: - var schemaByAdapterName = new Schema('memory'); - var schemaByAdapterPackage = new Schema(require('redis')); + var dataSourceByConnectorName = new DataSource('memory'); + var dataSourceByConnectorModule = new DataSource(require('redis')); ### Settings Second argument is optional settings. Settings object format and defaults -depends on specific adapter, but common fields are: +depends on specific connector, but common fields are: * `host`: Database host @@ -51,21 +52,21 @@ Database name * `debug`: Turn on verbose mode to debug db queries and lifecycle -For adapter-specific settings refer to adapter's readme file. +For connector-specific settings refer to connector's readme file. ### Connecting to database -Schema connecting to database automatically. Once connection established schema +DataSource connecting to database automatically. Once connection established dataSource object emit 'connected' event, and set `connected` flag to true, but it is not necessary to wait for 'connected' event because all queries cached and executed -when schema emit 'connected' event. +when dataSource emit 'connected' event. -To disconnect from database server call `schema.disconnect` method. This call -forwarded to adapter if adapter have ability to connect/disconnect. +To disconnect from database server call `dataSource.disconnect` method. This call +forwarded to connector if connector have ability to connect/disconnect. ### Model definition -To define model schema have single method `schema.define`. It accepts three +To define model dataSource have single method `dataSource.define`. It accepts three argumets: * **model name**: @@ -81,14 +82,14 @@ argumets: Examples of model definition: - var User = schema.define('User', { + var User = dataSource.define('User', { email: String, password: String, birthDate: Date, activated: Boolean }); - var User = schema.define('User', { + var User = dataSource.define('User', { email: { type: String, limit: 150, index: true }, password: { type: String, limit: 50 }, birthDate: Date, @@ -103,7 +104,7 @@ Examples of model definition: ### DB structure syncronization -Schema instance have two methods for updating db structure: automigrate and +DataSource instance have two methods for updating db structure: automigrate and autoupdate. The `automigrate` method drop table (if exists) and create it again, @@ -112,15 +113,15 @@ called when migration/update done. To check if any db changes required use `isActual` method. It accepts single `callback` argument, which receive boolean value depending on db state: false if -db structure outdated, true when schema and db is in sync: +db structure outdated, true when dataSource and db is in sync: - schema.isActual(function(err, actual) { + dataSource.isActual(function(err, actual) { if (!actual) { - schema.autoupdate(); + dataSource.autoupdate(); } }); ## SEE ALSO -loopback-connector-model(3) -loopback-connector-adapter(3) +loopback-data-model +loopback-data-connector diff --git a/docs/hooks.md b/docs/hooks.md index 5c39b9df..f072329a 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -1,5 +1,6 @@ -loopback-connector-hooks(3) - Hooks and object lifecycle. -=================== +# loopback-data-hooks + +Hooks and object lifecycle. ## DESCRIPTION @@ -130,5 +131,5 @@ loopback-connector-validations(3) man section. ## SEE ALSO -loopback-connector-model(3) -loopback-connector-validations(3) +loopback-data-model +loopback-data-validations diff --git a/docs/index.txt b/docs/index.txt deleted file mode 100644 index d3cf385a..00000000 --- a/docs/index.txt +++ /dev/null @@ -1,6 +0,0 @@ -# adapters github -loopback-connector-mongodb https://github.com/strongloop/loopback-connector-mongodb -loopback-connector-oracle https://github.com/strongloop/loopback-connector-oracle -loopback-connector-mysql https://github.com/strongloop/loopback-connector-mysql - -# external resources diff --git a/docs/loopback-data.md b/docs/loopback-data.md index 82e8a0bf..a6e6f644 100644 --- a/docs/loopback-data.md +++ b/docs/loopback-data.md @@ -4,4 +4,4 @@ Loopback-data provides ORM and data connectivity for Node.js. It was initially f ## SEE ALSO -loopback-connector +loopback-data-connector diff --git a/docs/model.md b/docs/model.md index bbaa4bc7..c59b8964 100644 --- a/docs/model.md +++ b/docs/model.md @@ -1,5 +1,6 @@ -loopback-connector-model(3) - Model methods, features and internals -=================== +# loopback-data-model + +Model methods, features and internals ## DESCRIPTION @@ -185,7 +186,7 @@ TODO: document ## SEE ALSO -loopback-connector-schema(3) -loopback-connector-validations(3) -loopback-connector-hooks(3) -loopback-connector-adapter(3) +loopback-data-datasource +loopback-data-validations +loopback-data-hooks +loopback-data-connector diff --git a/docs/validations.md b/docs/validations.md index 53dd4bc1..3621036f 100644 --- a/docs/validations.md +++ b/docs/validations.md @@ -1,2 +1,18 @@ -loopback-connector-validations(3) - Built-in validators, creating custom validations, syncronous and asyncronous object validation. -======================== +# loopback-data-validations + +Built-in validators, creating custom validations, syncronous and asyncronous object validation. + + // Setup validations + User.validatesPresenceOf('name', 'email') + User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}}); + User.validatesInclusionOf('gender', {in: ['male', 'female']}); + User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']}); + User.validatesNumericalityOf('age', {int: true}); + User.validatesUniquenessOf('email', {message: 'email is not unique'}); + + user.isValid(function (valid) { + if (!valid) { + user.errors // hash of errors {attr: [errmessage, errmessage, ...], attr: ...} + } + }) + diff --git a/media/mysql.ico b/media/mysql.ico deleted file mode 100644 index 918e89d3..00000000 Binary files a/media/mysql.ico and /dev/null differ diff --git a/media/sqlite.png b/media/sqlite.png deleted file mode 100644 index e47ef019..00000000 Binary files a/media/sqlite.png and /dev/null differ