Interface Entity

For more information go here

model.Invoice.events.validate = function(event) {
          //get the array of attributes that were changed
  var attributeMods = this.getModifiedAttributes();
     //cycle through them
  attributeMods.forEach(function(attribName){
      switch (attribName){
         case 'ID': //if the ID was changed
         case 'InvoiceDate': //or the invoiceDate was changed
                  //assign an error number and message
              result = {error: 1000, errorMessage: 'Invalid Change !'};
              break;
      }
  });
  return result; //return result regardless
}

 //Then each time you perform a save action the entity will go through this validation process
 var a = ds.Invoice.first();
 a.ID = 12;
 a.save();
 // Running this will thow the error message 'Invalid Change !

Note

The entity's STAMP value is needed when executing POST request throught XRH to update an entity

Example

emp = ds.Employee.first();
   //... process the data in the entity
if (emp.isModified())     // if at least one of the attributes has been changed
emp.save();
// otherwise, no need to save the entity

warning

The lock()/unlock() method only works with WakandaDB and 4D Mobile Connector. It does not work when working with the MYSQL & OBDC Connectors

For more details about locking entities check this pages :

• lock() API Description
• In-Depth description of locking mecanism

Example with a for loop

 var myColl = ds.People.query("nationality = :1", "FR");
for (var onePerson = myColl.first(); onePerson != null; onePerson=onePerson.next())
// onePerson will return null after the last entity of the collection
{
onePerson.name = onePerson.name.toUpperCase();
onePerson.save();
}

Same Example with while

`javascript var myColl = ds.People.query("nationality = :1", "FR"); var onePerson = myColl.first(); while (onePerson != null) { onePerson.name = onePerson.name.toUpperCase(); onePerson.save(); onePerson=onePerson.next(); }

warning

If values are modified and not saved, they are lost.

Note : This method is useful :

• when you attempt to save an entity but receive an error because this entity was modified in the meantime by another user
• when adding new related entities (see below):

  ///For instance, if you have classes with a company/employee relationship...
  ///If you get a collection of the employees related to a company like this:
  locationsColl_Before = company.locations; //3 locations
  //Then you create a new location related to the company.  You might expect calling this again:
  locationsColl_After = company.locations; //3 locations
  //It will not, it will still return the original 3.  In order to get all 4 locations related to the company you need to refresh:
  company.refresh();  locationsColl_AfterRefresh = company.locations; //4 locations

**Note** : How to use this method (advanced) :

*** ``` Once unloaded by this method, the entity is not unusable. Wakanda keeps a reference to the entity and automatically reloads it as soon as it becomes used again. This utility method lets you optimize memory consumption when the server needs to load and work with numerous large objects, such as pictures or BLOBs.

In principle, the garbage collection mechanism of JavaScript will purge unused objects from memory. However, this mechanism operates * * autonomously and can prove to be insufficient in some cases. For example, when the server has loaded dozens of large pictures on the JavaScript side, only references are handled, which may not require the intervention of the garbage collector.

However, on the server side, the memory is in high demand. In a case like this, it is useful to be able to "force" entities to be unloaded using the release( ) method.

Note that after calling release( ), if you want to make sure that the JavaScript reference to an entity has been deleted without having to wait for garbage collection (and thus for a subsequent access to the entity to return an error), you must force its value to null.

#### Example :
```javascript
myEntity.release();   //unload the entity from the server
myEntity = null;     // delete its reference

Note:

When this method is executed, it triggers a call to the remove event on the server if it has been set for the entity's datastore class or one of the datastore class attributes.

For more information and examples about the remove() method, check its description here (collection section)

How to update an existing entity :

var a = ds.Employee.first();
a.firstname = "MyNewFirstName" ;
a.lastname =  "MyNewLastName" ;
a.save();

How to create then save an entity:

new ds.Employee(
{
    firstname : "MyNewFirstName" ,
    lastname  : "MyNewLastName"
}).save();

***

Events

When executing a save() action, on the server side the events (if defined) are performed in the following order :

1. validate on each attribute
2. validate on the datastore class
3. save on the datastore class
4. save on each attribute

Example

//You can intercept and manage the error returned by the engine when the entity's internal stamp being saved is different from the one that is saved in the data
//To do this, you can place the save statement in a try/catch type structure. For example:
// select an entity and change its name to uppercase
function toUpperEmployee(lastName, firstName)
{
var emp = ds.Employee.find("lastName = :1 and firstName = :2", lastName, firstName);
emp.lastName.toUppercase();
try
{
   emp.save();
}
catch(e)
{  ... // put the error-processing code here
}

warning

The lock()/unlock() method only works with WakandaDB and 4D Mobile Connector. It does not work when working with the MYSQL & OBDC Connectors

For more details about locking entities check this pages :

• unlock() API Description
• In-Depth description of locking mecanism

warning

Keep in mind that the entity is not saved until you actually call the save( ) method.

Validation Example (click to Expand)

```javascript // first let's create a dataclass validate event model.Elem.events.validate = function(event) //onValidate until Wakanda v8 { if (this.name == "Unknown") { return { error: 100, // an object with 'error' will make validation fail errorMessage: "The name cannot be 'Unknown'" }; } } ``` Then you could create a datastore class method ```javascript checkValidity:function() { try { return this.validate(); // returns true if successful } catch (e) { throw { // if fail // send an exception with the customized message // from the error stack message: e.messages[e.messages.length - 1]

}; } } //Finally you would simply call your Validation process by calling // - the validate() method (server side) or , // - the CheckValidity class method (server side or client side) `