Mail merge. Progetto valido per gli appelli di settembre 2008 e gennaio 2009

Transcript

1 Mail merge Progetto valido per gli appelli di settembre 2008 e gennaio Descrizione Con il termine mail merge si intende tipicamente una funzionalità software che permetta la produzione di più documenti a partire da un modello e da una sorgente di dati. Ad esempio questa tecnica può essere utilizzata per produrre lettere personalizzate partendo da un testo già predisposto e da un database di indirizzi. Questo procedimento viene tipicamente effettuato utilizzando un elaboratore di testi, predisponendo come modello un documento che conterrà sia testo prefissato (che comparirà in tutti i documenti prodotti), sia nomi di variabili che verranno via via sostituite dalle informazioni lette dalla sorgente di dati. Quest ultima è invece tipicamente costituita da un foglio elettronico oppure da una base di dati, dove ogni riga del foglio elettronico o ogni record restituito dalla base di dati rappresentano dei particolari valori da sostituire alle variabili nel modello. L esecuzione della procedura di mail merge estrae tutte le informazioni dalla sorgente di dati, sostituendole ogni volta alle occorrenze delle variabili nel modello di documento e producendo un nuovo documento, che verrà poi utilizzato in qualche modo (e.g., stampato, inviato per posta elettronica e così via). Il progetto consiste nel realizzare una serie di classi JAVA che permettano di implementare una semplice procedura di mail merge in grado di generare diversi tipi di documenti a partire da una sorgente di dati comune. 2 I modelli di documento Dovrà essere possibile fare riferimento ai seguenti tipi di documento: Documento, che indica un generico documento. Ogni documento contiene il nome del suo autore e la data di creazione (Attenzione: in tutto il progetto è richiesto che le date siano indicate nel formato "gg/mm/aaaa hh:mm:ss" senza i doppi apici, ovviamente dove gg e MM indicano il numero del giorno all interno del mese e il numero corrispondente al mese, entrambi a due cifre, così come aaaa indica il numero dell anno, a quattro cifre. Analogamente, hh indica l ora a due cifre (nel formato a 24 ore, senza l indicazione AM/PM), così come mm e ss indicano rispettivamente i minuti e i secondi indicati usando due cifre. , che indica un generico messaggio di posta elettronica. Ogni messaggio contiene, oltre alle informazioni tipiche di un generico documento, anche l indirizzo di posta elettronica del destinatario (non gestiremo per semplicità messaggi inviati a più destinatari), l oggetto e il testo del messaggio (notate che quest ultima informazione, a differenza delle precedenti, è rappresentata da una stringa che può contenere più righe). Report, che indica un generico rapporto. Ogni rapporto contiene, oltre alle informazioni tipiche di un generico documento, anche l indirizzo di posta elettronica del suo autore (anche in questo caso considereremo solo rapporti scritti da un unico autore), il titolo e una successione di uno o più paragrafi, ognuno composto da un titolo e da un contenuto (dove titoli e contenuti possono occupare più righe). 3 L inserimento di informazioni variabili In ogni elemento che costituisce uno qualsiasi dei documenti descritti nel paragrafo precedente, a eccezione delle date, è possibile inserire uno o più nomi di variabili, da sostituire successivamente con informazioni personalizzate tramite una procedura di mail merge. In tutti i casi, i nomi delle variabili sono delimitati dai caratteri < e > e possono contenere un numero qualunque di caratteri qualsiasi, compresi i delimitatori e lo spazio (più avanti verrà indicato come gestire nomi di variabili che contengano i delimitatori). Per esempio, la stringa 1

2 Gentile <titolo> <primo nome> <secondo nome> <cognome>, siamo lieti di informarla che, avendo lei effettuato <acquisti\>100> acquisti nel nostro supermercato, ognuno per un totale superiore a 100 Euro, potrà acquistare in anteprima il nuovo modello del frullatore KRAZZ al prezzo simbolico di 10 Euro. <saluto>, La direzione dei supermercati TRIPP titolo primo nome secondo nome cognome acquisti>100 saluto Figura 1: Un possibile contenuto del modello per il testo di un messaggio di posta elettronica. Figura 2: Un possibile file dei nomi per il modello descritto in Figura 1. Dott. <primo nome> <secondo nome> <cognome> può essere utilizzata per indicare il generico autore di un documento, in modo che il titolo Dott. compaia in tutti i documenti generati, mentre <primo nome>, <secondo nome> e <cognome> vengano di volta in volta sostituiti con delle informazioni reperite da una fonte di dati (vedi oltre). A titolo di esempio, in Figura 1 è riportato un possibile valore per il testo di un messaggio di posta elettronica. L utilizzo di nomi di variabili, come suggerito dalla Figura 1, che contengono una o più occorrenze dei delimitatori < e > andrà gestita sfruttando un meccanismo simile alle sequenze di escape utilizzato per descrivere i caratteri in Java: la sequenza \> dovrà essere automaticamente tradotta nel carattere >; la sequenza \< dovrà essere automaticamente tradotta nel carattere <; la sequenza \\ dovrà essere automaticamente tradotta nel carattere \; 4 La fonte di dati Per definire una fonte di dati sarà necessario fare riferimento a due file di testo, contenenti rispettivamente i nomi delle variabili e il contenuto delle stesse per ogni documento che si vuole produrre. 4.1 Il file dei nomi Il file contenente i nomi delle variabili, a cui d ora in avanti ci riferiremo chiamandolo file dei nomi, sarà un file di testo contenente su ogni riga il nome di una delle variabili utilizzate nella procedura di mail merge, senza i corrispondenti caratteri delimitatori. Ciò permette di non dover utilizzare, all interno di questo file, le sequenze di escape. A titolo di esempio, in Figura 2 è riportato il contenuto di un possibile file dei nomi per le variabili utilizzate nel modello visualizzato in Figura Il file dei valori Una volta fissate le variabili utilizzando il formato descritto nel paragrafo precedente, è necessario utilizzare un ulteriore file che associ loro dei valori. Tale file, che chiameremo file dei valori, conterrà una riga per ogni documento che si vuole produrre, e ognuna di queste righe conterrà una serie di valori separati da virgole. In particolare, ogni riga conterrà esattamente tanti valori quante sono le righe (e quindi le variabili) all interno del file descritto nel paragrafo precedente. A titolo di esempio, in Figura 3 è visualizzato un possibile file dei valori per le variabili definite dal file 2

3 Prof.\, Dr.,Marco,,Rossi,30,Distinti saluti,fabio,ermanno,azzurri,35,cordialmente Dott.,Giulio,Sabino,Neri,50,Distintamente Figura 3: Un possibile contenuto del file dei i valori per le variabili relative alla Figura 2. dei nomi illustrato in Figura 2. Va notato come non sia necessario attribuire in tutte le righe del file dei nomi un valore a una data variabile: indicare due virgole senza alcuno spazio tra loro ha infatti l effetto di assegnare a una variabile l equivalente della stringa vuota. All interno di questo file, come esemplificato in Figura 3, bisognerà sfruttare le sequenze di escape in modo da permettere di utilizzare valori che contengano una o più virgole, pertanto la sequenza \, andrà convertita in un singolo carattere di virgola, così come la sequenza \\ andrà convertita in un carattere di backslash. 5 Elaborazione di documenti singoli e di gruppi di documenti La procedura di mail merge, nella sua versione base, funzionerà nel modo seguente: creerà un documento i cui contenuti faranno riferimento a una o più variabili; leggerà un file dei nomi (in particolare, questo file dovrà contenere i nomi di tutte le variabili che occorrono nella descrizione del documento, più eventuali altri nomi, pena l emissione di un opportuno errore); leggerà un file dei valori, e per ogni riga di questo file: leggerà i valori contenuti nella riga e separati da virgola, assegnandoli alle variabili (emettendo errore nel caso il numero di valori non coincida con il numero di variabili) creerà un nuovo documento nei cui contenuti tutte le occorrenze di una variabile saranno rimpiazzate dal valore corrispondente (emettendo errore nel caso una o più variabili non compaiano nel file dei nomi). Per complicarvi la vita, è necessario prevedere anche la produzione di gruppi di diversi documenti, a fronte di un unico file dei nomi e di un unico file dei valori. Sarà pertanto presente un ulteriore file, che chiameremo file dei modelli, che descriverà un gruppo di modelli di documento, ognuno descritto come indicato nei seguenti paragrafi. 5.1 Il formato per i documenti I generici documenti (quindi i documenti che non sono né messaggi di posta elettronica, né rapporti) sono descritti all interno del file dei modelli tramite la seguente sintassi. La codifica inizia tramite una riga il cui contenuto è BEGIN Document. La riga seguente contiene il nome dell autore. La riga seguente contiene la data di creazione del documento. La codifica termina tramite una riga il cui contenuto è END Document. 5.2 Il formato per i messaggi di posta elettronica I messaggi di posta elettronica sono descritti all interno dei file dei modelli tramite la seguente sintassi. La codifica inizia tramite una riga il cui contenuto è BEGIN . La riga seguente contiene il nome dell autore. La riga seguente contiene la data di creazione del messaggio. La riga seguente contiene l indirizzo del destinatario. 3

4 La riga seguente contiene l oggetto del messaggio. Le righe seguenti, fino a che non si trovano due righe vuote, contengono il testo del messaggio. La codifica termina tramite una riga il cui contenuto è END e che segue le due righe vuote indicate al punto precedente. 5.3 Il formato per i rapporti I rapporti sono descritti all interno del file dei modelli tramite la seguente sintassi. La codifica inizia tramite una riga il cui contenuto è BEGIN Report. La riga seguente contiene il nome dell autore. La riga seguente contiene la data di creazione del messaggio. La riga seguente contiene l indirizzo di posta elettronica dell autore. Le righe seguenti, fino a che non si trovano due righe vuote, contengono il titolo del messaggio. Le righe seguenti (una volta scartate le due righe vuote descritte al punto precedente) contengono il titolo di un paragrafo (il quale potrà quindi essere composto da più righe). Le righe seguenti (sempre una volta scartate le due righe vuote del punto precedente) contengono il testo di un paragrafo. Va notato come all interno del testo si possa inserire una riga vuota per separare due capoversi. I due punti precedenti possono essere ripetuti più volte (è comunque necessario che una loro occorrenza sia sempre presente). La codifica termina tramite una riga il cui contenuto è END Report e che segue le due righe vuote indicate al punto precedente. 6 Generazione dei documenti I documenti prodotti dalla procedura di mail merge, una volta generati, dovranno poter essere: visualizzati sullo schermo in sequenza, marcando l inizio di ogni documento tramite una linea tracciata stampando una serie di 40 trattini (dove per trattino si intende il carattere - ), senza aggiungere righe vuote prima o dopo, oppure memorizzati in una directory, che andrà creata nel caso non esista, salvando ogni documento in un file distinto e assegnando per nome a ogni file un numero progressivo (iniziando da 0) preceduto dai caratteri D, E e R rispettivamente nei casi in cui si stia generando un documento generico, un messaggio di posta elettronica oppure un rapporto. Va notato come il contatore che memorizza il numero progressivo sia unico e comune a tutti i documenti, quindi se per esempio si elaborano un messaggio di posta elettronica e un rapporto, i nomi dei file saranno, rispettivamente, E0 e R1. Per i dettagli sulla visualizzazione dei vari tipi di documento si rimanda ai paragrafi seguenti. 6.1 Visualizzazione dei documenti I generici documenti (quindi i documenti che non sono né messaggi di posta elettronica, né rapporti) sono visualizzati nel modo seguente: la prima riga contiene il nome dell autore; la seconda riga contiene la data di creazione. 4

5 6.2 Visualizzazione dei messaggi di posta elettronica I messaggi di posta elettronica sono visualizzati nel modo seguente: la prima riga contiene la stringa "Messaggio da:", seguita da uno spazio e dal nome dell autore del messaggio; la seconda riga contiene la stringa "Inviato il", seguita da uno spazio e dalla data di creazione; la terza riga contiene la stringa "a:", seguita da uno spazio e dall indirizzo del destinatario; la quarta riga contiene la stringa "Oggetto:", seguita da uno spazio e dall oggetto; le righe seguenti contengono il testo del messaggio. 6.3 Visualizzazione dei rapporti I rapporti sono visualizzati nel modo seguente: inizialmente viene visualizzato il titolo del rapporto, che può comparire su più righe: i suoi caratteri devono essere automaticamente convertiti in maiuscolo, aggiungendo uno spazio dopo ogni carattere; successivamente viene visualizzata una riga vuota; nella riga successiva viene visualizzato il nome dell autore, seguito da uno spazio e dal suo indirizzo di posta elettronica racchiuso tra parentesi tonde; la riga successiva contiene la data di creazione del documento; ogni paragrafo viene visualizzato nel modo seguente: inizialmente viene visualizzata una riga vuota; le righe successive contengono il titolo del paragrafo, i cui caratteri sono automaticamente convertiti in maiuscolo; successivamente viene visualizzata una riga vuota; le righe successive visualizzano il contenuto del paragrafo. 7 Dettagli implementativi È lasciata ampia libertà sulla realizzazione del progetto. È in ogni caso obbligatorio: definire un eccezione WrongFormatException, da lanciare ogni volta che non vengono rispettati i formati descritti in questo documento e quando vengono lanciate eccezioni legate a operazioni di input/output; utilizzare un interfaccia all interno del progetto, nel punto ritenuto più opportuno; definire una classe per ogni tipo di documento (i nomi Document, e Report sono delle buone scelte per i nomi di queste classi); inserire in ognuna delle classi descritte al punto precedente un costruttore che permetta di creare un istanza specificando come argomenti tutti gli elementi che compongono un documento (anche se per ragioni di efficienza nel codice potrà essere sensato invocare tali costruttori specificando null al posto di uno o più argomenti); definire una classe DocumentProcessor che venga istanziata specificando: l istanza di un generico documento, di un messaggio di posta elettronica o di un rapporto, il nome di un file dei nomi, e il nome di un file dei valori 5

6 e che contenga l implementazione di un metodo process() che accetta come argomento una stringa. Tale metodo, che non restituisce valori, deve eseguire l operazione di mail merge visualizzando i documenti prodotti se l argomento è null, e salvarli invece nella directory il cui nome è contenuto nella stringa passata come argomento in caso contrario, seguendo le convenzioni descritte nel Paragrafo 6; definire una classe BatchProcessor che venga istanziata specificando nell ordine il nome di un file dei modelli, di un file dei nomi e di un file dei valori, e che contenga l implementazione di un metodo process, con la stessa segnatura e la stessa semantica del metodo omonimo descritto nel punto precedente, con la differenza che il procedimento di mail merge verrà applicato a tutti i documenti descritti nel file dei modelli; sia l invocazione del costruttore, sia quella di process dovranno poter lanciare un eccezione della classe WrongFormatException; rispettare alla lettera il formato per i file di input e di output e per le visualizzazioni a schermo. A parte quanto espressamente richiesto, è lasciata piena libertà sull implementazione delle singole classi e sull eventuale introduzione di classi aggiuntive, a patto di seguire correttamente le regole del paradigma di programmazione orientata agli oggetti e i principi di buona programmazione. Si suggerisce di porre particolare attenzione alla scelta dei modificatori relativi a variabili d istanza e metodi, alla creazione di metodi di accesso alle variabili di istanza quando questi siano ritenuti necessari, alla definizione di classi e metodi astratti e di metodi o di variabili statici dove questi risultino opportuni, nonché alla dichiarazione e alla gestione delle eccezioni che possono venire lanciate dai vari metodi e alle relazioni di ereditarietà tra le varie classi. Si ricorda altresì di rispettare alla lettera il formato descritto per interpretare i contenuti dei file e dei messaggi di output. Non è richiesto l utilizzo di particolari modalità grafiche di visualizzazione: è sufficiente una qualunque modalità di output basata sull uso dei caratteri. È invece espressamente richiesto di non utilizzare package non standard di Java (si possono quindi utilizzare java.util, java.io e così via, ma non prog.io). I progetti che useranno pacchetti non standard non saranno corretti. 8 Suggerimenti Alcuni degli aspetti del progetto (per esempio la gestione e la formattazione delle date o l uso di array di cui non si conosce a priori il numero di elementi) sono già gestiti da particolari classi dei package standard. Non è quindi necessario reimplementare da zero queste funzionalità: basterà cercare all interno delle API. Utilizzate in modo sensato l ereditarietà per implementare le classi che descrivono i vari tipi di documenti, e cercate di mantenere tutte le operazioni fondamentali, come il caricamento dei file dei nomi e dei valori, così come la sostituzione delle variabili con i contenuti corrispondenti, nella classe meno specifica. Nonostante l apparente complessità, è possibile implementare il progetto in circa 400 linee di codice. Sulla pagina web del corso di laboratorio sono pubblicati un file dei modelli, un file dei nomi e un file dei valori che è possibile utilizzare per verificare il funzionamento del programma (chiaramente, la vostra soluzione dovrà elaborare correttamente qualsiasi file dei modelli, dei nomi e dei valori purché sintatticamente corretti). 9 Modalità di consegna Il progetto può essere svolto al massimo da tre persone che intendono sostenere l intero esame di Fondamenti di Architettura e Programmazione - Laboratorio di Programmazione negli appelli di Febbraio o Aprile 2008, e deve essere consegnato entro la mezzanotte tra lunedì 15 e martedì 16 settembre 2008, tramite il sito di sottoposizione pubblicato all indirizzo Per sottomettere un progetto è necessario che tutti i componenti del gruppo si registrino; successivamente un componente potrà creare un gruppo a cui affiliare i rimanenti componenti. La sottoposizione è fatta a nome del gruppo e vale per tutti i suoi componenti. Va sottolineato che delle sottoposizioni successive cancellano quelle fatte in precedenza, nonché che il sito di sottoposizione effettua dei controlli sulla validità del codice consegnato: pertanto, è caldamente consigliato effettuare sottoposizioni parziali man mano che vengono realizzati dei prototipi. 6

7 Dovranno essere consegnati tutti i sorgenti Java che permettano al programma di essere eseguito correttamente, unitamente alla documentazione descritta nel capoverso che segue, compressi in un archivio di tipo ZIP che estragga i file nella directory in cui si trova l archivio stesso, senza creare una nuova directory. È inoltre richiesto di consegnare, entro mercoledì 16 settembre 2008, una copia cartacea della stampa del codice sorgente prodotto nella casella di posta (fisica, non elettronica) del docente di riferimento, situata all ingresso del DSI/DICo, indicando chiaramente nome, cognome e numero di matricola di tutti i componenti del gruppo, nonché il turno e il docente di riferimento. A questa copia cartacea dovrà essere allegato un breve documento in cui saranno illustrate le principali scelte implementative e le strategie utilizzate per svolgere il progetto. Questo documento dovrà essere incluso nell archivio ZIP inviato tramite il sito di sottoposizione, memorizzandolo in un formato non proprietario (sono accettabili per esempio pdf, rtf e txt). Nella copia cartacea indicare anche in quali appelli i singoli componenti del gruppo intendono discutere il progetto. Le sottoposizioni che non seguono queste specifiche e i programmi che non risultano compilabili correttamente non verranno valutati. È richiesto di indicare chiaramente all inizio di tutti i documenti consegnati nome, cognome e matricola dei vari componenti del gruppo. 10 Valutazione La discussione con i singoli studenti verterà sulle modalità di implementazione adottate e sulla padronanza di alcuni dei concetti necessari per realizzare il progetto e/o spiegati a lezione. La valutazione del progetto sarà fatta in base alla: conformità dell implementazione scelta per risolvere il problema con il paradigma di programmazione a oggetti; conformità del codice presentato alle regole di buona programmazione; adeguatezza della documentazione presentata; assenza di errori nel programma. Visto inoltre l elevato grado di libertà lasciato relativamente all implementazione del progetto, la valutazione delle scelte implementative avrà un peso decisamente maggiore rispetto alla correttezza della soluzione proposta. Dario Malchiodi Walter Cazzola Dip. di Scienze dell Informazione Dip. di Informatica e Comunicazione Via Comelico 39/ Milano Via Comelico 39/ Milano Stanza S238 Tel Stanza S220 Tel malchiodi@dsi.unimi.it cazzola@dico.unimi.it 7