Curseurs d'objets (tech)

Introduction

Les curseurs d'objets (TCursor) permettent d'accéder à un ou plusieurs objets d'une base de données en spécifiant des critères de recherche et de tri ou en utilisant directement des instructions SQL.

Note : Les listes d'objets peuvent être utilisé comme attribut non persistant

Généralement l’utilisation d’un curseur suit le schéma suivant :

1. Le curseur est créé sur une classe particulière, ce sont les objets de cette classe qui seront retournés.
2. Les critères de recherche et de tri sont définis.
3. Le curseur est ouvert.
4. Tant qu’il existe des objets dans le résultat, le curseur est parcouru ; les objets sont retournés un par un dans cette boucle.
5. Le curseur est fermé.

Les curseurs peuvent être implémentés de manière différente suivant les types de serveur de données ; un certain nombre de règles doivent être respectées :

1. Les curseurs sont prévus pour retourner des objets ; ne pas utiliser d’ordre de mise à jour dans le code SQL définissant un curseur.
2. Lorsqu’un curseur est utilisé dans le cadre d’une transaction longue, il est nécessaire de créer la transaction longue avant le curseur.

Déclaration d'une variable curseur

Les curseurs doivent être déclarée avant d'être utilisées, lorsque la classe du curseur est connue au moment de la déclaration la forme préfixé du nom de la classe métier peut être utilisée :

var ls:NomDeClassCursor;

Cette forme de déclaration permet au compilateur de connaitre la classe des objets du curseur.

Création d'un objet curseur

Utilisation du ClassManager

Le ClassManager expose une fonction pour créer des curseurs d'une classe donnée :

function CreateCursor(const iClassName :string):TCursor;

iClassName représente le nom de la classe des objets retournés par le curseur.

Exemple

var ls:TEcritureCursor;
begin
  ls := ClassManager.CreateCursor('TEcriture');
end;

Utilisation du constructeur de curseur d'une classe métier

Les classes métiers exposent un constructeur de curseur permettant de créer un curseur de la classe :

class function TObjectClass.CreateCursor:TObjectClassCursor;

Exemple

var ls:TEcritureList;
begin
  ls := TEcriture.CreateCursor;
end;

Note : Les deux formes de code sont équivalentes, la seconde est plus claire et évite les erreurs de frappe du nom des classes

Propriétés

Propriétés de paramétrage du curseur

ClassName	Nom de la classe sur laquelle porte le curseur.
Where	Critère de recherche objet permettant de sélectionner les enregistrements renvoyés.
ArgCount	Spécifie le nombre d'arguments utilisés dans WHERE.
Args	La propriété Args permet de consulter et de modifier dynamiquement la valeur des arguments utilisés dans WHERE.
OrderBy	Spécifie l'ordre de tri des enregistrements.
Descendants	Inclure ou non les objets descendants.
ClassFilter	Critère de recherche sur la classe des l'objets parcourus.
MaxInstances	Limite le nombre d'objet retourné.
NoLock	Utilise un Hint de base de données pour ne pas verrouiller la table SQL parcourue.
AnyWhere	Ne pas filter les objets sur les périmètres de partage.
SQL	La propriété SQL permet de définir directement les instructions SQL exécutées par le composant.
Translator	Objet technique permettant de formatter le code SQL en fonction du pilote de base de données

Propriétés des curseurs avec agrégats

Les curseurs avec agrégats permettent d'exprimer sous forme objet l'équivalent d'un agrégat SQL.

Lorsque des agrégats sont utilisés sur un curseur celui-ci ne peut pas retourner une instance d'objet et retourne des champs SQL.

La numérotation des champs SQL est :

• Les champs de regroupement.
• Les champs agrégés.

Tip : L'utilisation de ces propriétés évitent d'écrire un curseur sous forme SQL.

AgregateCount	Détermine le nombre d'agrégat
Agregates	Détermine un attribut à agréger.
AgregateOpes	Détermine l'opérateur de l'agrégat.
GroupByCount	Détermine le nombre d'attribut à regrouper.
GroupBys	Détermine un attribut à regrouper.
FieldCount	Retourne le nombre de champs SQL de la requête.
Fields	Retourne la valeur courante du champ de la requête.

Exemple d'utilisation d'un curseur avec agrégats :

//Procedure TotalEngaementParNature(out rslt:WSX_NatureEngagementList);
var vCursor:TDetailEngagementCursor; inst:WSX_NatureEngagement;
begin
  vCursor := TDetailEngagement.CreateCursor;
  vCursor.Descendants := True;
  vCursor.AgregateCount := 1;
  vCursor.Agregates[1] := 'montantValorisation';
  vCursor.GroupBycount := 1;
  vCursor.GroupBys[1] := 'NatureBudgetaire.code';
  vCursor.Open;
  while not vCursor.Eoi do
   begin
     inst := WSE_NatureEngagement.Create;
     inst.Code := vCursor.Fields[0];
     inst.Montant := vCursor.Fields[1];
     rslt.AddRef(inst);
     vCursor.Next;
   end;
end;

Tip : Une autre façon de réaliser un curseur sur des agrégats est d'utiliser un curseur sur une vue avec agrégats; cette manière est préférable car elle utilise un formalisme objet et pas SQL

Propriétés d'exécution

EOI	Indique si le curseur a atteint la fin de l'ensemble de données.
LOI	Indique si le curseur est positionné sur le dernier enregistrement d'un ensemble de données.
Count	Renvoie le nombre d'objet qui sera parcourus par le curseur.
FetchCount	Renvoie le nombre de fetch réalisés.
OID	Renvoie l'identifiant de l'objet courant.
Instance	Renvoie l'instance d'objet courant. La classe de cette instance est la classe spécifiée à la création du curseur.

Méthodes

Open	Exécute la requête.
Close	Ferme le curseur.
Rollback	Annule toutes les modifications, insertions ou suppressions de données de la transaction en cours et termine la transaction Valable pour un curseur de type modification.
Next	Appelez Next pour placer le curseur sur l'enregistrement suivant.

— Code métier — Développement DSM —