Introduzione a JAX-WS

1. Panoramica

L'API Java per i servizi Web XML (JAX-WS) è un'API standardizzata per la creazione e l'utilizzo di servizi Web SOAP (Simple Object Access Protocol).

In questo articolo creeremo un servizio Web SOAP e ci collegheremo ad esso utilizzando JAX-WS.

2. SAPONE

SOAP è una specifica XML per l'invio di messaggi su una rete. I messaggi SOAP sono indipendenti da qualsiasi sistema operativo e possono utilizzare una varietà di protocolli di comunicazione tra cui HTTP e SMTP.

SOAP è pesante XML, quindi è meglio utilizzato con strumenti / framework. JAX-WS è un framework che semplifica l'utilizzo di SOAP. Fa parte dello standard Java.

3. Dall'alto verso il basso e dal basso verso l'alto

Esistono due modi per creare servizi Web SOAP. Possiamo optare per un approccio dall'alto verso il basso o dal basso verso l'alto.

In un approccio top-down (contratto prima), viene creato un documento WSDL e le classi Java necessarie vengono generate dal WSDL. In un approccio bottom-up (contratto-last), le classi Java vengono scritte e il WSDL viene generato dalle classi Java.

Scrivere un file WSDL può essere piuttosto difficile a seconda della complessità del tuo servizio web. Ciò rende l'approccio dal basso verso l'alto un'opzione più semplice. D'altra parte, poiché il WSDL è generato dalle classi Java, qualsiasi modifica nel codice potrebbe causare una modifica nel WSDL. Questo non è il caso dell'approccio top-down.

In questo articolo daremo uno sguardo a entrambi gli approcci.

4. WSDL (Web Services Definition Language)

WSDL è una definizione del contratto dei servizi disponibili. È una specifica dei messaggi di input / output e di come richiamare il servizio Web. È indipendente dal linguaggio ed è definito in XML.

Diamo un'occhiata agli elementi principali di un documento WSDL.

4.1. Definizioni

L' elemento delle definizioni è l'elemento radice di tutti i documenti WSDL. Definisce il nome, lo spazio dei nomi, ecc. Del servizio e, come puoi vedere, può essere abbastanza spazioso:

 ... 

4.2. Tipi

L' elemento types definisce i tipi di dati utilizzati dal servizio web. WSDL utilizza XSD (XML Schema Definition) come sistema di tipi che aiuta con l'interoperabilità:

 ...      ... 

4.3. Messaggi

L' elemento message fornisce una definizione astratta dei dati trasmessi. Ogni elemento del messaggio descrive l'input o l'output di un metodo di servizio e le possibili eccezioni:

 ...          ... 

4.4. Operazioni e tipi di porte

L' elemento portType descrive ogni operazione che può essere eseguita e tutti gli elementi del messaggio coinvolti. Ad esempio, il getEmployee operazione specifica la richiesta di ingresso , uscita e l'eventuale guasto eccezione generata dal servizio web funzionamento :

 ...       ....  ...  

4.5. Binding

L' elemento binding fornisce dettagli sul protocollo e sul formato dati per ogni portType :

 ...               ...  ... 

4.6. Servizi e porti

L' elemento service definisce le porte supportate dal servizio web. L' elemento port in service definisce il nome , il binding e l' indirizzo del servizio:

 ...      ... 

5. Approccio dall'alto verso il basso (primo contratto)

Iniziamo con un approccio dall'alto verso il basso creando un file WSDL dipendentiervicetopdown.wsdl. Per semplicità, ha un solo metodo:

5.1. Generazione di file di origine del servizio Web da WSDL

Esistono diversi modi per generare file di origine del servizio Web da un documento WSDL.

Un modo è utilizzare lo strumento wsimport che fa parte di JDK (a $ JAVA_HOME / bin) fino a JDK 8.

Dal prompt dei comandi:

wsimport -s . -p com.baeldung.jaxws.server.topdown employeeservicetopdown.wsdl

Opzioni della riga di comando utilizzate: -p specifica il pacchetto di destinazione. -s specifica dove mettere i file sorgente generati.

Per le versioni successive di JDK, possiamo usare jaxws-maven-plugin di MojoHaus come descritto qui.

In alternativa, org.jvnet.jaxb2 's Maven-jaxb2-plugin può rivelarsi utile come dettagliato nella Invocare un servizio Web SOAP in primavera.

I file generati:

  • EmployeeServiceTopDown.java : è l'interfaccia SEI (Service Endpoint Interface) che contiene le definizioni dei metodi
  • ObjectFactory.java : contiene metodi factory per creare istanze di classi derivate dallo schema a livello di codice
  • EmployeeServiceTopDown_Service.java : è la classe del provider di servizi che può essere utilizzata da un client JAX-WS

5.2. Interfaccia endpoint del servizio Web

Lo strumento wsimport ha generato l'interfaccia dell'endpoint del servizio Web EmployeeServiceTopDown . Dichiara i metodi del servizio web:

@WebService( name = "EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) @XmlSeeAlso({ ObjectFactory.class }) public interface EmployeeServiceTopDown { @WebMethod( action = "//topdown.server.jaxws.baeldung.com/" + "EmployeeServiceTopDown/countEmployees") @WebResult( name = "countEmployeesResponse", targetNamespace = "//topdown.server.jaxws.baeldung.com/", partName = "parameters") public int countEmployees(); }

5.3. Implementazione del servizio Web

Lo strumento wsimport ha creato la struttura del servizio web. Dobbiamo creare l'implementazione del servizio web:

@WebService( name = "EmployeeServiceTopDown", endpointInterface = "com.baeldung.jaxws.server.topdown.EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") public class EmployeeServiceTopDownImpl implements EmployeeServiceTopDown { @Inject private EmployeeRepository employeeRepositoryImpl; @WebMethod public int countEmployees() { return employeeRepositoryImpl.count(); } }

6. Approccio dal basso verso l'alto (contratto-ultimo)

In un approccio dal basso verso l'alto, dobbiamo creare sia l'interfaccia endpoint che le classi di implementazione. Il WSDL viene generato dalle classi quando il servizio Web viene pubblicato.

Creiamo un servizio web che eseguirà semplici operazioni CRUD sui dati dei dipendenti .

6.1. La classe del modello

La classe del modello Employee :

public class Employee { private int id; private String firstName; // standard getters and setters }

6.2. Interfaccia endpoint del servizio Web

L'interfaccia dell'endpoint del servizio Web che dichiara i metodi del servizio Web:

@WebService public interface EmployeeService { @WebMethod Employee getEmployee(int id); @WebMethod Employee updateEmployee(int id, String name); @WebMethod boolean deleteEmployee(int id); @WebMethod Employee addEmployee(int id, String name); // ... }

Questa interfaccia definisce un contratto astratto per il servizio web. Le annotazioni utilizzate:

  • @WebService denota che si tratta di un'interfaccia di servizio web
  • @WebMethod viene utilizzato per personalizzare un'operazione di servizio Web
  • @WebResult viene utilizzato per personalizzare il nome dell'elemento XML che rappresenta il valore restituito

6.3. Implementazione del servizio Web

La classe di implementazione dell'interfaccia dell'endpoint del servizio Web:

@WebService(endpointInterface = "com.baeldung.jaxws.EmployeeService") public class EmployeeServiceImpl implements EmployeeService { @Inject private EmployeeRepository employeeRepositoryImpl; @WebMethod public Employee getEmployee(int id) { return employeeRepositoryImpl.getEmployee(id); } @WebMethod public Employee updateEmployee(int id, String name) { return employeeRepositoryImpl.updateEmployee(id, name); } @WebMethod public boolean deleteEmployee(int id) { return employeeRepositoryImpl.deleteEmployee(id); } @WebMethod public Employee addEmployee(int id, String name) { return employeeRepositoryImpl.addEmployee(id, name); } // ... }

7. Pubblicazione degli endpoint del servizio Web

To publish the web services (top-down and bottom-up), we need to pass an address and an instance of the web service implementation to the publish() method of the javax.xml.ws.Endpoint class:

public class EmployeeServicePublisher { public static void main(String[] args) { Endpoint.publish( "//localhost:8080/employeeservicetopdown", new EmployeeServiceTopDownImpl()); Endpoint.publish("//localhost:8080/employeeservice", new EmployeeServiceImpl()); } }

We can now run EmployeeServicePublisher to start the web service. To make use of CDI features, the web services can be deployed as WAR file to application servers like WildFly or GlassFish.

8. Remote Web Service Client

Let's now create a JAX-WS client to connect to the EmployeeService web service remotely.

8.1. Generating Client Artifacts

To generate JAX-WS client artifacts, we can once again use the wsimport tool:

wsimport -keep -p com.baeldung.jaxws.client //localhost:8080/employeeservice?wsdl

La classe EmployeeService_Service generata incapsula la logica per ottenere la porta del server utilizzando URL e QName .

8.2. Connessione al servizio Web

Il client del servizio Web utilizza EmployeeService_Service generato per connettersi al server ed effettuare chiamate al servizio Web in remoto:

public class EmployeeServiceClient { public static void main(String[] args) throws Exception { URL url = new URL("//localhost:8080/employeeservice?wsdl"); EmployeeService_Service employeeService_Service = new EmployeeService_Service(url); EmployeeService employeeServiceProxy = employeeService_Service.getEmployeeServiceImplPort(); List allEmployees = employeeServiceProxy.getAllEmployees(); } }

9. Conclusione

Questo articolo è una rapida introduzione ai servizi Web SOAP che utilizzano JAX-WS .

Abbiamo utilizzato l'approccio bottom-up e top-down per creare servizi Web SOAP utilizzando l'API JAX-WS. Abbiamo anche scritto un client JAX-WS che può connettersi in remoto al server ed effettuare chiamate al servizio web.

Il codice sorgente completo è disponibile su GitHub.