@axway/api-builder-orm

Object relational mapping (ORM) framework for API Builder.

Main Components

There are 4 main components to the ORM framework:

- model - Defines the logical structure of a data entity.
- Instance - An instance of a model object.
- Collection - Zero or more instances.
- Connector - Responsible for generating and managing Models.

$3

To define a model, you must give a set of fields and a connector.

``javascript
var User = orm.Model.extend('user',{
fields: {
name: {
type: String,
default: 'Jeff',
}
},
connector: Connector
});
`

The first argument is the name of the model. The second argument is the definition of the model.

#### Definition
The definition of the model is an object with the following properties.

| Name | Type | Description |
|--------------------------|------------------|--------------------------------------------------|
| actions | string[] | An array of method actions that are enabled for the model. If empty, all are enabled. |
| autogen | boolean | A boolean to indicate the model was auto-generated. |
| cache | boolean | Enables a LRU cache. |
| connector | string \| object | Identifies the connector to which this model belongs, required. |
| countDescription | string | Changes the description for the method count. |
| createDescription | string | Changes the description for the method create. |
| deleteAllDescription | string | Changes the description for the method deleteAll. |
| deleteDescription | string | Changes the description for the method delete. |
| disabledActions | string[] | An array of actions that are disabled for the model. |
| distinctDescription | string | Changes the description for the method distinct. |
| fields | object | A collection of property fields belonging to the model. |
| findAllDescription | string | Changes the description for the method findAll. |
| findAndModifyDescription | string | Changes the description for the method findAndModify. |
| findByIDDescription | string | Changes the description for the method findByID. |
| findManyByIDDescription | string | Changes the description for the method findManyByID. |
| metadata | object | Additional metadata about the model. |
| plural | string | The plural name of the model. |
| queryDescription | string | Changes the description for the method query. |
| singular | string | The singular name of the model. |
| updateDescription | string | Changes the description for the method update. |
| upsertDescription | string | Changes the description for the method upsert. |

#### Fields
The fields are a collection of properties where each key uniquely identifies the field, and each field has a set of properties that define it:

| Name | Type | Description |
|-------------|---------|----------------------------------------------------------|
| custom | boolean | Indicates the field's value is custom and should be omitted when converting to payload (e.g. JSON). |
| default | any | The default value. |
| description | string | The description of the field. |
| length | integer | For Strings and Arrays, the precise length of the field. |
| limit | integer | In composite models where the field is joined with another and the type is "array", then this property limits the amount of records returned. |
| maxlength | integer | For Strings and Arrays, the maximum length of the field. |
| minlength | integer | For Strings and Arrays, the minimum length of the field. |
| model | string | The name of the model from which this field originates (in composite models). |
| name | string | The name of the field. |
| optional | boolean | The field is optional (deprecated). |
| readonly | boolean | The field is read-only. |
| required | boolean | If true, the field is required. |
| type | any | The column type, supporting values: string, date, number, array, object, and boolean; required. |

#### Metadata
The metadata is used to encode additional data about the Model that can be used for composite models or primary keys.

| Name | Type | Description |
|-------------------|---------|----------------------------------------------------------|
| primarykey | string | The field name that is identified as the primary key. The field cannot be a property of fields. |
| primaryKeyDetails | object | An object that describes additional details about the primary key. |
| table | string | In some connectors, this refers to the table name for the Model. |
| schema | string | In some connectors, this refers to the table schema name or owner of the table for the Model. |

##### Metadata.primaryKeyDetails
| Name | Type | Description |
|-------------------|---------|----------------------------------------------------------|
| autogenerated | boolean | Indicates the primary key is auto-generated. |
| dataType | string | In some connectors, this describes the persisted datatype of the primary key. |
| type | string | In some connectors, this describes the field type for the primary key, supporting values: string, date, number. |

#### Methods
The model has several instance methods:

| Name | Description |
|---------------|------------------------------------------------------------------|
| count | Find count of a query. |
| create | Create a new Model instance. |
| delete | Deletes a Model instance. |
| deleteAll | Removes all Model instances. |
| distinct | Find unique values for a Model field name. |
| extend | Create a new Model class from the current Model. |
| find | Find one or more Models. |
| findAll | Find all Models. |
| findAndModify | Find a Model from a query and modify values. |
| findByID | Find one Model by a primary key. |
| findManyByID | Find many Models by a primary key. |
| query | Find a Model from a query. |
| update | Updates a Model instance. |
| upsert | Updates or inserts a Model instance. |

#### Custom functions
A model can have custom functions by defining them in the definition as a property. They will automatically be available on the model instance.

`javascript
var User = orm.Model.extend('user',{
fields: {
name: {
type: String,
required: true,
default: 'jeff'
}
},
connector: Connector,

// implement a function that will be on the Model and
// available to all instances
getProperName: function() {
// this points to the instance when this is invoked
return this.name.charAt(0).toUpperCase() + this.name.substring(1);
}
});

User.create(function(err,user){
console.log(user.getProperName());
});
`

$3

One you've defined a model, you can then use it to create an Instance of the Model.

`javascript
User.create({name:'Nolan'}, function(err,user){
// you now have a user instance
});
`

Instances has several methods for dealing with the model.

| Name | Description |
|---------------|------------------------------------------------------------------|
| get | get the value of a field property |
| set | set a value or a set of values (Object) |
| isUnsaved | returns true if the instance has pending changes |
| isDeleted | returns true if the instance has been deleted and cannot be used |
| update | save any pending changes |
| remove | remove this instance (delete it) |
| getPrimaryKey | return the primary key value set by the Connector |

In addition to get and set, you can also use property accessors to get field values.

`javascript
console.log('name is',user.name);
user.name = 'Rick';
`

$3

If the Connector returns more than one Model instance, it will return it as a Collection, which is a container of Model instances.

A collection is an array and has additional helper functions for manipulating the collection.

You can get the length of the collection with the length property.

$3

To create a connector, you can either inherit from the Connector class using utils.inherit or extend:

`javascript
var MyConnector = orm.Connector.extend({
constructor: function(){
},
findByID: function(Model, id, callback) {
}
});
`

Once you have created a Connector class, you can create a new instance:

`javascript
var connector = new MyConnector({
url: 'http://foobar.com'
});
``

License

This code is proprietary, closed source software licensed to you by Axway. All Rights Reserved. You may not modify Axway’s code without express written permission of Axway. You are licensed to use and distribute your services developed with the use of this software and dependencies, including distributing reasonable and appropriate portions of the Axway code and dependencies. Except as set forth above, this code MUST not be copied or otherwise redistributed without express written permission of Axway. This module is licensed as part of the Axway Platform and governed under the terms of the Axway license agreement (General Conditions) located here: https://support.axway.com/en/auth/general-conditions; EXCEPT THAT IF YOU RECEIVED A FREE SUBSCRIPTION, LICENSE, OR SUPPORT SUBSCRIPTION FOR THIS CODE, NOTWITHSTANDING THE LANGUAGE OF THE GENERAL CONDITIONS, AXWAY HEREBY DISCLAIMS ALL SUPPORT AND MAINTENANCE OBLIGATIONS, AS WELL AS ALL EXPRESS AND IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO IMPLIED INFRINGEMENT WARRANTIES, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND YOU ACCEPT THE PRODUCT AS-IS AND WITH ALL FAULTS, SOLELY AT YOUR OWN RISK. Your right to use this software is strictly limited to the term (if any) of the license or subscription originally granted to you.