Mail merge

Mail merge
Progetto valido per gli appelli di settembre 2008 e gennaio 2009
1
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.
• Email, 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
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
Figura 1: Un possibile contenuto del modello per il testo di un messaggio di posta elettronica.
titolo
primo nome
secondo nome
cognome
acquisti>100
saluto
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 1.
4.2
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
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 Email.
• 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
• 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 Email 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
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, EMail 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
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
http://homes.dsi.unimi.it/~malchiod/LP/sottoposizione
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
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
Dip. di Scienze dell’Informazione
Via Comelico 39/41 20135 Milano
Stanza S238 – Tel. +39 02 503 16338
e-mail [email protected]
Walter Cazzola
Dip. di Informatica e Comunicazione
Via Comelico 39/41 20135 Milano
Stanza S220 – Tel. +39 02 503 16300
e-mail [email protected]
7