SeamFramework.orgCommunity Documentation
Seam include ora dei componenti opzionali per modellare e spedire le email.
Il supporto email è fornito da jboss-seam-mail.jar. Questo JAR contiene i controlli JSF per la mail, che vengono impiegati per costruire le email, ed il componente manager mailSession.
Il progetto examples/mail contiene un esempio di supporto email in azione. Mostra un pacchetto idoneo e contiene esempi che mostrano le funzionalità chiave attualmente supportate.
Si può testare la propria mail usando l'ambiente di test di Seam. Si veda Sezione 37.3.4, «Test d'integrazione di Seam Mail».
Non occorre imparare un nuovo linguaggio di template per usare Seam Mail — un'email è semplicemente un facelet!
<m:message xmlns="http://www.w3.org/1999/xhtml"
xmlns:m="http://jboss.com/products/seam/mail"
xmlns:h="http://java.sun.com/jsf/html">
<m:from name="Peter" address="peter@example.com" />
<m:to name="#{person.firstname} #{person.lastname}"
>#{person.address}</m:to>
<m:subject
>Try out Seam!</m:subject>
<m:body>
<p
><h:outputText value="Dear #{person.firstname}" />,</p>
<p
>You can try out Seam by visiting
<a href="http://labs.jboss.com/jbossseam"
>http://labs.jboss.com/jbossseam</a
>.</p>
<p
>Regards,</p>
<p
>Pete</p>
</m:body>
</m:message
>
Il tag <m:message> racchiude l'intero messaggio e dice a Seam di iniziare a generare la mail. Dentro al tag <m:message> si usa un tag <m:from> per impostare il mittente, un tag <m:to> per specificare un destinatario (si noti che EL viene impiegato come in un facelet normale), e un tag <m:subject>.
Il tag <m:body> racchiude il corpo della mail. Si possono usare tag HTML dentro il corpo così come componenti JSF.
Adesso che si ha un modello di email, come lo si spedisce? Alla fine della generazione di m:message viene chiamato mailSession per spedire l'email, e quindi semplicemente occorre chiedere a Seam di generare la vista:
@In(create=true)
private Renderer renderer;
public void send() {
try {
renderer.render("/simple.xhtml");
facesMessages.add("Email sent successfully");
}
catch (Exception e) {
facesMessages.add("Email sending failed: " + e.getMessage());
}
}
Per esempio, se si digita un indirizzo email non valido, allora viene lanciata un'eccezione che viene catturata e quindi mostrata all'utente.
Seam semplifica l'uso degli allegati ad una mail. Supporta la maggior parte dei tipi java standard usati con i file.
Se si vuole spedire jboss-seam-mail.jar:
<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar"/>
Seam caricherà il file dal classpath e lo allegherà alla mail. Di default verrà allegato come jboss-seam-mail.jar; se si vuole avere un altro nome basta aggiungere l'attributo fileName:
<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar" fileName="this-is-so-cool.jar"/>
Si può anche allegare un java.io.File, un java.net.URL:
<m:attachment value="#{numbers}"/>
Oppure un byte[] o un java.io.InputStream:
<m:attachment value="#{person.photo}" contentType="image/png"/>
Si noterà che per byte[] e java.io.InputStream occorrerà specificare il tipo MIME dell'allegato (poiché quest'informazione non viene trasportata come parte del file).
Ancora meglio si può allegare un PDF generato da Seam, o ogni altra vista JSF standard, semplicemente mettendo un <m:attachment> attorno ai normali tag:
<m:attachment fileName="tiny.pdf">
<p:document
>
A very tiny PDF
</p:document>
</m:attachment
>
Con un set di file da allegare (per esempio un gruppo di fotografie caricate da un database) si utilizza un <ui:repeat>:
<ui:repeat value="#{people}" var="person">
<m:attachment value="#{person.photo}" contentType="image/jpeg" fileName="#{person.firstname}_#{person.lastname}.jpg"/>
</ui:repeat
>
E se si vuole mostrare un'immagine allegata inline:
<m:attachment
value="#{person.photo}"
contentType="image/jpeg"
fileName="#{person.firstname}_#{person.lastname}.jpg"
status="personPhoto"
disposition="inline" />
<img src="cid:#{personPhoto.contentId}" />
Ci si potrebbe chiedere a cosa serva cid:#{...}. IETF specifica che mettendo questo come src dell'immagine, verranno visualizzati gli allegati quando si tenta di localizzare l'immagine (il Content-ID deve corrispondere) — magia!
Occorre dichiarare l'allegato prima di tentare di accedere allo stato dell'oggetto.
Nonostante la maggior parte dei lettori email oggi supportino HTML, alcuni non lo fanno, quindi è possibile aggiungere un'alternativa di puro testo al corpo della mail:
<m:body>
<f:facet name="alternative"
>Sorry, your email reader can't show our fancy email,
please go to http://labs.jboss.com/jbossseam to explore Seam.</f:facet>
</m:body
>
Spesso si vuole spedire una mail ad un gruppo di destinatari (per esempio i propri utenti). Tutti i tag dei destinatari possono essere messi dentro un <ui:repeat>:
<ui:repeat value="#{allUsers} var="user">
<m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
</ui:repeat
>
A volte, comunque, occorre spedire un messaggio leggermente diverso a ciascun utente (es. una password resettata). Il miglior modo per farlo è mettere l'interno messaggio dentro un <ui:repeat>:
<ui:repeat value="#{people}" var="p">
<m:message>
<m:from name="#{person.firstname} #{person.lastname}"
>#{person.address}</m:from>
<m:to name="#{p.firstname}"
>#{p.address}</m:to>
...
</m:message>
</ui:repeat
>
L'esempio mail templating mostra che il templating facelets funziona solo con i tag mail di Seam.
template.xhtml contiene:
<m:message>
<m:from name="Seam" address="do-not-reply@jboss.com" />
<m:to name="#{person.firstname} #{person.lastname}"
>#{person.address}</m:to>
<m:subject
>#{subject}</m:subject>
<m:body>
<html>
<body>
<ui:insert name="body"
>This is the default body, specified by the template.</ui:insert>
</body>
</html>
</m:body>
</m:message
>
templating.xhtml contiene:
<ui:param name="subject" value="Templating with Seam Mail"/>
<ui:define name="body">
<p
>This example demonstrates that you can easily use <i
>facelets templating</i
> in email!</p>
</ui:define
>
Si possono usare anche i tag sorgente di facelets nella propria email, ma occorre metterli in un jar dentro WEB-INF/lib - fare riferimento a .taglib.xml da web.xml non è molto affidabile quando si usa Seam Mail (se si spedisce la mail in modo asincrono Seam Mail non ha accesso all'intero contesto JSF o Servlet, e quindi non conosce i parametri di configurazione di web.xml).
Se occorre configurare Facelets o JSF per spedire mail, servirà eseguire l'override del componente Renderer e configurarlo programmaticamente - solo per utenti avanzati!
Seam supporta l'invio di messaggi internazionalizzati. Di default, viene usata la codifica fornita da JSF, ma questa può essere sovrascritta nel template:
<m:message charset="UTF-8">
...
</m:message
>
Il corpo, soggetto e nome destinatario (e mittente) verranno codificati. Occorre assicurarsi che facelets usi il set di caratteri corretto per il parsing delle pagine, impostando la codifica del template:
<?xml version="1.0" encoding="UTF-8"?>
A volte si vogliono aggiungere altre intestazioni alla mail. Seam fornisce supporta per alcune di queste (si veda Sezione 21.5, «Tag»). Per esempio, si può impostare l'importanza della mail e chiedere una conferma di lettura:
<m:message xmlns:m="http://jboss.com/products/seam/mail"
importance="low"
requestReadReceipt="true"/>
Altrimenti si può aggiunge una qualsiasi intestazione al messaggio usando il tag <m:header>:
<m:header name="X-Sent-From" value="JBoss Seam"/>
Se si usa EJB, allora si può impiegare MDB (Message Driven Bean) per ricevere una mail. JBoss fornisce un adattatore JCA — mail-ra.rar — ma la versione distribuita con JBoss AS ha un numero di limitazioni (e non è incorporata in alcune versioni) quindi si raccomanda di usare mail-ra.rar distribuito con Seam (si trova nella directory extras/ nella distribuzione Seam). mail-ra.rar deve essere messo in $JBOSS_HOME/server/default/deploy; se la versione di JBoss già lo contiene, lo si sostituisca.
Lo si può configurare come:
@MessageDriven(activationConfig={
@ActivationConfigProperty(propertyName="mailServer", propertyValue="localhost"),
@ActivationConfigProperty(propertyName="mailFolder", propertyValue="INBOX"),
@ActivationConfigProperty(propertyName="storeProtocol", propertyValue="pop3"),
@ActivationConfigProperty(propertyName="userName", propertyValue="seam"),
@ActivationConfigProperty(propertyName="password", propertyValue="seam")
})
@ResourceAdapter("mail-ra.rar")
@Name("mailListener")
public class MailListenerMDB implements MailListener {
@In(create=true)
private OrderProcessor orderProcessor;
public void onMessage(Message message) {
// Process the message
orderProcessor.process(message.getSubject());
}
}
Ogni messaggio ricevuto causerà una chiamata a onMessage(Message message). La maggior parte delle annotazioni di Seam funzioneranno dentro MDB, ma non sarà possibile accedere al contesto di persistenza.
Si possono trovare maggiori informazioni su mail-ra.rar all'indirizzo http://www.jboss.org/community/wiki/InboundJavaMail.
Se non si usa JBoss AS si può comunque usare mail-ra.rar oppure si cerchi se il proprio application server include un adattatore simile.
Per includere il supporto email nella propria applicazione, si includa jboss-seam-mail.jar nella directory WEB-INF/lib. Se si usa JBoss AS non c'è nessuna configurazione ulteriore per usare il supporto email di Seam. Altrimenti occorre assicurarsi di avere JavaMail API, un'implementazione di JavaMail API presente (l'API e l'impl usate in JBoss AS sono distribuite con seam in lib/mail.jar), ed una copia di Java Activation Framework (distribuito con seam in lib/activation.jar.
Il modulo Seam Mail richiede l'uso di Facelets come tecnologia per la vista. Future versioni della libreria potranno supportare l'uso di JSP. In aggiunta si richiede l'uso del pacchetto seam-ui.
Il componente mailSession usa JavaMail per dialogare con un server SMTP 'reale'.
Una sessione JavaMail può essere disponibile via ricerca JNDI se si lavora in ambiente JEE o si può usare una sessione configurata da Seam.
Le proprietà del componente mailSession sono descritte con maggior dettaglio in Sezione 32.9, «Componenti relativi alla Mail».
deploy/mail-service.xml di JBoss AS configura una sessione JavaMail legandola a JNDI. La configurazione di default del servizio deve essere modificata per la propria rete. http://www.jboss.org/community/wiki/JavaMail descrive il servizio con maggiore dettaglio.
<components xmlns="http://jboss.com/products/seam/components"
xmlns:core="http://jboss.com/products/seam/core"
xmlns:mail="http://jboss.com/products/seam/mail">
<mail:mail-session session-jndi-name="java:/Mail"/>
</components
>
Qua viene detto a Seam di ottenere da JNDI la sessione mail associata java:/Mail.
Una sessione mail può essere configurata via components.xml. Qua viene indicato a Seam di usare smtp.example.com come server SMTP:
<components xmlns="http://jboss.com/products/seam/components"
xmlns:core="http://jboss.com/products/seam/core"
xmlns:mail="http://jboss.com/products/seam/mail">
<mail:mail-session host="smtp.example.com"/>
</components
>
L'esempio mail di Seam usa Meldware (da buni.org) come server mail. Meldware è un pacchetto groupware che fornisce SMTP, POP3, IMAP, webmail, un calendario condiviso ed un tool di amministrazione grafico; è scritto come applicazione JEE e quindi può essere deployato in JBoss AS assieme alla propria applicazione Seam.
La versione di Meldware distribuita con Seam (scaricata a richiesta) è configurata per lo sviluppo - caselle di posta, utenti e alias (indirizzi email) sono creati ogni volta che si esegue il deploy dell'applicazione. Se si vuole usare Meldware in produzione occorre installare l'ultima release da buni.org.
Le email vengono generate usando tag nel namespace http://jboss.com/products/seam/mail. I documenti dovrebbero sempre avere il tag message alla radice del messaggio. Il tag message prepara Seam a generare una email.
I tag standard per il templating di facelets possono venire usati normalmente. Dentro il corpo si può usare qualsiasi tag JSF; se viene richiesto l'accesso a risorse esterne (fogli di stile, javascript) allora ci si assicuri di impostare urlBase.
Tag radice di un messaggio mail
importance — low, normal o high. Di default è normal, questo imposta l'importanza del messaggio email.
precedence — imposta la precedenza del messaggio (es. bulk).
requestReadReceipt — di default è false, se impostato, verrà aggiunta una richiesta di conferma di lettura, da inviare all'indirizzo From:.
urlBase — Se impostato, il valore è messo prima di requestContextPath consentendo di usare nelle proprie email componenti quali <h:graphicImage>.
messageId — Imposta esplicitamente il Message-ID
Si imposti l'indirizzo From: per la mail. Se ne può avere uno soltanto per email.
name — il nome da cui l'email deve provenire.
address — l'indirizzo email da cui la mail deve provenire.
Si imposti l'indirizzo Reply-to: per la mail. Se ne può avere uno soltanto per email.
address — l'indirizzo email da cui la mail deve provenire.
Si aggiunga un destinatario alla mail. Si usino più tag <m:to> per destinatari multipli. Questo tag può essere collocato in modo sicuro dentro un tag repeat quale <ui:repeat>.
name — il nome del destinatario.
address — l'indirizzo email del destinatario.
Si aggiunga un destinatario cc alla mail. Si usino più tag <m:cc> per destinatari cc multipli. Questo tag può essere collocato in modo sicuro dentro un tag iteratore quale <ui:repeat>.
name — il nome del destinatario.
address — l'indirizzo email del destinatario.
Si aggiunga un destinatario ccn alla mail. Si usino più tag <m:bcc> per destinatari ccn multipli. Questo tag può essere collocato in modo sicuro dentro un tag repeat quale <ui:repeat>.
name — il nome del destinatario.
address — l'indirizzo email del destinatario.
Aggiungere un'intestazione alla mail (es. X-Sent-From: JBoss Seam)
name — Il nome dell'intestazione da aggiungere (es. X-Sent-From).
value — Il valore dell'intestazione da aggiungere (es. JBoss Seam).
Aggiungere un allegato alla mail.
value — Il file da allegare.
String — Una String è interpretata come path al file all'interno del classpath
java.io.File — Un'espressione EL può fare riferimento ad un oggetto File
java.net.URL — Un'espressione EL può fare riferimento ad un oggetto URL
java.io.InputStream — Un'espressione EL può fare riferimento ad un oggetto InputStream. In questo caso devono essere specificati entrambi i fileName e contentType.
byte[] — Un'espressione EL può fare riferimento a byte[]. In questo caso devono essere specificati entrambi i fileName e contentType.
Se viene omesso l'attributo value:
Se questo tag contiene un tag <p:document>, il documento descritto sarà generato ed allegato alla mail. Deve essere specificato un fileName.
Se questo tag contiene altri tag JSF, da questi verrà generato un documento HTML ed allegato alla mail. Un fileName dovrebbe sempre essere specificato.
fileName — Specifica il nome del file da usare per il file allegato.
contentType — Specifica il tipo MIME del file allegato.
Impostiamo l'oggetto della mail.
Si imposti il corpo della mail. Supporta un facet alternativo che, se viene generata una mail HTML, può contenere testo alternativo per un lettore di email che non supporta HTML.
type — Se impostato a plain allora verrà generata una mail con semplice testo, altrimenti una mail HTML.