ERP 2.50:Developers Guide/How to create build validations and module scripts/it

Contents 1 Obiettivo 2 Convalida di Compilazione 2.1 Introduzione all' implementazione di validazioni di compilazione 2.2 Scrivere le validazioni di compilazione 2.3 Compilare la validazione di compilazione 2.4 Eseguire la validazione di compilazione 3 Scripts di Modulo 3.1 Introduzione all'implementazione di scripts di modulo 3.2 Scrivere lo script di modulo 3.3 Compiling the module script 3.4 Eseguire lo script di modulo

Obiettivo

In questo articolo howto, creeremo sia un Validazione di Build che uno Script di Modulo. Sono due concetti molto simili, e sono anche implementate allo modo molto, quindi ci accingiamo a descriverle nello stesso documento.

Convalida di Compilazione

Una Convalida di Compilazione in Openbravo è una classe che viene eseguita all'inizio della task update.database, e che restituisce un elenco di errori. Se c'è uno o più errori, l'operazione di Compilazione si ferma, e gli errori vengono mostrati all'utente.

A causa di questo, gli errori vengono visualizzati per l'utente, la Convalida deve seguire queste regole:

• In un modo standard un messaggio di prompt compare spiegando che la Convalida non è riuscita ma il sistema rimane stabile. Questo è molto importante

• Nel messaggio deve essere chiara la causa del guasto e se necessario bisogna creare una regola di avviso per aiutare gli utenti a identificare i record problematici se alla fine la compilazione fallisce.

• Ogni sviluppatore deve garantire e controllare che il messaggio sia comprensibile, una volta che crea la convalida

Si prega di vedere questa immagine come esempio:

• A partire dalla MP21 potete trovare un esempio chiaro e semplice di come sviluppare una Convalida contenente gli avvisi in:
  • src-util/buildvalidation/src/org/openbravo/buildvalidation/Cbpvendoracct_data.xsql
  • src-util/buildvalidation/src/org/openbravo/buildvalidation/Cbpvendoracct.java

L'utilizzo principale delle convalide di compilazione è quello di fermare la compilazione perché l'istanza è in uno stato tale che la ricompilazione del sistema non può essere tranquillamente fatta. Nei moduli, le convalide possono essere utilizzate per fermare la compilazione nel caso in cui il modulo non può essere installato in modo sicuro nel sistema per qualche motivo.

Così, per esempio, una validazione potrebbe essere utilizzato per controllare se l'utente ha fatto un passo necessario della configurazione manuale, che non può essere automatizzato. O una di convalida potrebbe anche essere utilizzato per controllare se l'utente ha compilato alcuni dati che sono necessari affinchè il modulo sia installato correttamente.

Convalide di compilazione sono un pezzo di codice diverso in Openbravo, in quanto sono distribuiti come file binari (classi compilate), che vengono eseguiti direttamente, senza che siano compilato sull'esecuzione. Il task di packaging per moduli include automaticamente i file binari all'interno del file. obx, lo sviluppatore deve solo fare in modo che le classi siano state compilate prima del confezionamento del modulo.

Introduzione all' implementazione di validazioni di compilazione

I passi principali per creare una validazione di compilazione sono:

1 .- Scriverla (è necessario creare una classe Java per ogni convalida che si vuole fare).

2.- Compilarla (le validazioni di compilazione sono compilate separatamente dal resto del codice Openbravo, utilizzando una specifica task ant di compilazione).

3.- Testarla (è necessario verificare attentamente la convalida prima di includere nel vostro modulo, o nel Core).

4.- Aggiungerlo al modulo, o Core (Non dimenticate di aggiungere le classi binarie, in quanto sono necessarie, oltre ai file sorgente di Java. ant package.module aggiungerà automaticamente i file al file. obx , ma è necessario aggiungere manualmente i file binari in aggiunta al file di origine al repository Mercurial se si utilizza uno per il vostro modulo, o se si desidera aggiungere la convalida per Core).

Per creare una validazione di compilazione, bisogna creare una classe che estende la classe org.openbravo.buildvalidation.BuildValidation . Questa è una classe astratta che ha un metodo astratto : List<String> execute()

Questo metodo bisogna implementarlo. La classe verrà caricata all'inizio del task di update.database, e questo metodo verrà chiamato. Come visto, una Lista di Stringhe deve essere restituita . Se la lista è vuota, il build continuerà. Se la lista contiene almeno una stringa, ogni stringa verrà mostrata all'utente, e il build si fermerà . Ogni stringa si suppone essere un messaggio di errore , che mostra all'utente cosa bisonga fare per sistemarlo nel suo sistemaaffinche la validazione sia positiva.

Scrivere le validazioni di compilazione

Come spiegato , una validazione di compilazione non è nulla di più di una classe che estende la classe org.openbravo.buildvalidation.BuildValidation , e implementa il metodo astratto execute. Di seguito qui un esempio :

 
 
public class ValidationExample extends BuildValidation {
 
  public List<String> execute() {
    try {
      ConnectionProvider cp = getConnectionProvider();
      PreparedStatement ps = cp
          .getPreparedStatement("SELECT COUNT(*) FROM C_Bpartner WHERE name IS NULL");
      ps.execute();
      ResultSet rs = ps.getResultSet();
      rs.next();
      ArrayList<String> errors = new ArrayList<String>();
      if (rs.getInt(1) > 0) {
        errors
            .add("There are business partners which don't have a defined name. Please fill the name of every business partner before installing the module MyModule.");
      }
      return errors;
    } catch (Exception e) {
      return handleError(e);
    }
  }
}

In questo esempio , si possono vedere i punti principali di ogni validazione di build validation:

• La classe implementa la classe BuildValidation , e i suoi relativi metodi di execute .
• Nel metodo, si può fare la validazione (i.e. controlla se l'istanza di Openbravo rispetta le regole specifiche). C'è un metodo conveniente getConnectionProvider() , fornito dalla superclasse astratta, che permette di fare queries dirette al database. E' molto importante notare che le validazioni dovrebbero solo fare queries sul database, non dovrebbero mai cambiare i contenuti del database. Scripts dei Moduli possono essere usati per cambiare il database se necessario.
• Finalmente, il metodo restituisce una Lista di Stringhe di errori, che possono essere vuote se la validazione va a buon fine, o può contenere uno o più errori se il sistema non soddisfa la validazione.

Si può anche usare SqlC se si vuole fare operazioni sul database.

 
public class ValidationExample2 extends BuildValidation {
 
  public List<String> execute() {
    try {
      ConnectionProvider cp = getConnectionProvider();
      ArrayList<String> errors = new ArrayList<String>();
      int numBpartners=Integer.parseInt(ValidationExample2Data.queryBPartners(cp));
      if (numBpartners > 0) {
        errors.add("There are business partners which don't have a defined name. Please fill the name of every business partner before installing the module MyModule.");
      }
      return errors;
    } catch (Exception e) {
      return handleError(e);
    }
  }
}

Questi necessita del seguente file xsql:

 
<?xml version="1.0" encoding="UTF-8" ?>
 
<SqlClass name="ValidationExample2Data" package="org.openbravo.buildvalidation">
  <SqlMethod name="queryBPartners" type="preparedStatement" return="string">
      <SqlMethodComment></SqlMethodComment>
      <Sql><![CDATA[
         SELECT COUNT(*) FROM C_Bpartner WHERE name IS NULL
          ]]>
      </Sql>
  </SqlMethod>
</SqlClass>

I file sorgenti della classe devono essere inseriti nella cartella del modulo : src-util/buildvalidation/src

La cartella non esiste se è la vostra prima validazione, in tal caso va creata .

Compilare la validazione di compilazione

Per compilare la validazione di compilazione, bisogna eseguire il seguente comando :

 
ant compile.buildvalidation -Dmodule=javapackageofmodule

Se si vogliono compilare le validazioni del Core di Openbravo, la proprietà del modulo deve essere settata a "org.openbravo"

Questa task compilerà le classi Java, e li copia nella corretta cartella "build" nel modulo, o nella src-util/buildvalidation del Core.

Eseguire la validazione di compilazione

Le validazioni saranno automaticamente eseguite nel task update.database , o in update.database.mod se il modulo viene applicato. E' molto importante notare che le validazioni non saranno compilati in questo task, hanno bisogno di essere state compilate precedentemente per essere eseguite.

Un altro punto importante da notare è che le validazioni di compilazioni saranno eseguite in ogni versione del modulo, o Core, in cui sono presenti (questo significa, ad esempio, che se uno script esiste in Openbravo Core MP15 e successive, verrà eseguito quando ci si aggiorna alla MP15 o succesive, e verrà eseguito ancora quando ci si aggiorna a una versione successiva). Lo sviluppatore ha bisogno di tenere in conto di questo aspetto (è consigliabile non progettare scripts che siano dipendenti dalla versione, dovrebbero essere sempre progettati come generici).

Il task package.module includerà automaticamente i file binari compilati nel file .obx , considerato che siano compilate le validazioni prima di fare il packaging del modulo.

Se aggiungi uno validazione al Core di Openbravo, ricordati che devi includere le classi binarie (contenute in src-util/modulescript/build/classes/) al repository come ogni altro file sorgente. Senza questo passo, non verranno eseguite (perchè le classi non sono compilate di default nel processo di build , esse vengono eseguite solo se ci sono i files binari ).

Scripts di Modulo

Uno script di modulo è una task che viene eseguita quando un modulo viene applicato in un database. Questa task ha il compito di fare operazioni che devono essere fatte nel database, e non possono essere fatte in un modo diverso.

Concettualmente, essi sono estremamente simili a Convalide di Compilazione, e le fasi principali interessate per creare uno Script di Modulo sono praticamente identiche, quindi è consigliabile leggere la sezione precedente prima di questa. I principali punti di uno script di modulo sono i seguenti:

• Mentre le convalide di compilazione vengono eseguite all'inizio del update.database, gli script di modulo vengono eseguite nel bel mezzo del processo, quando lo chiavi esterne e trigger del database sono disattivati

• Come con con le convalide, gli script del modulo verranno eseguiti ogni volta che viene chiamato un update.database o update.database.mod per quel modulo particolare . Questo significa chelo script deve essere costruito in modo tale che può essere eseguito più volte senza problemi, e questa è una considerazione molto importante che lo sviluppatore deve prendere in considerazione.

• Lo script del modulo non deve mai fallire. Se fallisce, la compilazione verrà fermata, ma visto che è già stato avviato, il sistema sarà in uno stato inconsistente (per esempio, tutte le chiavi esterne e trigger non saranno attive ). Lo sviluppatore deve evitare ciò a tutti i costi, se possibile.

Introduzione all'implementazione di scripts di modulo

Come per le convalide di compilazione, uno script di modulo è una classe Java che estende la classe astratta org.openbravo.modulescript.ModuleScript , e implementa il metodo execute(). Questo metodo di esecuzione verrà chiamato dal task update.database. Questo metodo comprenderà la logica dello script del modulo, tutte le operazioni saranno eseguite.

Scrivere lo script di modulo

Qui vediamo uno script di modulo molto semplice , che imposta solo il valore di una colonna a un default nel caso in cui il valore della colonna è null:

 
 
public class ModuleScriptExample extends ModuleScript {
 
  public void execute() {
    try {
      ConnectionProvider cp = getConnectionProvider();
      PreparedStatement ps = cp
          .getPreparedStatement("UPDATE mytable SET mycolumn=0 WHERE mycolumn IS NULL");
      ps.executeUpdate();
    } catch (Exception e) {
      handleError(e);
    }
  }
}

I due principali punti importanti che sono necessari da prendere in considerazione quando si costruisce lo script sono :

• Lo script non deve mai fallire. Il fallimento lascerà l'utente in una situazione molto ostile (con la compilazione fermata a metà), e deve essere evitato a tutti i costi. In questo caso, questo script non fallirà a meno che la tabella non esiste.
• Lo script deve essere progettato in modo che possa essere eseguito un numero indefinito di volte. Questo script, per esempio, può essere eseguito più volte senza problemi (la prima volta imposterà tutte le righe che hanno un valore nullo, e dopo che, solo le righe nuove che sono state inserite prima saranno modificate, ma le righe precedentemente modificato non saranno modificate di nuovo a meno che non hanno di nuovo il valore null presumibilmente sbagliato ).

I file sorgenti della classe devono essere inseriti nella cartella del modulo : src-util/modulescript/src La cartella non esiste se è la vostra prima validazione, in tal caso va creata .

Compiling the module script

Per compilare lo script di modulo, bisogna eseguire il comando:

 
ant compile.modulescript -Dmodule=javapackageofmodule

Se si vuole compilare gli scripts del Core di Openbravo, la proprietà del modulo deve essere impostata a "org.openbravo"

Questa task compilerà le classi Java, e le copierà nella corretta cartella "build" del modulo, o nella src-util/modulescript del Core.

Eseguire lo script di modulo

Gli scripts di modulo saranno automaticamente eseguiti nel task update.database , o in update.database.mod se il modulo viene applicato. E' molto importante notare che gli scripts del modulo non saranno compilati in questo task, necessitano di essere compilati prima di essere eseguiti.

Un altro importante punto da notare è che gli scripts del modulo funzionano come validazioni di compilazione per quanto riguarda i criteri di esecuzione; ossia, verranno eseguiti in ogni versione del modulo, o Core, in cui sono presenti (questo significa , ad esempio, che se uno script esiste in Openbravo Core MP15 e successive, verrà eseguito quando ci si aggiorna alla MP15 o succesive, e verrà eseguito ancora quando ci si aggiorna a una versione successiva). Lo sviluppatore ha bisogno di tenere in conto di questo aspetto (è consigliabile non progettare scripts che siano dipendenti dalla versione, dovrebbero essere sempre progettati come generici).

Inoltre gli scripts dovrebbero anche essere progettati per produrre lo stesso risultato se eseguiti più volte, perchè verranno eseguite ogni volta che il sistema viene ri-compilato, o il modulo viene modificato.

Il task package.module includerà automaticamente i binari compilati nel file .obx , si preoccupa che compiliate gli script di modulo prima di fare il packaging del modulo.

Se aggiungi uno script di modulo al Core di Openbravo, ricordati che devi includere le classi binarie (contenute in src-util/modulescript/build/classes/) al repository come ogni altro file sorgente. Senza questo passo, non verranno eseguite (perchè le classi non sono compilate di default nel processo di build , esse vengono eseguite solo se ci sono i files binari ).