WSO2 WSF/PHP: Servizio Web per il controllo caselle di posta
Introduzione
Quante volte è capitato di avere la necessità di verificare la validità di uno o più indirizzi mail? Penso una miriade di volte, in particolar modo in tutte quelle situazioni, dove per esempio il vostro ipotetico sistema deve comunicare via mail con i propri utenti. In questo breve articolo vedremo come creare un servizio web che compi il controllo di validità di una o più caselle di posta. In questo contesto la validità della mail non si riferisce ad controllo di correttezza formale, è invece la verifica dell'esistenza della casella di posta per il dominio specificato.
L’infrastruttura necessaria per creare il nostro servizio web è fornita dal framework di WSO2: Web Services for PHP, abbreviato in WSF/PHP. Assumiamo che il framework WSF/PHP sia correttamente installato e configurato, assumiamo inoltre di avere una certa padronanza nell'utilizzo di questo framework. Il servizio web che andremo a realizzare richiede una libreria PHP chiamata SMTP Email Validation[1], responsabile della verifica delle caselle di posta.
Definizione dell’interfaccia
Ogni servizio web ha una propria interfaccia con la quale si presenta verso l’esterno. Nei nostri “tempi moderni”, quest’interfaccia è solitamente descritta attraverso un particolare documento XML denominato Web Service Definition Language (WSDL[2]).
Battezziamo il nostro servizio web con il nome di WSEmailValidation che conterrà una sola operazione denominata ExecuteEmailValidation (vedi Tabella 1). L’operazione del nostro servizio web sarà responsabile della validazione di una o più caselle di posta (passate come argomento) sfruttando il protocollo SMTP[3], per far questo, il nostro servizio web farà uso della libreria PHP menzionata nel paragrafo introduttivo.
Tabella 1 Firme dell’insieme di Operations per il servizio WSEmailValidation
Nome Servizio Web | WSEmailValidation | |||
Operation | ExecuteEmailValidation | |||
Parametro | Tipo | IN/OUT | Descrizione | |
Input | Object (EmailValidationInput) NOT NULL | IN | Oggetto di tipo EmailValidationInput contenente le email da validare. | |
Response | Object (EmailValidationResponse) | OUT | Oggetto di tipo EmailValidationResponse contenente una collezione di oggetti di tipo EmailValidation. |
Avvalendoci di diagrammi vedremo come sono composti gli oggetti coinvolti dal nostro servizio web. Figure 1 Rappresentazione del Complex Type EmailValidationInput Figure 2 Rappresentazione del Complex Type EmailValidationResponse L’oggetto EmailValidationResponse è una collection di oggetti di tipo EmailValidation, in Figura 3 la struttura. Figure 3 Rappresentazione del Complex Type EmailValidation
Implementazione del servizio web WSEmailValidation
Definita a grandi linee l’interfaccia del nostro servizio web, non resta altro che passare all’implementazione vera e propria. Utilizzeremo una caratteristica presente su WSF/PHP e su qualunque altro framework di livello enterprise, faccio riferimento alle annotations. Partiamo da subito con la definizione dei Complex Type visti in precedenza.
Listato 1 Definizione dei Complex Type tramite annotation
/** * Class of EmailValidationInput * * @namespace http://shirus.lab.dontesta.it/ws/WSEmailValidation */ class emailValidationInput {/** * @var string $emails One or more Email */ public $emails; } /** * Class of EmailValidationResponse * @namespace http://shirus.lab.dontesta.it/ws/WSEmailValidation */ class emailValidationResponse { /** * @var [0, unbounded] array of object EmailValidation $emailValidation Returns the email validation results */ public $emailValidation; } /** * Class of EmailValidation * * @namespace http://shirus.lab.dontesta.it/ws/WSEmailValidation */ class EmailValidation { /** * @var string $email Email */ public $email; /** * @var string $sender Name of Sender */ public $sender; /** * @var string $result Result of Email Validation */ public $result; } |
Per avere maggiori informazioni sulle annotation di WSF/PHP è possibile far riferimento alla documentazione ufficiale disponibile all’indirizzo http://wso2.org/project/wsf/php/2.0.0/docs/api.html sezione WSDL Generation API => Annotation Syntax. Al Listato 2 è invece l’illustrata l’implementazione dell’operazione ExecuteEmailValidation.
Listato 2 Implementazione dell’operazione ExecuteEmailValidation
/** * The Service Operation ExecuteEmailValidation * * @namespace http://shirus.lab.dontesta.it/ws/WSEmailValidation * @param object emailValidationInput $input * @return object emailValidationResponse $response */ function ExecuteEmailValidation($input) { try { // The email to validate $emails = split(',',$input['emails']); // Instantiate the class $SMTP_Validator = new SMTP_validateEmail(); // Do the validation $results = $SMTP_Validator->validate($emails);// Prepare Email Valitation Response $response = new emailValidationResponse(); $response->emailValidation = array(); // View results foreach($results as $email=>$result) { if ($result) { $validation = new EmailValidation(); $validation->email = $email; $validation->sender = $sender; $validation->result = 'The email address '. $email.' is valid'; array_push($response->emailValidation, $validation); } else { $validation = new EmailValidation(); $validation->email = $email; $validation->sender = $sender; $validation->result = 'The email address '. $email.' is not valid'; array_push($response->emailValidation, $validation); } } return array($response); } catch (Exception $e) { throw new WSFault("Sender", $e->getCode() . " - " . $e->getMessage()); } } |
Le annotation, oltre a definire il namespace, indicano così come dichiarato in Tabella 1, il tipo di parametro d’input e il tipo di ritorno dell’operazione ExecuteEmailValidation.
L’implementazione dell’operazione ExecuteEmailValidation è abbastanza chiara, tale da poter essere ricondotta ad uno schema di questo tipo:
- Acquisizione delle caselle di posta da sottoporre a validazione. È creata una struttura dati (Array) che contiene una o più caselle di posta;
- Istanza della classe SMTP_validateEmail e richiamo del metodo di validazione;
- Preparazione della risposta verso il consumer del servizio web
Nel Listato 3 è illustrata l’ultima parte di codice che rende operativo il servizio web. Listato 3 Istanza del servizio WSEmailValitation
// Define the operations map $operations = array( "ExecuteEmailValidation" => "ExecuteEmailValidation"); // Params options $opParams = array("ExecuteEmailValidation"=>"MIXED"); // Sends the reply in response to a client invocation $service = new WSService(array("operations"=>$operations, "serviceName"=>"WSEmailValidation", "opParams"=>$opParams)); $service->reply(); |
A questo punto il nostro servizio web è pronto all’uso. L’end point del servizio web varia secondo la configurazione adottata per il proprio ambiente di sviluppo, per esempio nel mio caso, il documento WSDL (versione 1.1 e 2.0) e raggiungibile all’indirizzo http://shirus.lab.dontesta.it/~amusarra/WSEmailValidation/WSEmailValidation?wsdl
Test del servizio WSValidationEmail
Una volta costruito il nostro servizio web non resta che consumarlo per eseguire i primi test. Le strade per consumare il servizio web possono essere:
- Creazione di un client utilizzando i tool di WSO2 WSF/PHP. Per maggiori info fare riferimento alla documentazione ufficiale di WSO2;
- Utilizzare SOAP UI (o altro) per eseguire il test;
Propendo per la seconda strada. E’ possibile scaricare la versione Open Source di SOAP UI direttamente dal sito http://www.soapui.org/. L’utilizzo del prodotto è veramente semplice e intuitivo, basta creare un nuovo progetto sulla base dell’URL del WSDL e in modo del tutto automatico il tool crea l’ambiente necessario per eseguire le richieste al nostro servizio WSEmailValidation.
Nelle successive figure sono illustrati degli screenshot di SOAP UI che mostrano la richiesta SOAP e la risposta SOAP del servizio. Figure 4 SOAP UI Richiesta del servizio Figure 5 SOAP UI Risposta del servizio Di seguito una serie di risposte del servizio WSEmailValidation
- SOAP Response per una casella di posta esistente
- SOAP Response per una casella di posta per cui non esiste il dominio
- SOAP Response per una casella di posta che non esiste
- SOAP Response per due casella di posta: una corretta ed una non corretta
[1] A PHP class that allows validation of email addresses via SMTP. For more info at URL http://code.google.com/p/php-smtp-email-validation/ [2] The W3C note is a specification for describing network services as a set of endpoints operating on messages containing either document-oriented. For more info at URL http://www.w3.org/TR/wsdl [3] Simple Mail Transfer Protocol. For more info at URL http://it.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol