Curseurs d'objets (tech)

Version du 17 octobre 2011 à 07:56

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

Nom	Type	Usage
WHERE	String	Critère de recherche objet permettant de sélectionner les enregistrements renvoyés.
ARGCOUNT	Integer	Spécifie le nombre d'arguments utilisés dans WHERE.
ARGS [ INDEX ]	property Args[index]:Integer;	La propriét Args permet de consulter et de modifier dynamiquement la valeur des arguments utilisés dans WHERE.
ORDERBY	String	Spécifie l'ordre de tri des enregistrements.
DESCENDANTS	Boolean	Inclure ou non les objets descendants.
CLASSFILTER	String	Critère de recherche sur la classe des l'objets parcourus.
MAXINSTANCES	Integer	Limite le nombre d'objet retourné.
NOLOCK	Boolean	Utilise un Hint de base de données pour ne pas verrouiller la table SQL parcourue. Attention : Peut dépendre du pilote de base de données.
ANYWHERE	Boolean	Ne pas filter les objets sur les périmètres de partage. Attention : Cette option n'est à utiliser que pour les dossiers multi-société dans les traitements de type inter-sociétés.
SQL	TStrings	La propriété SQL permet de définir directement les instructions SQL exécutées par le composant. Attention : Aucun contrôle n'est effectué sur le SQL défini dans cette propriété.
TRANSLATOR	Translateur SQL	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.

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

procedure Open;

procedure Close;

procedure RollBack;

procedure Next;

Exemples

Utilisation de Where

function getCursor:TCursor;
var
  vDOLCursorList : TCursor;
  vWhere : String;
begin
  vDOLCursorList := ClassManager.CreateCursor('TDetailOperationLogistique');
  vDOLCursorList.Where := '(oidLotProduit = %1) and (oidDepot = %2) and (dateExecution >= %3)';
  vDOLCursorList.ArgCount := 3;
  vDOLCursorList.Args[1] := aOidLotProduit ;
  vDOLCursorList.Args[2] := aOidDepot ;
  vDOLCursorList.Args[3] := aDate ;
  //
  vDOLCursorList.NOLOCK := TRUE;
  vDOLCursorList.Open;
  Result := vDOLCursorList;
end;

Utilisation de Count

//Function CountByCursor(aNomClasse:string):integer;
var vCursorOP :TCursor;
begin
  vCursorOP := ClassManager.CreateCursor(aNomClasse);
  vCursorOP.Descendants := True;
  vCursorOP.Where := aRequete;
  result := vCursorOP.Count;
end;

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;