Version BETA : QxOrm 1.2.2 - Nouveau module QxValidator à tester

**QxOrm** · 28/11/2011, 20h39

Bonjour à tous,

Je viens de mettre en ligne une première version BETA de la future version de QxOrm (qui sera nommée QxOrm 1.2.2) : http://www.qxorm.com/version/QxOrm_1.2.2_BETA_17.zip

La principale nouveauté de cette version est l'apparition d'un nouveau module : QxValidator. Ce nouveau module permet de définir des règles de validation afin de vérifier une instance de classe avant qu'elle soit insérée ou mise à jour en BDD. Ça ressemble fortement à ce que propose NHibernate (et d'autres ORM) : http://nhforge.org/wikis/validator/n...mentation.aspx

Il n'y a pas de doc encore pour utiliser ce module, mais voici un exemple pour ceux qui veulent tester (exemple du dossier ./test/qxDllSample/dll1/ du package QxOrm) :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
#ifndef _QX_CLASS_PERSON_H_
#define _QX_CLASS_PERSON_H_
 
#ifdef _MSC_VER
#pragma once
#endif
 
namespace qx {
namespace test {
 
class QX_DLL1_EXPORT CPerson : public QObject
{
 
   Q_OBJECT
   QX_REGISTER_FRIEND_CLASS(qx::test::CPerson)
 
public:
 
   enum sex { male, female, unknown };
 
protected:
 
   long     m_lPersonId;
   QString  m_sFirstName;
   QString  m_sLastName;
   double   m_dDouble;
   sex      m_eSex;
 
public:
 
   CPerson() : QObject(), m_lPersonId(0), m_sFirstName("toto"), m_dDouble(4.5678), m_eSex(unknown) { ; }
   CPerson(long lId) : QObject(), m_lPersonId(lId), m_sFirstName("toto"), m_dDouble(4.5678), m_eSex(unknown) { ; }
   virtual ~CPerson() { ; }
 
   long getPersonId() const      { return m_lPersonId; }
   QString getFirstName() const  { return m_sFirstName; }
   QString getLastName() const   { return m_sLastName; }
   double getDouble() const      { return m_dDouble; }
   sex getSex() const            { return m_eSex; }
 
   void setPersonId(long l)               { m_lPersonId = l; }
   void setFirstName(const QString & s)   { m_sFirstName = s; }
   void setLastName(const QString & s)    { m_sLastName = s; }
   void setDouble(double d)               { m_dDouble = d; }
   void setSex(sex e)                     { m_eSex = e; }
 
private:
 
   void isValid(qx::QxInvalidValueX & invalidValues);
 
};
 
} // namespace test
} // namespace qx
 
QX_REGISTER_COMPLEX_CLASS_NAME_HPP_QX_DLL1(qx::test::CPerson, QObject, 0, qx_test_CPerson)
 
#endif // _QX_CLASS_PERSON_H_

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
#include "../include/precompiled.h"
 
#include "../include/CPerson.h"
 
#include <QxMemLeak.h>
 
void myGlobalValidator_1(const QVariant & value, const qx::IxValidator * validator, qx::QxInvalidValueX & invalidValues);
void myGlobalValidator_2(const QString & value, const qx::IxValidator * validator, qx::QxInvalidValueX & invalidValues);
 
QX_REGISTER_COMPLEX_CLASS_NAME_CPP_QX_DLL1(qx::test::CPerson, qx_test_CPerson)
 
namespace qx {
template <> void register_class(QxClass<qx::test::CPerson> & t)
{
   IxDataMember * pData = NULL;
   IxFunction * pFct = NULL;
   IxValidator * pValidator = NULL;
 
   t.setName("CPerson");
 
   pData = t.id(& qx::test::CPerson::m_lPersonId, "idPerson", 0);
 
   pData = t.data(& qx::test::CPerson::m_sFirstName, "firstName", 0);
   pData = t.data(& qx::test::CPerson::m_sLastName, "lastName", 0);
   pData = t.data(& qx::test::CPerson::m_dDouble, "double", 0);
   pData = t.data(& qx::test::CPerson::m_eSex, "sex", 0);
 
   pFct = t.fct_0<long>(& qx::test::CPerson::getPersonId, "fct_getPersonId");
   pFct = t.fct_0<QString>(& qx::test::CPerson::getFirstName, "fct_getFirstName");
   pFct = t.fct_1<void, long>(& qx::test::CPerson::setPersonId, "fct_setPersonId");
 
   QxValidatorX<qx::test::CPerson> * pAllValidator = t.getAllValidator();
   if (! pAllValidator) { qAssert(false); return; }
   pValidator = pAllValidator->add_NotEmpty("firstName", "a person must have a firstname");
   pValidator = pAllValidator->add_NotEmpty("lastName");
   pValidator = pAllValidator->add_MinDecimal("double", 0.5, "'double' field must be greater than or equal to '0.5'");
   pValidator = pAllValidator->add_MaxDecimal("double", 103.19);
   pValidator = pAllValidator->add_CustomValidator(& qx::test::CPerson::isValid);
   pValidator = pAllValidator->add_CustomValidator_QVariant(& myGlobalValidator_1, "firstName");
   pValidator = pAllValidator->add_CustomValidator_DataType<QString>(& myGlobalValidator_2, "lastName");
}}
 
namespace qx {
namespace test {
 
void CPerson::isValid(qx::QxInvalidValueX & invalidValues)
{
   // This method is called automatically by 'QxValidator' module (validator engine of QxOrm library) :
   // - when you try to insert or update using 'qx::dao::xxx' functions
   // - when you call 'qx::validate()' function
 
   // For registration, see 'pAllValidator->add_CustomValidator(& qx::test::CPerson::isValid);' into 'qx::register_class<T>()' function
 
   // Here, you can verify some values of your instance
   // If a value is not valid, you must add an invalid value into the collection 'invalidValues'
 
   if ((m_sFirstName == "admin") || (m_sLastName == "admin"))
   { invalidValues.insert("you cannot set 'admin' for the name of a person"); }
}
 
} // namespace test
} // namespace qx
 
// ********************************************************************************************************
// ********************************************************************************************************
 
// Example of global functions 'myGlobalValidator_1' and 'myGlobalValidator_2' used by 'QxValidator' module
// Those functions will be called automatically by validator engine of QxOrm library :
// - when you try to insert or update using 'qx::dao::xxx' functions
// - when you call 'qx::validate()' function
 
void myGlobalValidator_1(const QVariant & value, const qx::IxValidator * validator, qx::QxInvalidValueX & invalidValues)
{
   // Here you can test the value (converted to QVariant type)
   // If an invalid value is detected, just add a message into 'invalidValues' collection
 
   Q_UNUSED(value); Q_UNUSED(validator); Q_UNUSED(invalidValues);
}
 
void myGlobalValidator_2(const QString & value, const qx::IxValidator * validator, qx::QxInvalidValueX & invalidValues)
{
   // Here you can test the value (with its real type, in this example, the data-member is a 'QString' type)
   // If an invalid value is detected, just add a message into 'invalidValues' collection
 
   Q_UNUSED(value); Q_UNUSED(validator); Q_UNUSED(invalidValues);
}
 
// ********************************************************************************************************
// ********************************************************************************************************

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
boost::shared_ptr<qx::test::CPerson> personValidate;
personValidate.reset(new qx::test::CPerson());
personValidate->setLastName("admin");
personValidate->setDouble(305.86);
qx::QxInvalidValueX invalidValues = qx::validate(personValidate);
QString sInvalidValues = invalidValues.text();
qDebug("[QxOrm] test 'QxValidator' module :\n%s", qPrintable(sInvalidValues));

Sinon, la BETA contient également une évolution pour retourner le vrai ID (à la place de l'OID) avec une BDD PostgreSQL et la fonction qx::dao::insert() : on utilise le mot-clé RETURNING dans la requête SQL pour gérer ça car la classe QSqlQuery de Qt retourne l'OID (méthode lastInsertId()).

Merci d'avance à tous ceux qui pourront tester cette version BETA...

**QxOrm** · 07/12/2011, 19h57

Voici la documentation pour ceux qui veulent tester le nouveau module QxValidator :
_________________________________

Le module QxValidator de la bibliothèque QxOrm permet d'ajouter des contraintes sur les propriétés enregistrées dans le contexte QxOrm. Ces contraintes sont définies dans la méthode de mapping : void qx::register_class<T>(). Si pour une instance de classe donnée, au moins une contrainte n'est pas respectée, alors l'instance est considérée comme invalide : l'objet ne peut alors pas être sauvegardé en base de données (INSERT ou UPDATE).

Il est également possible d'utiliser le module QxValidator pour valider les données au niveau de la couche présentation de l'application : si les données saisies par un utilisateur ne sont pas valides, un message d'erreur peut être signalé, il n'est alors pas nécessaire d'essayer d'enregistrer l'instance courante en base de données. Les règles de validation n'ont pas besoin d'être dupliquées : elles peuvent être utilisées aussi bien par la couche présentation que par la couche d'accès aux données de l'application.

Voici la description de quelques classes du module QxValidator :

qx::IxValidator : chaque contrainte définie dans la fonction de mapping void qx::register_class<T>() est associée à une interface de type qx::IxValidator ;
qx::IxValidatorX : pour une classe donnée, la liste des contraintes est associée à une interface de type qx::IxValidatorX. Cette collection peut être parcourue à l'exécution du programme : ça peut être intéressant par exemple pour générer le schéma SQL et prendre en compte les contraintes au niveau de la base de données (voir la Q&R de la FAQ : Comment générer le schéma SQL (création et mise à jour des tables) en fonction des classes persistantes C++ définies dans le contexte QxOrm ?) ;
qx::QxInvalidValueX : au moment du processus de validation, lorsqu'une instance n'est pas valide, la liste des contraintes non respectées est représentée par une collection de type qx::QxInvalidValueX ;
qx::QxInvalidValue : chaque élément de cette collection est de type qx::QxInvalidValue et contient un message d'erreur (description expliquant pourquoi l'instance est invalide).

Le module QxValidator gère automatiquement la notion d'héritage de classe : si des contraintes sont définies au niveau de la classe de base, alors elles seront automatiquement vérifiées pour chaque validation d'une classe dérivée.

Voici un exemple d'utilisation du module QxValidator avec une classe 'person' :

* fichier 'person.h' :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#ifndef _CLASS_PERSON_H_
#define _CLASS_PERSON_H_
 
class person
{
 
public:
 
   enum sex { male, female, unknown };
 
   long        _id;
   QString     _firstName;
   QString     _lastName;
   QDateTime   _birthDate;
   sex         _sex;
 
   person() : _id(0), _sex(unknown) { ; }
   person(long id) : _id(id), _sex(unknown) { ; }
   virtual ~person() { ; }
 
private:
 
   void isValid(qx::QxInvalidValueX & invalidValues);
 
};
 
QX_REGISTER_HPP_MY_EXE(person, qx::trait::no_base_class_defined, 0)
 
#endif // _CLASS_PERSON_H_

* fichier 'person.cpp' :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
#include "../include/precompiled.h"
 
#include "../include/person.h"
#include "../include/global_validator.h"
 
#include <QxMemLeak.h>
 
QX_REGISTER_CPP_MY_EXE(person)
 
namespace qx {
template <> void register_class(QxClass<person> & t)
{
   t.id(& person::_id, "id");
 
   t.data(& person::_firstName, "firstName");
   t.data(& person::_lastName, "lastName");
   t.data(& person::_birthDate, "birthDate");
   t.data(& person::_sex, "sex");
 
   QxValidatorX<person> * pAllValidator = t.getAllValidator();
   pAllValidator->add_NotEmpty("firstName");
   pAllValidator->add_NotEmpty("lastName", "a person must have a lastname");
   pAllValidator->add_CustomValidator(& person::isValid);
   pAllValidator->add_CustomValidator_QVariant(& validateFirstName, "firstName");
   pAllValidator->add_CustomValidator_DataType<QDateTime>(& validateDateTime, "birthDate");
}}
 
void person::isValid(qx::QxInvalidValueX & invalidValues)
{
   // Cette méthode est appelée automatiquement par le module 'QxValidator' :
   // - avant d'insérer ou mettre à jour une instance de type 'person' par les fonctions du namespace 'qx::dao' ;
   // - en utilisant la fonction 'qx::validate()' avec pour paramètre une instance de type 'person'.
 
   // L'enregistrement de la méthode 'person::isValid()' est effectué dans la fonction de mapping :
   // pAllValidator->add_CustomValidator(& person::isValid);
 
   // Dans cette méthode, il est possible de vérifier n'importe quelle valeur de l'instance courante
   // Si une propriété est non valide, il suffit d'insérer un élément dans la collection 'invalidValues'
 
   // Remarque : cette méthode est déclarée 'private' pour forcer l'utilisateur à utiliser la fonction 'qx::validate()'
   // Mais ce n'est pas une obligation : cette méthode peut être déclarée 'public' ou 'protected'
 
   // Par exemple, si on souhaite vérifier la propriété '_sex' d'une personne :
   if ((_sex != male) && (_sex != female))
   { invalidValues.insert("le sexe de la personne doit être défini : masculin ou féminin"); }
}

* fichier 'global_validator.h' :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Les fonctions suivantes ('validateFirstName()' et 'validateDateTime()') sont globales (non liées à une classe)
// Elles peuvent ainsi être utilisées par plusieurs classes pour valider une propriété (par exemple : valider la saisie d'une adresse IP).
// Ces fonctions seront appelées automatiquement par le module 'QxValidator' :
// - avant d'insérer ou mettre à jour une instance de classe par les fonctions du namespace 'qx::dao' ;
// - en utilisant la fonction 'qx::validate()'.
 
void validateFirstName(const QVariant & value, const qx::IxValidator * validator, qx::QxInvalidValueX & invalidValues)
{
   // Ici, on peut tester la valeur d'une propriété (convertie en type QVariant)
   // Si la valeur est invalide, il suffit d'insérer un message à la collection 'invalidValues'
 
   // Par exemple, si la valeur ne doit jamais être égale à "admin" :
   if (value.toString() == "admin")
   { invalidValues.insert("la valeur ne peut pas être égale à 'admin'"); }
}
 
void validateDateTime(const QDateTime & value, const qx::IxValidator * validator, qx::QxInvalidValueX & invalidValues)
{
   // Ici, on peut tester la valeur d'une propriété (en conservant son vrai type, ici il s'agit de tester une date-heure de type 'QDateTime')
   // Si la valeur est invalide, il suffit d'insérer un message à la collection 'invalidValues'
 
   // Par exemple, si la date-heure doit forcément être renseignée :
   if (! value.isValid())
   { invalidValues.insert("la date-heure doit être renseignée et doit être valide"); }
}

* fichier 'main.cpp' :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
person personValidate;
personValidate._lastName = "admin";
qx::QxInvalidValueX invalidValues = qx::validate(personValidate);
QString sInvalidValues = invalidValues.text();
qDebug("[QxOrm] test 'QxValidator' module :\n%s", qPrintable(sInvalidValues));

A l'exécution de ce bout de code, l'instance 'personValidate' est non valide : la collection 'invalidValues' contient quatre éléments :
- "la valeur de la propriété 'firstName' ne peut pas être vide" ;
- "le sexe de la personne doit être défini : masculin ou féminin" ;
- "la valeur ne peut pas être égale à 'admin'" ;
- "la date-heure doit être renseignée et doit être valide".

Le module QxValidator fournit plusieurs validateurs pour effectuer des vérifications basiques :

add_NotNull() : vérifie que la valeur n'est pas nulle ;
add_NotEmpty() : vérifie que la chaîne de caractères n'est pas vide ;
add_MinValue() : vérifie que la valeur numérique n'est pas inférieure au paramètre ;
add_MaxValue() : vérifie que la valeur numérique n'est pas supérieure au paramètre ;
add_Range() : vérifie que la valeur numérique est comprise entre les deux paramètres ;
add_MinDecimal() : vérifie que la valeur décimale n'est pas inférieure au paramètre ;
add_MaxDecimal() : vérifie que la valeur décimale n'est pas supérieure au paramètre ;
add_RangeDecimal() : vérifie que la valeur décimale est comprise entre les deux paramètres ;
add_MinLength() : vérifie que la chaîne de caractères a une taille minimale ;
add_MaxLength() : vérifie que la chaîne de caractères ne dépasse pas un certain nombre de caractères ;
add_Size() : vérifie que la taille de la chaîne de caractères est comprise entre les deux paramètres ;
add_DatePast() : vérifie que la date-heure est dans le passé ;
add_DateFuture() : vérifie que la date-heure est dans le futur ;
add_RegExp() : vérifie que la chaîne de caractères est compatible avec l'expression régulière passée en paramètre ;
add_EMail() : vérifie que la chaîne de caractères correspond à un e-mail.

Comme dans l'exemple de la classe 'person', il est possible de définir également des validateurs personnalisés : ce sont des fonctions ou méthodes de classe qui seront appelées automatiquement par le module QxValidator pour valider une propriété ou une instance de classe. Il existe trois types de validateurs personnalisés :

add_CustomValidator() : méthode de classe, la signature de la méthode doit être "void my_class::my_method(qx::QxInvalidValueX &)" ;
add_CustomValidator_QVariant() : fonction globale avec type QVariant (propriété convertie en QVariant), la signature de la fonction doit être "void my_validator(const QVariant &, const qx::IxValidator *, qx::QxInvalidValueX &)" ;
add_CustomValidator_DataType() : fonction globale avec le type réel de la propriété, la signature de la fonction doit être "void my_validator(const T &, const qx::IxValidator *, qx::QxInvalidValueX &)" ;

Remarque : à chaque validateur peut être associé un groupe (paramètre optionnel pour chaque méthode add_XXX() de la classe qx::IxValidatorX). Il est ainsi possible de créer des groupes de validation suivant le contexte d'exécution : par exemple, valider la saisie d'une personne sur une IHM A ne nécessite peut-être pas les mêmes vérifications que valider une personne sur une IHM B. Pour exécuter la validation d'une instance pour un groupe donné (par exemple "myGroup"), il faut appeler la fonction suivante : "qx::QxInvalidValueX invalidValues = qx::validate(personValidate, "myGroup");".

Autre remarque : le module QxValidator définit des messages par défaut lorsqu'une contrainte n'est pas vérifiée. Il est possible de redéfinir ces messages par défaut en modifiant la collection suivante : "QHash<QString, QString> * lstMessage = QxClassX::getAllValidatorMessage();". Par exemple : "lstMessage->insert("min_value", "la valeur '%NAME%' doit être inférieure ou égale à '%CONSTRAINT%'");". Les champs %NAME% et %CONSTRAINT% seront automatiquement remplacés par les valeurs correspondantes. Pour modifier le message pour un validateur donné (et non de manière globale), il faut utiliser le paramètre optionnel disponible pour les méthodes add_XXX() de la classe qx::IxValidatorX.

**djarBoy** · 12/01/2012, 17h27

Salut !

Très intéressante cette notion ! C'est amusant car justement, je m'apprêtais à faire un truc similaire !

Dans ton exemple, tu mets isValid en private de la classe person, chez moi, j'ai une erreur de compilation quand j'essaie de faire ça:

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
 
pAllValidator->add_CustomValidator(& person::isValid);

Note: j'utilise gcc sous ubuntu.

**QxOrm** · 13/01/2012, 09h39

Dans ton exemple, tu mets isValid en private de la classe person, chez moi, j'ai une erreur de compilation...

Regarde bien la définition de la classe qx::test::CPerson que j'ai mis en exemple, j'ai ajouté la macro QX_REGISTER_FRIEND_CLASS(qx::test::CPerson).
En effet, si tu définis des membres privés dans ta classe persistante, il faut ajouter la macro QX_REGISTER_FRIEND_CLASS pour pouvoir les utiliser dans la fonction qx::register_class<T>().

* Pourquoi j'ai mis la méthode isValid() en private ?
Je pense que c'est une bonne pratique pour forcer l'utilisateur de la classe à utiliser la fonction qx::validate() (et non myPerson.isValid()).
Mais tu n'es pas obligé de suivre ce conseil si tu préfères créer une méthode isValid() en public

**djarBoy** · 13/01/2012, 12h24

Ah oui ok !

Non, c'est une bonne idée, je vais faire ça

Version BETA : QxOrm 1.2.2 - Nouveau module QxValidator à tester

QxOrm

Discussions similaires

Partager

Partager