Table of Contents

RequestDAL

Descor.RequestCenter.DAL.OracleODP.RequestDAL — adapter di accesso dati Oracle per il dominio Request/Ticket. Implementa il contratto IRequestDAL come insieme di wrapper sottili attorno alle stored procedure dei package GESTREQUEST e GESTREQUEST_T2. Classificazione: VERIFIED.

Scopo

RequestDAL è l'unica implementazione del contratto IRequestDAL (letture/scritture della richiesta di servizio, ticket). Ogni metodo pubblico segue lo stesso schema proc-wrapper: costruisce gli OracleParameter, ottiene il gestore di connessione cm, apre la connessione, invoca una stored procedure Oracle tramite cm.ExecuteNonQuery / cm.ExecuteReader / cm.Fill, quindi rilascia la connessione. Non contiene logica di business: la validazione, l'orchestrazione transazionale e le regole vivono nel livello BL (Descor.RequestCenter.Ticket.Request, vedi class-Ticket-Request.md).

Namespace e progetto

  • Namespace: Descor.RequestCenter.DAL.OracleODP (RootNamespace del progetto). Classificazione: SUPPORTED (RequestCenter.DAL.OracleODP.vbproj).
  • Progetto: RequestCenter.DAL.OracleODP — VB.NET, net48, driver Oracle.DataAccess (ODP.NET unmanaged).
  • File: RequestDAL.vb (~8433 righe; 246 membri Function che implementano IRequestDAL). Classificazione: VERIFIED (wc -l = 8433; conteggio membri nel blocco IRequestDAL = 246).
  • Re-link .NET 8: il progetto RequestCenter.DAL.OracleODPXNET (net8.0) ri-collega 36 dei 38 file DAL via <Compile Include=..\RequestCenter.DAL.OracleODP\*.vb Link=..>; una guardia #If NET5_0_OR_GREATER seleziona il driver managed Oracle.ManagedDataAccess. Le direttive Imports in testa a RequestDAL.vb (righe 3-10) confermano il doppio target. Classificazione: VERIFIED (RequestDAL.vb:3-10 + spec di progetto).

Responsabilità

  • Tradurre le chiamate del BL in invocazioni di stored procedure Oracle dei package GESTREQUEST (~41 riferimenti) e GESTREQUEST_T2 (~9). Classificazione: SUPPORTED (conteggio riferimenti da spec del batch; grep sul sorgente conferma prevalenza di GESTREQUEST.*).
  • Materializzare i risultati come DataSet (variante base) o IDataReader (variante *DReader) per le operazioni di lettura.
  • Restituire l'identificativo generato in scrittura (es. NEWREQUESTINDEX per addRequest).

Perché esiste

UNKNOWN — la motivazione storica della separazione in package GESTREQUEST / GESTREQUEST_T2 non è documentata nelle fonti disponibili. È osservabile solo che GESTREQUEST_T2 raccoglie procedure più recenti (es. ADDREQUEST con protocollo, ADDCUSTOMITEMTOREQUEST), mentre GESTREQUEST contiene la variante ADDREQUESTWITHOUTPROTOCOL e i setter di dettaglio.

Contratto pubblico

Tutti i membri pubblici derivano da IRequestDAL (vedi interface-IRequestDAL.md). Si distinguono tre famiglie:

Famiglia Verbo Ritorno Meccanismo cm
Letture Load, getByProtocol, getRequestList, getRequestListBy*, getUserRequestList, … (+ gemello *DReader) DataSet / IDataReader cm.Fill (DataSet) / cm.ExecuteReader (DReader)
Scritture "add/set" addRequest, setProtocol, setDescription, setWorkflowInterface, setManagement, setContract, … Integer (righe interessate o indice generato) cm.ExecuteNonQuery
Chiusura/cancellazione closeRequest, deleteRequest Integer cm.ExecuteNonQuery

Implementazioni o classi derivate

RequestDAL implementa IRequestDAL (Implements IRequestDAL, RequestDAL.vb:14) ed eredita BaseDAL (Inherits BaseDAL, RequestDAL.vb:13). È l'unica implementazione nota del contratto per il backend Oracle ODP. Classificazione: SUPPORTED (RequestDAL.vb:12-14).

Dipendenze

  • GlobalDataManager (cm) — ottenuto via Configuration.Settings.GetConnectionManager (letture) o GetConnectionManager(True) (scritture). È il motore che esegue le procedure. Vedi class-GlobalDataManager.md.
  • Oracle.DataAccess (OracleParameter, OracleDbType, Types.OracleDecimal) sotto net48; Oracle.ManagedDataAccess sotto net8.0.
  • Descor.RequestCenter.Interfaces.Ticket — il contratto IRequestDAL (RequestDAL.vb:1).

Ciclo di vita

Istanza priva di stato condiviso: ogni metodo ricava cm localmente, non conserva connessioni tra chiamate. La connessione viene aperta con cm.Open e rilasciata nel blocco Finally con cm.CloseIfNeeded(openResult) (dove openResult As OpenConnectionResult traccia se la connessione è stata realmente aperta dal metodo o riusata da una transazione in corso). Classificazione: VERIFIED (schema ripetuto in tutti gli anchor letti, es. RequestDAL.vb:29-39, 5076-5086).

Stato interno

Nessuno stato di istanza rilevante oltre a quello ereditato da BaseDAL. Le variabili cm, openResult, i parametri e l'eventuale DataSet sono locali al metodo.

Metodi principali

I blocchi seguenti documentano i metodi di scrittura chiave e sintetizzano la famiglia di lettura. I ~246 metodi non sono documentati singolarmente: quelli non elencati seguono identico schema proc-wrapper (spec §4.3, raggruppamento dei banali).

Public Function addRequest(iduser As Integer, idtenant As Integer, protocol As String, protocolcode As String, subcode As Integer, protocollevelparent As Integer, requestdate As Nullable(Of Date)) As Integer

  • Scopo: creare una nuova richiesta con protocollo e restituirne l'identificativo generato.
  • Attese del chiamante: parametri di identità (iduser, idtenant) e di protocollo già risolti dal BL.
  • Parametri: mappati 1:1 su OracleParameter (PIDUSER, PIDTENANT, PPROTOCOL, PPROTOCOLCODE, PSUBCODE, PPROTOCOLLEVELPARENT, PREQUESTDATE) più il parametro OUT NEWREQUESTINDEX (ParameterDirection.Output).
  • Valore di ritorno: Integer = DirectCast(newIndexParam.Value, Types.OracleDecimal).ToInt32 — l'ID della richiesta creata.
  • Letture DB / Scritture DB: WRITE via GESTREQUEST_T2.ADDREQUEST. A livello di package, GESTREQUEST_T2 scrive REQUESTREGISTRY (RW) e REQUESTREGISTRYDATA (RW); la scrittura sulla tabella anagrafica REQUESTREGISTRY è il side effect atteso. Vedi procedures.md e crud-matrix.md. Classificazione: proc VERIFIED (RequestDAL.vb:5078); mappatura tabella al livello di package SUPPORTED (crud-matrix / stored-procedure-dependencies.csv), a livello di singola procedura INFERRED.
  • Ambito transazionale: GetConnectionManager(True) segnala partecipazione a transazione (vedi Transazioni); commit/rollback governati dal BL tramite RequestCenter.Transaction.
  • Overload: addRequest(iduser, idtenant, requestdate) (RequestDAL.vb:5089) crea la richiesta senza protocollo via GESTREQUEST.ADDREQUESTWITHOUTPROTOCOL, stesso pattern OUT NEWREQUESTINDEX.
  • Side effect: creazione riga anagrafica della richiesta.
  • Comportamento in errore e ripristino: blocco Catch attivo solo in build #If DEBUG (rilancia con Throw); in Finally sempre cm.CloseIfNeeded(openResult).
  • Classificazione: VERIFIED (RequestDAL.vb:5054-5087).

Public Function setDescription(idrequest As Integer, dsrequest As String) As Integer

  • Scopo: impostare/aggiungere il testo descrittivo della richiesta.
  • Parametri: PIDREQUEST (Int32), PDSREQUEST (Varchar2).
  • Valore di ritorno: Integer restituito direttamente da cm.ExecuteNonQuery (righe interessate).
  • Letture DB / Scritture DB: WRITE via GESTREQUEST.ADDDESCRIPTIONTOREQUEST. Il package GESTREQUEST scrive REQUESTREGISTRY; l'aggiornamento della descrizione insiste sull'anagrafica della richiesta. Classificazione: proc VERIFIED (RequestDAL.vb:5419); tabella INFERRED (mappatura solo a livello di package).
  • Nota BL: corrisponde a Request.SetDescription / WriteDescription nel livello BL (vedi class-Ticket-Request.md).
  • Ambito transazionale: GetConnectionManager(True).
  • Classificazione: VERIFIED (RequestDAL.vb:5407-5427).

Public Function setWorkflowInterface(idrequest As Integer, idworkflowelement As Integer) As Integer

  • Scopo: collegare la richiesta a un elemento di workflow (interfaccia di flusso).
  • Parametri: PIDREQUEST (Int32), PIDELEMENT (Int32).
  • Valore di ritorno: Integer da cm.ExecuteNonQuery.
  • Letture DB / Scritture DB: WRITE via GESTREQUEST.ADDWORKFLOWINTERFACE. Il package GESTREQUEST scrive la tabella REQUESTWORKFLOWINTERFACE (WRITE nella crud-matrix). Classificazione: proc VERIFIED (RequestDAL.vb:5653); tabella SUPPORTED (nome tabella + dipendenza di package concordi).
  • Nota BL: corrisponde a Request.SetWorkflowInterface (Request.vb:2596).
  • Classificazione: VERIFIED (RequestDAL.vb:5641-5661).

Public Function closeRequest(idrequest As Integer, closedate As Date) As Integer

  • Scopo: registrare la chiusura della richiesta a una data.
  • Parametri: PIDREQUEST (Int32), PCLOSEDATE (Date).
  • Valore di ritorno: Integer da cm.ExecuteNonQuery.
  • Letture DB / Scritture DB: WRITE via GESTREQUEST.ADDCLOSETOREQUEST; insiste sull'anagrafica REQUESTREGISTRY (package GESTREQUEST). Classificazione: proc VERIFIED (RequestDAL.vb:6254); tabella INFERRED.
  • Ambito transazionale: ottiene cm via GetConnectionManager (senza argomento True), a differenza degli altri setter. Classificazione: SUPPORTED (RequestDAL.vb:6243) — vedi issues del manifest.
  • Nota BL: corrisponde a Request.Close (Request.vb:2758).
  • Classificazione: VERIFIED (RequestDAL.vb:6242-6262).

Public Function deleteRequest(idrequest As Integer) As Integer

  • Scopo: cancellare la richiesta.
  • Parametri: dichiara PIDREQUEST (Int32).
  • Valore di ritorno: Integer da cm.ExecuteNonQuery.
  • Letture DB / Scritture DB: invoca la stored procedure standalone DELETEREQUEST (non package-qualificata). In stored-procedure-dependencies.csv, DELETEREQUEST legge REQUESTREGISTRY e delega alla procedura XADMINDELETEREQUEST (riferimento a PROCEDURE) l'effettiva cancellazione a cascata. Classificazione: proc VERIFIED (RequestDAL.vb:6273); catena di cancellazione SUPPORTED (csv).
  • Debito tecnico: il parametro idRequestParam è dichiarato (RequestDAL.vb:6269) ma non gli viene assegnato .Value prima di cm.ExecuteNonQuery, a differenza di tutti gli altri metodi. Il valore inviato risulta quindi Nothing/non impostato. Segnalato in issues; PORTAL-ONLY, non modificato. Classificazione: SUPPORTED (RequestDAL.vb:6269-6273 — assenza dell'assegnazione).
  • Nota BL: corrisponde a Request.Delete (Shared, Request.vb:2813).
  • Classificazione: VERIFIED per struttura, SUPPORTED per il difetto (RequestDAL.vb:6264-6281).

Famiglia di lettura — Load / get* (con gemelli DataSet + DReader)

  • Scopo: recuperare una richiesta o una lista di richieste secondo diversi criteri (id, protocollo, calltype/gruppo, asset, oggetto di manutenzione, contratto, azienda, utente, filtro composito).
  • Schema comune: ogni operazione di lettura è tipicamente offerta in due gemelli:
    • variante base → ritorna DataSet, eseguita con cm.Fill(ds, "PROC", params…);
    • variante *DReader → ritorna IDataReader, eseguita con cm.ExecuteReader("PROC", params…).
  • Esempi verificati:
    • Load(idrequest) → GETREQUEST via cm.Fill (RequestDAL.vb:18-40); gemello LoadDReader → GETREQUEST via cm.ExecuteReader (RequestDAL.vb:42-60).
    • getRequestList(idcalltype, egroup) → GETREQUESTLIST via cm.Fill (RequestDAL.vb:733-757); gemello getRequestListDReader → GETREQUESTLIST via cm.ExecuteReader (RequestDAL.vb:759-779).
    • Il parametro OUT DS_CUR (OracleDbType.RefCursor, ParameterDirection.Output) veicola il result set in tutte le letture.
  • Letture DB: READ. GETREQUEST legge un'ampia rosa di tabelle REQUEST* (REQUESTREGISTRY, REQUESTAPPROVAL, REQUESTCATEGORY, REQUESTCOMPLAINT, REQUESTFROMTYPE, REQUESTLINKED, CALLTYPE, …). Classificazione: SUPPORTED (csv).
  • Filtri complessi: getIdRequestListByFilter / …DReader (RequestDAL.vb:333 area, contratto a TicketInterfaces.vb:61-80) accettano ~45 parametri opzionali di filtro più un customfieldSQL As String. Classificazione: SUPPORTED (TicketInterfaces.vb:61-80).
  • Classificazione complessiva: VERIFIED (schema gemello osservato su più anchor letti).

Collaborazioni

  • BL Request (class-Ticket-Request.md) è il chiamante primario: i suoi setter (SetDescription, SetWorkflowInterface, Close, Delete, Create) invocano i metodi omologhi di RequestDAL.
  • GlobalDataManager (class-GlobalDataManager.md) esegue effettivamente le procedure e governa apertura/chiusura connessione e transazione.
  • RequestCenter.Transaction avvolge le scritture (OpenConnection → Begin → Commit/Rollback → CloseConnection), vedi il flusso FLOW-REQ-001.md (area addRequest, RequestDAL.vb:5078).

Accesso al database

Metodo Package.Proc Direzione Tabella/e (granularità package) Classific. mappatura
addRequest (con protocollo) GESTREQUEST_T2.ADDREQUEST WRITE REQUESTREGISTRY, REQUESTREGISTRYDATA INFERRED (package RW)
addRequest (overload) GESTREQUEST.ADDREQUESTWITHOUTPROTOCOL WRITE REQUESTREGISTRY INFERRED
setDescription GESTREQUEST.ADDDESCRIPTIONTOREQUEST WRITE REQUESTREGISTRY INFERRED
setWorkflowInterface GESTREQUEST.ADDWORKFLOWINTERFACE WRITE REQUESTWORKFLOWINTERFACE SUPPORTED
closeRequest GESTREQUEST.ADDCLOSETOREQUEST WRITE REQUESTREGISTRY INFERRED
deleteRequest DELETEREQUEST (→ XADMINDELETEREQUEST) WRITE (cascata) REQUESTREGISTRY + delega SUPPORTED
Load / LoadDReader GETREQUEST READ molte REQUEST* + CALLTYPE SUPPORTED
getRequestList / …DReader GETREQUESTLIST READ REQUEST* SUPPORTED

Riferimenti: REQUESTCENTER_TEST38/index.md, tables.md, procedures.md, crud-matrix.md.

Transazioni

Il gestore cm è ottenuto con GetConnectionManager(True) nella maggioranza dei setter di scrittura (l'argomento richiede la partecipazione alla transazione corrente); le letture e closeRequest usano GetConnectionManager senza argomento. Il controllo di commit/rollback non è nel DAL: è esposto dal BL via RequestCenter.Transaction (Begin/Commit/Rollback). Classificazione: SUPPORTED (RequestDAL.vb:5055/5090/5408/5642/6243/6265 + FLOW-REQ-001).

Autorizzazione

Nessun controllo di autorizzazione nel DAL: è responsabilità del BL / del livello web (gate RequestCenterPage.Page_PreInit). Classificazione: INFERRED (assenza di controlli negli anchor letti).

Side effect

Scritture su tabelle REQUEST* (creazione, aggiornamento descrizione/chiusura, collegamento workflow, cancellazione a cascata). Nessun invio a sistemi esterni osservato in questi metodi.

Gestione degli errori

Pattern uniforme: blocco Try … Finally, con un ramo Catch ex As Exception … Throw compilato solo sotto #If DEBUG (in Release non c'è cattura intermedia e l'eccezione propaga direttamente). Il Finally esegue sempre cm.CloseIfNeeded(openResult) (assente nelle varianti *DReader, che lasciano aperto il reader al chiamante). Classificazione: VERIFIED (RequestDAL.vb:33-39, 50-59, 5080-5086).

Thread safety

Non documentata. Ogni chiamata usa un cm locale; la sicurezza rispetto ai thread dipende da GlobalDataManager e dalla gestione della connessione. Classificazione: UNKNOWN.

Considerazioni sulle prestazioni

Le varianti *DReader (streaming via IDataReader) evitano la materializzazione in DataSet e sono preferibili per liste ampie; le varianti DataSet sono più comode ma copiano l'intero result set in memoria. Classificazione: INFERRED.

Esempio di utilizzo

Non eseguito su questo host (macOS, no Oracle Client). Schema d'uso verificato staticamente dal BL: il livello Request apre una RequestCenter.Transaction, invoca addRequest/set*, poi Commit. Vedi FLOW-REQ-001.md.

Test correlati

Nessun test automatico nel repository (0 unità di test). Non è dichiarata copertura.

Flussi correlati

  • FLOW-REQ-001.md — creazione/gestione richiesta (area addRequest, RequestDAL.vb:5078).

Regole di business correlate

Limitazioni

  • Mappatura metodo→tabella disponibile solo a granularità di package (stored-procedure-dependencies.csv aggrega le dipendenze delle procedure interne ai package GESTREQUEST/GESTREQUEST_T2); la tabella precisa per singola procedura non è ricostruibile dalle fonti del portale.
  • RequestCSDAL.vb e RequestCSReasonDAL.vb sono esclusi dal re-link net8.0 (RequestCenter.DAL.OracleODPXNET).

Debito tecnico

  • deleteRequest non assegna .Value al parametro PIDREQUEST (RequestDAL.vb:6269-6273) — vedi blocco metodo e issues.

Evidenze

  • InfocadWeb/WebMachine/RequestCenter.DAL.OracleODP/RequestDAL.vb:1-14 (Imports, Inherits BaseDAL, Implements IRequestDAL, guardia #If NET5_0_OR_GREATER).
  • RequestDAL.vb:18-40 (Load→GETREQUEST, cm.Fill), :42-60 (LoadDReader, cm.ExecuteReader).
  • RequestDAL.vb:733-779 (getRequestList/…DReader→GETREQUESTLIST).
  • RequestDAL.vb:5054-5087 (addRequest→GESTREQUEST_T2.ADDREQUEST, OUT NEWREQUESTINDEX), :5089-5114 (overload→GESTREQUEST.ADDREQUESTWITHOUTPROTOCOL).
  • RequestDAL.vb:5407-5427 (setDescription→GESTREQUEST.ADDDESCRIPTIONTOREQUEST).
  • RequestDAL.vb:5641-5661 (setWorkflowInterface→GESTREQUEST.ADDWORKFLOWINTERFACE).
  • RequestDAL.vb:6242-6262 (closeRequest→GESTREQUEST.ADDCLOSETOREQUEST, GetConnectionManager senza True).
  • RequestDAL.vb:6264-6281 (deleteRequest→DELETEREQUEST; PIDREQUEST senza .Value).
  • InfocadWeb/WebMachine/RequestCenter/Interfaces/TicketInterfaces.vb:39-116 (contratto IRequestDAL).
  • Metadati: wc -l RequestDAL.vb = 8433; 246 Function nel blocco IRequestDAL.
  • DB: docs/_generated/stored-procedure-dependencies.csv (dipendenze package GESTREQUEST/GESTREQUEST_T2, DELETEREQUEST→XADMINDELETEREQUEST, GETREQUEST READ multi-tabella); 05-databases/crud-matrix.md; 05-databases/REQUESTCENTER_TEST38/{index,tables,procedures}.md.