Come si ricorderà dalla puntata precedente [1], il processo di creazione di un servizio Web in J2EE passa attraverso sei diverse fasi:

• definizione;
• implementazione;
• produzione del pacchetto di installazione;
• installazione del pacchetto in un server J2EE;
• pubblicazione del servizio in un registro (opzionale);
• risposta alle richieste dei client.

Nella scorsa puntata abbiamo affrontato le prime due fasi; in questa affronteremo la produzione del pacchetto e la sua installazione, tramite un tutorial guidato ed illustrato che riprende l'esempio di servizio (HelloService) presente negli esempi del tutorial di SUN per J2EE 1.4 [3], ed in particolare nel capitolo 17.

Preparazione degli strumenti
La fase di installazione (deploy) dell'applicazione e della pubblicazione sui registri di servizi Web sono tipicamente operazioni svolte con gli strumenti di supporto; in particolare si prevede che la pubblicazione non debba richiedere al programmatore l'utilizzo di JAXR per pubblicare il servizio, ma che sia una commodity fornita dall'application server utilizzato.
Per creare un pacchetto di installazione è necessario utilizzare lo strumento di deploy di SUN, il Deploytool; per operare, è necessario prima avviare il server J2EE tramite la funzione "Start Application Server". Attenzione però - per un fastidioso problema con la beta 2 dell'SDK (si parla della versione Windows NT), utilizzare gli strumenti forniti con impostazione internazionale diversa dall'inglese americano provoca diversi problemi relativi ad XML, sia a livello di Deploytool che di Application Server. Per ovviare all'inconveniente, è possibile provare due workaround, il primo meno invasivo, il secondo di più. Come primo tentativo è possibile impostare la Virtual Machine degli strumenti per operare con l'impostazione statunitense, senza modificare le impostazioni di Windows. A tal fine è necessario applicare le seguente modifiche, ad esempio (tratto da deploytool.bat):

set _USER_LANG=en
set _USER_REGION=US
%_JAVACMD% -Duser.language=%_USER_LANG% -Duser.region=%_USER_REGION% -Dcom.sun.aas.installRoot="%AS_INSTALL%" -Djava.endorsed.dirs=%AS_INSTALL%\share\lib\endorsed -Dcom.sun.aas.defaultUserName="%AS_ADMIN_USER%" -Dcom.sun.aas.defaultPassword="%AS_ADMIN_PASSWORD%" -cp %_CPATH% %_MAIN% %1 %2

Se questa modifica non dovesse funzionare, è possibile modificare le impostazioni internazionali di Windows e tutto dovrebbe operare correttamente.

Creazione del pacchetto
Avviato dunque Deploytool, è necessario dapprima creare l'applicazione enterprise che ospiterà il servizio.

• Selezionare dunque File | New | Application EAR;
• selezionare "browse" e posizionarsi in una directory libera;
• nel campo File Name, digitare HelloService.ear.
  
  

Se avete scaricato il codice sorgente del tutorial J2EE, è possibile posizionare l'EAR nella sottodirectory /j2eetutorial14/examples/ejb/helloservice/ (Figura 1).

Figura 1 - Organizzazione delle directory del codice del tutorial J2EE 1.4

• Selezionare dunque "New Application" e selezionare OK.

A questo punto è possibile creare l'enterprise bean utilizzando il wizard relativo di Deploytool. Selezionare File | New | Enterprise; viene presentato un wizard composto da una serie di pagine. La prima è semplicemente descrittiva delle funzionalità dello strumento. Selezionare Next.

Pagina EJB EAR
In questa pagina è necessario specificare il codice necessario ad implementare il componente. Procedere come segue:

• selezionare il pulsante Create New JAR Module;
• nel combo box sottostante selezionare HelloService;
• nel campo JAR Display Name digitare HelloServiceJAR;
• selezionare edit. Dalla dialog box che appare, è necessario individuare il percorso che

contiene i file compilati, che nel codice del tutorial sono sotto il percorso /j2eetutorial14/examples/ejb/helloservice/build/. Da qui è necessario importare i file mapping.xml, MyHelloService.wsdl e le classi presenti nella sottodirectory helloservice, come mostrato in figura 2.

Figura 2 - Selezionare gli opportuni file da
importare nel componente

Per confermare, selezionare Add e poi OK. Il risultato che si dovrebbe ottenere è mostrato in figura 3. Selezionare Next.

Figura 3 - La pagina EJB JAR completata con le informazioni necessarie

Pagina General
La pagina successiva consente di impostare i componenti EJB che si sta creando, specificandone le classi di interfaccia e di implementazione, oltre che il nome ed il tipo. Procedere come segue:

• selezionare Session nel riquadro Bean Type;
• selezionare il pulsante Stateless;
• selezionare helloservice.HelloServiceBean nel combo box Enterprise Bean Class;
• digitare HelloServiceEJB nel campo Enteprise Bean Class;

Il risultato è presente in figura 4. Selezionare Next.

Figura 4 - Impostazione delle opzioni del Bean

Pagina Configuration Options
In questa pagina non c'è molto da fare: il sistema per default sceglie di esporre il componente come servizio Web, selezionado Yes nella radio button Expose Bean as Web Service Endpoint. Selezionare Next

Pagina Choose Service
In questa pagina viene indicato a quale endpoint deve essere collegato il servizio; è possibile sia collegarsi ad un servizio esistente, oppure crearne uno nuovo. Si scelga questa seconda opzione e si compilino i campi come segue:

• selezionare il file META-INF/wsdl/MyHelloService.wsdl nel combo box relativo al file WSDL;
• selezionare il file mapping.xml dal combo box Mapping File;
• assicurarsi che nei campi Service Name e Service Display Name sia presente il valori "MyHelloService".

La pagina dovrebbe apparire come in figura 5. Selezionare Next.

Figura 5 - La definizione del servizio Web

Pagina Endpoint
In questa pagina viene collegato l'endpoint al servizio che si sta definendo, tramite l'indicazione dei namespace e dell'URI relativo. Questa pagina va configurata come segue:

• selezionare helloservice.HelloIF nella combo box Service Endpoint Interface;
• compilare la sezione WSDL Port, digitando "urn:Foo" nel campo namespace e "HelloIFPort" nel campo Local Part;
• impostare l'address URI nella sezione Deployment Settings a hello-ejb/hello.

La pagina dunque si configura come in figura 6. Successivamente selezionare Next.

Figura 6 - Configurazione dell'endpoint del servizio

Conclusione
L'ultima pagina del wizard presenta il descrittore del servizio, per una ispezione visiva del risultato prodotto (figura 7). Selezionare Finish.

Figura 7 - Il descrittore prodotto

Installazione dell'applicazione
A questo punto l'applicazione è completa: al suo interno è presente il descrittore dell'applicazione ed il codice ed i descrittori del bean e del servizio Web (figura 8); a questo punto è possibile eseguire il deploy. Selezionare l'applicazione e scegliere Tools | Deploy - lo strumento richiederà l'autenticazione dell'utente tramite utente e password che dovranno coincidere con quelli inseriti in fase di installazione dell'SDK (figura 9).

Figura 8 - L'applicazione è ora completa ed è possibile visualizzarne
i parametri all'interno di Deploytool

Figura 9 - Per accedere al server applicativa è necessaria l'autenticazione

L'installazione viene controllata tramite la finestra di console di Deploytool che riporta i messaggi prodotti dallo strumento nelle fasi di installazione (deploy) e partenza (Figura 10).

Figura 10 - La console di Deploytool

Test del client
Sempre all'interno del tutorial di SUN è presente un semplice programma JAX-RPC client, basato su stub statici, per provare il servizio realizzato. Questo è un classico programma client JAX-RPC simile a quelli realizzati nelle precedenti puntate (si veda [2]) che riporto qui per comodità (listato 1).

Listato 1 - HelloClient.java
package staticstub;

import javax.xml.rpc.Stub;

public class HelloClient {

  private String endpointAddress;

  public static void main(String[] args) {

  System.out.println("Endpoint address = " + args[0]);
  try {
    Stub stub = createProxy();
    stub._setProperty(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
                      args[0]);
    HelloIF hello = (HelloIF)stub;
    System.out.println(hello.sayHello("Duke!"));
  }
  catch (Exception ex) {
    ex.printStackTrace();
  }
}

  private static Stub createProxy() {
    // Note: MyHelloService_Impl is implementation-specific.
    return (Stub)(new MyHelloService_Impl().getHelloIFPort());
  }
}

Si noti che gli stub vengono generati con il comando wscompile, con un comando simile al seguente:
wscompile.bat -gen:client -d build -classpath build config-wsdl.xml

Il file confi-wsdl.xml è così composto:
<?xml version="1.0" encoding="UTF-8"?>
<configuration
xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
<wsdl location="build/MyHelloService.wsdl"
packageName="helloservice"/>
</configuration>

Il risultato è mostrato in figura 11. Per provare il client con gli esempi presenti nel tutorial di SUN è necessario eseguire i seguenti comandi:
· asant build dalla directory j2eetutorial14/examples/jaxrpc/helloservice;
· asant build dalla directory j2eetutorial14/examples/jaxrpc/staticstub;

per eseguire il client utilizzare il comando asant run dalla directory j2eetutorial14/examples/jaxrpc/staticstub.

Client J2EE
Il supporto ai servizi Web della tecnologia J2EE non è però solo limitata al server: sebbene la piattaforma enterprise di Java offra una ottima e completa infrastruttura per realizzare componenti server, le specifiche 1.4 includono anche il supportod lato client, non solo tramite le API JAXR per l'accesso ai registry di Web Services, ma anche per fruire dei servizi all'interno di client J2EE.
L'accesso ad un componente EJB esportato come servizio non si discosta dallo standard previsto per la piattaforma per l'accesso ai normali Bean Enterprise, e si basa su un lookup JNDI. Per convenzione, tutti i servizi Web sono raccolti sotto il prefisso java:comp/env/service/.
Nel listato 2 è presente un client di prova.

Listato 2 - HelloClient.java
package appclient;

import javax.xml.rpc.Stub;
import javax.naming.*;

public class HelloClient {

  private String endpointAddress;

  public static void main(String[] args) {

    System.out.println("Endpoint address = " + args[0]);

    try {
      Context ic = new InitialContext();
      MyHelloService myHelloService = (MyHelloService)
      ic.lookup("java:comp/env/service/MyJAXRPCHello");
      appclient.HelloIF helloPort=myHelloService.getHelloIFPort();
      ((Stub)helloPort)._setProperty(
                         Stub.ENDPOINT_ADDRESS_PROPERTY,args[0]);

    System.out.println(helloPort.sayHello("Jake!"));
    System.exit(0);

    } catch (Exception ex) {
      ex.printStackTrace();
      System.exit(1);
    }
  } // main
}

Il programma può essere eseguito solo all'interno di un contesto J2EE, dunque è necessario eseguirne il deploy tramite Deplotool. Per prima cosa è necessario però compilare il codice, eventualmente sfruttando gli script forniti con gli esempi del tutorial e presenti sotto j2eetutorial14/examples/jaxrpc/appclient. Eseguire dunque il comando asant build.
Una volta eseguita la compilazione, si passi a Deploytool e si selezioni File | New | Application EAR. Tramite il pulsante Browse, posizionarsi sul percorso j2eetutorial14/examples/jaxrpc/appclient e digitare HelloServiceApp nel campo File Name. Fare clic su New Application e poi su OK (figura 12).

Figura 12 - La nuova applicazione nel relativo elenco

A questo punto è possibile creare il nuovo JAR Client, tramite il wizard relativo, richiamabile tramite la voce File | New | Application Client JAR. Il wizard presenta come di consueto una prima pagina di presentazione. Selezionando Next viene presentata la JAR File Contents.

Pagina JAR File Contents
In questa pagina si costruirà il vero e proprio componente client, specificando le classi compilate che lo compongono. Procedere come segue:

• nel riquadro AppClient Location selezionare Create New AppClient Module in Application;
• nella combo-box sottostante selezionare HelloServiceApp;
• nel riquadro AppClient Display Name digitare HelloClient;
• selezionare il pulsante Edit ed aggiungere la directory build nel percorso /examples/jaxrpc/appclient, selezionando la suddetta directory e premendo il pulsante Add (Figura 12);
• selezionare OK. La pagina assume la forma presente in figura 13.

Figura 12 - Aggiunta delle classi al modulo JAR

Figura 13 - I contenuti del JAR client

Pagina General
La pagina conclusiva del wizard consente di specificare la classe principale dell'applicazione. Selezionare dunque appclient.HelloClient nel combo box Main Class (figura 14) e premere Finish.

Figura 14 - Configurazione della classe principale.

A questo punto la nuova applicazione è creata ed elencata nella cartella Applications (figura 15).

Figura 15 - La nuova applicazione
HelloServiceApp

L'ultimo passaggio necessario al funzionamento del client è la configurazione del riferimento web JNDI, che avviene tramite la tab Web Service Refs nel componente HelloClient. Dalla finestra, selezionare Add e specificare:

• service/MyJAXRPCHello nel campo Coded Name;
• selezionare appclient.MyHelloService nel combo box Service Interface;
• selezionare il file MyHelloService.wsdl nel combo box del file WSDL;
• digitare urn:Foo nel campo namespace;
• digitare MyHelloService nel campo Local Part;
• selezionare mapping.xml nel combo box Mapping File;
• selezionare OK (figura 16).

Figura 16 - Configurazione del Web Service Reference

A questo punto è possibile eseguire il deploy di quanto generato, per ottenere in risposta il JAR del client relativo. Per fare questo:

• selezionare l'applicazione HelloServiceApp;
• selezionare Tools | Deploy;
• nella finestra che appare selezionare il checkbox Return Client JAR;
• digitare utente e password;
• selezionare OK (figura 17)

Figura 17 - Finestra di installazione

Se tutto è stato fatto correttamente, il sistema presenta un file di log libero da errori (figura 18).

Figura 18 - Installazione completata

Prova del client J2EE
Dopo tutti questi passaggi, dovremmo essere in grado di provare il client J2EE tramite il servizio di prova EJB installato in precedenza. Il servizio è già stato provato con un client JAX-RPC, dunque l'attenzione verrà concentrata sul client J2EE. Posizionarsi nella directory /j2eetutorial14/examples/jaxrpc/appclient/ e digitare:
appclient -client HelloServiceAppClient.jar http://localhost:1024/hello-ejb/hello

(si noti che l'URL è differente in quanto riportato nel tutorial, perché in questo caso stiamo provando il client con il servizio precedentemente realizzato e non con il servizio JAX-RPC utilizzato nel tutorial).

Il risultato del testo è presente in figura 19.

Figura 19 - Output del client J2EE

Conclusioni
Durante questo lungo tutorial si è visto quali sono i passaggi indispensabili per realizzare un servizio Web ed un client J2EE. Sebbene sia necessario l'uso estensivo di strumenti di amministrazione, l'approccio non è estremamente complesso, anche se si deve considerare che in queste semplici applicazioni di prova era presente un solo servizio, aspetto che facilita sicuramente la configurazione dei wizard.

Riferimenti
[1] Web Services e J2EE, parte I, Mokabyte settembre 2003
[2] Corso di Java Web Services, IIV parte: JAX-RPC, http://www.mokabyte.com/2003/06/jws-5.htm
[3] J2EE 1.4 Tutorial, http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html