Un caso d’uso
Come abbiamo visto, gli utenti di un server Notes, sono contenuti all’interno di un database particolare chiamato names.nsf. Per tale ragione, la creazione di un nuovo utente, non è altro che l’aggiunta di un nuovo documento a names.nsf.
Per rendere maggiormente didattica tale aggiunta, ho voluto analizzare un reale caso d’uso che potrebbe capitare in qualsiasi applicazione Web.
Il problema che mi sono posto è stato quello di poter indicare, in una form HTML, un nome e una password e alla conferma aggiornare sia il database utenti che l’access control list del database stesso.
Per fare questo ho creato una form per l’inserimento dei parametri, la quale verrà controllata nella fase di submit da parte di un agente, che si occuperà di fare tutto il lavoro.

Mettiamoci al lavoro
A questo punto, una volta focalizzato il nostro obiettivo, non ci resta che aprire Lotus Domino Designer, o per chi ha la versione 4 il client Notes, e creare la maschera sulla quale andremo a lavorare. Il nome di tale maschera sarà nuovoutente. All’interno di tale oggetto andremo poi ad inserire due campi che utilizzeremo per la successiva elaborazione. Tali campi saranno: nome e password.
Per completare la maschera non ci serve altro che definire un Hotspot Button, tramite il quale ordinare l’operazione di submit, che abbiamo gia analizzato nel corso di una delle puntate precedenti. Tale operazione si può effettuare con l’utilizzo della seguente formula:

@Command([FileSave]);
@Command([FileCloseWindow])

Per poter poi gestire i dati salvati tramite un agente, dobbiamo indicare a Lotus Domino quale agente deve essere utilizzato, tramite la valorizzazione dell’elemento WebQuerySave del form corrente:

@Command([ToolsRunMacro]; "salvautente")

In questo caso è stato indicato che il nome dell’agente da utilizzare è salvautente.
Dopo aver salvato la maschera, se non vi sono stati errori, possiamo andare a sviluppare il codice dell’agente salvautente. Quello che dovremo fare, a grandi linee, è aprire l’address book, aggiungere l’utente, aprire l’access control list del database corrente ed aggiungere anche qui il nuovo utente.
 

Scriviamo l’agente di submit
Come tutti gli agenti, possiamo sfruttare l’impostazione che ci propone Lotus Domino Designer, andando ad aggiungere quello che ci interessa valorizzare.
Se provate a creare un nuovo agente, l’ambiente di disegno vi proporrà una struttura simile alla seguente:

import lotus.domino.*;
public class JavaAgent extends AgentBase {
   public void NotesMain() {
      try {
         Session session = getSession();
         AgentContext agentContext = session.getAgentContext();
         // (Your code goes here) 
         System.out.println("ok");
      } catch(Exception e) {
         e.printStackTrace();
      }
   }
}

Se siete un po’ ansiosi e volete subito verificare il corretto funzionamento di questa prima parte di codice, vi consiglio di aggiungere, come nell’esempio, la riga System.out.println(“ok”) e verificare, provando a salvare i valori nella form, che nella console del server appaia la scritta “ok”.
Se tutto dovesse andare nel modo corretto, siamo pronti per passare alla fase successiva.
 

Il codice Java
La prima cosa da fare è quella di andare ad aprire l’address book.
Per fare questo dobbiamo, prima di tutto, sapere dove si trova tale archivio. In questo caso siamo però abbastanza fortunati, dato che nella quasi totalità dei casi, lo troveremo semplicemente nella directory data di Notes.
Per aprirlo non utilizzeremo quindi percorsi particolari, ma basterà indicarne il nome. Per fare questo dovremo chiedere alla sessione corrente, che abbiamo appena valorizzato nella variabile session, l’apertura del database tramite il metodo getDatabase. Ecco di seguito la riga che ci permette di fare questo:

Database names = session.getDatabase( "", "names.nsf" );

Come potete notare, il metodo getDatabase, riceve due parametri. Il primo, che ho omesso di indicare, è il nome del server sul quale aprire il file. Non indicandolo verrà automaticamente utilizzato il server corrente. Questo particolare ci permette di capire che, se l’utente con quale viene salvato l’agente ha diritto di lettura e scrittura anche in un server diverso dal corrente, potremo effettuare le stesse operazioni anche su un server remoto.
Ora che siamo riusciti ad aprire l’address book, non ci resta che iniziare a prendere i valori che sono stati immessi da browser nella form, utilizzando il metodo getItemValueString applicato al documento corrente, fornito dal metodo getDocumentContext dell’oggetto agentContext:

Document doc = agentContext.getDocumentContext();
String cNome = doc.getItemValueString("Nome");
String cPwd = doc.getItemValueString("password");

Come potete notare, il procedimento è molto più lungo da spiegare che da sviluppare, in quanto il suo utilizzo si riduce ad una riga di codice.
Fino a qui non ci sono stati grossi problemi implementativi, dato che, quello che viene immesso lato browser è esattamente quello che viene inserito nel database.
Esiste però una particolarità di cui dobbiamo tener conto, rappresentata dal campo password.
Tale campo deve essere salvato in modo criptato nel documento persona, quindi non è possibile un suo utilizzo diretto.
 

Concettualmente l’operazione da fare è semplice: si tratta di applicare la formula @password al valore di cPwd. Il problema è che, nell’interfaccia Java di Notes, tale funzione non esiste. Non vi è modo di utilizzarla, se non con un piccolo trucco, che è quello di richiamare @password, tramite il metodo di valutazione delle formule, evaluate, che la classe Session ci mette a disposizione.
Ultima particolarità di questo passaggio è data dal fatto che, il ritorno del metodo evaluate non è un valore String, come sarebbe giusto in questo caso specifico, ma un Vector di elementi, sul quale dobbiamo applicare le giuste trasformazioni per avere i valori che ci interessano.
Nel caso della formula @password, tale Vector, ha un solo elemento di tipo String.
Per tale ragione siamo costretti a scrivere questo codice per trasformare il valore digitato in valore criptato:

cPwd = "@PASSWORD('" +cPwd +"')";
Vector v = session.evaluate( cPwd );
cPwd = (String)v.firstElement();

Ora che abbiamo tutti gli elementi che ci servono, non ci resta che creare un nuovo documento all’interno del database names, valorizzandone i giusti campi e salvando il tutto.
La creazione del documento è attuabile tramite il metodo createDocument della classe Database:

Document person = names.createDocument();

Per la creazione dei campi invece si può sfruttare un semplice concetto: se valorizziamo un campo che non esiste all’interno del documento che abbiamo appena creato, Notes provvederà a crearlo.
Questo vuol dire che, un semplice richiamo al metodo appendItemValue di un campo che non esiste, ci permetterà la sua creazione.
I campi da creare in questo nuovo documento sono pertanto i seguenti:

FullName = Il nome del nuovo utente inserito
LastName = contiene lo stesso valore di FullName
Form = impostato a “Person”
Type = impostato a “Person”
HTTPPassword = la password criptata

Questi campi sono fondamentali per fare in modo che il nuovo documento venga correttamente indicizzato dalle viste di ricerca utenti. Traducendo in codice queste assegnazioni otterremo così il seguente listato:

person.appendItemValue("Form", "Person");
person.appendItemValue("Type", "Person");
person.appendItemValue("Fullname", cNome);
person.appendItemValue("LastName", cNome);
person.appendItemValue("HTTPPassword", cPwd);

Una volta creato il documento in memoria, basterà forzarne un salvataggio per poter avere finalmente il dato disponibile:

person.save(true,false);

Se tutto è andato alla perfezione, tramite Domino Administrator, sarà possibile vedere che, all’interno della lista degli utenti è apparso anche il nome dell’utente che abbiamo appena inserito con la pagina HTML.
Un’ultima osservazione deve essere fatta sul numero di campi disponibili nel documento person.
Andando a confrontare i campi del documento appena creato, con quelli di uno similare già presenti nel database, noterete una discordanza fra il numero di campi disponibili.
Tale differenza non è grave, dato che la maschera di inserimento standard di Notes crea tutta una serie di parametri aggiuntivi opzionali.
Se dovesse però porsi l’esigenza di modificare qualche caratteristica dell’utente appena inserito, sarà sempre possibile modificare il documento con i normali meccanismi Notes.
 

Modifica dell’ACL di un database
Il primo passo per una corretta creazione di nuovi utenti lato WEB è stato fatto. A questo punto possiamo vedere come, allo stesso modo, possiamo modificare l’access control list, di un database.
In questo caso abbiamo a disposizione una serie di classi che, in maniera molto semplice, permettono la gestione di tale aspetto dei database Notes.
La classe principale è sicuramente ACL, che permette di avere una completa gestione della lista degli utenti abilitati verso un certo database.
Con tale classe è possibile avere l’elenco degli utenti, aggiungerne uno nuovo o semplicemente rimuoverlo dalla lista di quelli attivi.
Insieme a tale classe è presente anche la classe che gestisce le proprietà del singolo utente. Tale classe è ACLEntry, e sarà la classe che andremo ad utilizzare per modificare le caratteristiche dell’utente.
Vediamo ora come possiamo utilizzare tali classi per personalizzare il nostro database di test.
Sicuramente la prima cosa da fare è quella di chiedere alla classe agentContext qual è il database corrente. Quest’operazione si effettua con una semplice riga di codice:

Database db = agentContext.getCurrentDatabase();

Una volta che abbiamo valorizzato un oggetto Database con il giusto valore¸ tramite il metodo getACL(), potremo facilmente accedere ad un oggetto in grado di manipolare la lista degli utenti. A questo punto, tramite l’utilizzo del metodo createACLEntry, potremo creare un nuovo utente e con un successivo salvataggio potremo aggiungere tale utente all’ACL:

// Aggiornamento ACL
Database db = agentContext.getCurrentDatabase();
ACL acl = db.getACL();
ACLEntry addACL = acl.createACLEntry( “user”, ACL.LEVEL_MANAGER);
acl.save();

Per verificare se l’aggiunta è stata fatta nel modo corretto, possiamo controllare l’effetto della nostra modifica, sia dall’ambiente di disegno, passando dalle caratteristiche del database, e sia utilizzando l’oggetto acl, scorrendone i valori e presentandoli a video:

// Visualizzo l'ACL
ACLEntry acle = acl.getFirstEntry();
do {
   System.out.println(acle.getName());
} while ((acle = acl.getNextEntry(acle)) != null);

il raggiungimento del primo elemento null indicherà la fine della lista degli utenti.
 

Test di accesso
Ora che l’utente è stato creato ed aggiunto a quelli che possono gestire il database, non ci resta che controllare, tramite un browser, se è possibile accedere ai dati, identificandoci con l’utente e password appena inseriti.
Per forzare l’identificazione dovremo però impostare a No Access l’accesso di default sul database. In questo modo forzeremo Notes a chiedere l’autentificazione dell’utente.
Se tutto è stato scritto nel modo corretto accederete ai dati del database e a tutte le sue risorse.
 
 
 

Conclusioni
A questo punto dovreste essere completamente padroni del sistema di autentificazione utenti di Notes. In realtà esistono delle tecniche leggermente più sofisticate per gestire in modo più elegante e meno intrusivo gli utenti, ma il loro utilizzo non si discosta molto da questi concetti.
Sommando così tutte le tecniche apprese nelle prime puntate di questo corso si dovreste essere in grado di affrontare con tranquillità la creazione di applicazioni di medie dimensioni.
Ovviamente, per poter sfruttare al meglio Notes, la cosa migliore da fare, è quella di studiare in modo approfondito, tutti i metodi delle classi disponibili. Fortunatamente però l’help fornito da Lotus è molto completo e dettagliato, corredato da numerosi esempi esplicativi, di sicuro supporto per ogni programmatore Notes.
A questo punto il corso subisce una piccola pausa, per dare spazio a due puntate nelle quali andremo ad illustrare come realizzare un progetto Internet di presentazione di documenti.
In questo modo potremo mettere in pratica i concetti utilizzati su un caso reale, vedendo com’è possibile pianificare, dallo sviluppo al rilascio, una semplice applicazione, curando anche i problemi di sicurezza nei quali potremmo incorrere.
 

Bibliografia
[1] http://www.lotus.com sito Internet di riferimento per i prodotti Lotus
[2] http://www.notes.net sito ufficiale di Lotus Domino. Da questo sito è possibile scaricare tutti gli aggiornamenti di Domino, dalla versione 4.0 all’ultimissima versione disponibile.
[3] http://www.mokabyte.it, sito contenente tutte le puntate di questo corso.
[4] http://www.infomedia.it/artic/Baccan, sito contenente alcuni articoli di approfondimento degli argomenti trattati.

Matteo Baccan 
Matteo Baccan è uno specialista di progettazione e sviluppo in C++, Java e Lotus Notes. Attualmente si occupa dello studio di tecniche avanzate di programmazione in ambito Internet/Intranet tramite Lotus Notes e Java, presso Integra Italia. Si possono consultare alcune sue pubblicazioni presso http://www.infomedia.it/artic/Baccan. Può essere contattato tramite e-mail all'indirizzo baccan@infomedia.it