Introduction à JAX-WS

1. Vue d'ensemble

L'API Java pour les services Web XML (JAX-WS) est une API normalisée permettant de créer et de consommer des services Web SOAP (Simple Object Access Protocol).

Dans cet article, nous allons créer un service Web SOAP et nous y connecter à l'aide de JAX-WS.

2. SAVON

SOAP est une spécification XML pour l'envoi de messages sur un réseau. Les messages SOAP sont indépendants de tout système d'exploitation et peuvent utiliser une variété de protocoles de communication, notamment HTTP et SMTP.

SOAP est lourd en XML, il est donc préférable de l'utiliser avec des outils / frameworks. JAX-WS est un framework qui simplifie l'utilisation de SOAP. Il fait partie de Java standard.

3. De haut en bas ou de bas en haut

Il existe deux façons de créer des services Web SOAP. Nous pouvons opter pour une approche descendante ou ascendante.

Dans une approche descendante (contrat d'abord), un document WSDL est créé et les classes Java nécessaires sont générées à partir du WSDL. Dans une approche ascendante (contrat-dernier), les classes Java sont écrites et le WSDL est généré à partir des classes Java.

L'écriture d'un fichier WSDL peut être assez difficile en fonction de la complexité de votre service Web. Cela rend l'approche ascendante une option plus facile. D'un autre côté, puisque votre WSDL est généré à partir des classes Java, toute modification de code peut entraîner une modification du WSDL. Ce n'est pas le cas pour l'approche descendante.

Dans cet article, nous examinerons les deux approches.

4. Langage de définition des services Web (WSDL)

WSDL est une définition de contrat des services disponibles. Il s'agit d'une spécification des messages d'entrée / sortie et de la manière d'appeler le service Web. Il est indépendant du langage et est défini en XML.

Regardons les principaux éléments d'un document WSDL.

4.1. Définitions

L' élément de définitions est l'élément racine de tous les documents WSDL. Il définit le nom, l'espace de noms, etc. du service et, comme vous pouvez le voir, peut être assez spacieux:

 ... 

4.2. Les types

L' élément types définit les types de données utilisés par le service Web. WSDL utilise XSD (XML Schema Definition) comme système de type qui aide à l'interopérabilité:

 ...      ... 

4.3. messages

L' élément de message fournit une définition abstraite des données transmises. Chaque élément de message décrit l'entrée ou la sortie d'une méthode de service et les exceptions possibles:

 ...          ... 

4.4. Opérations et types de ports

L' élément portType décrit chaque opération qui peut être effectuée et tous les éléments de message impliqués. Par exemple, l' opération getEmployee spécifie l' entrée de demande , la sortie et l' exception d' erreur possible levée par l' opération de service Web :

 ...       ....  ...  

4.5. Fixations

L' élément de liaison fournit des détails de protocole et de format de données pour chaque portType :

 ...               ...  ... 

4.6. Services et ports

L' élément service définit les ports pris en charge par le service Web. L' élément port en service définit le nom , la liaison et l' adresse du service:

 ...      ... 

5. Approche descendante (contrat d'abord)

Commençons par une approche descendante en créant un fichier WSDL Employeeservicetopdown.wsdl. Par souci de simplicité, il n'a qu'une seule méthode:

5.1. Génération de fichiers source de service Web à partir de WSDL

Il existe plusieurs façons de générer des fichiers source de service Web à partir d'un document WSDL.

Une façon est d'utiliser l' outil wsimport qui fait partie de JDK (à $ JAVA_HOME / bin) jusqu'au JDK 8.

À partir de l'invite de commande:

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

Options de ligne de commande utilisées: -p spécifie le package cible. -s spécifie où placer les fichiers source générés.

Pour les versions ultérieures de JDK, nous pouvons utiliser jaxws-maven-plugin de MojoHaus comme décrit ici.

Sinon, org.jvnet.jaxb2 « s maven-plugin-jaxb2 peut être utile comme détaillé dans Invoquer un service Web SOAP au printemps.

Les fichiers générés:

  • EmployeeServiceTopDown.java - est l'interface de point de terminaison de service (SEI) qui contient des définitions de méthode
  • ObjectFactory.java - contient des méthodes d'usine pour créer des instances de classes dérivées de schéma par programmation
  • EmployeeServiceTopDown_Service.java - est la classe de fournisseur de services qui peut être utilisée par un client JAX-WS

5.2. Interface de point de terminaison de service Web

L' outil wsimport a généré l'interface de point de terminaison de service Web EmployeeServiceTopDown . Il déclare les méthodes du service 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. Implémentation de service Web

L' outil wsimport a créé la structure du service Web. Nous devons créer l'implémentation du service 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. Approche ascendante (contrat-dernier)

Dans une approche ascendante, nous devons créer à la fois l'interface de point de terminaison et les classes d'implémentation. Le WSDL est généré à partir des classes lorsque le service Web est publié.

Let's create a web service that will perform simple CRUD operations on Employee data.

6.1. The Model Class

The Employee model class:

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

6.2. Web Service Endpoint Interface

The web service endpoint interface which declares the web service methods:

@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); // ... }

This interface defines an abstract contract for the web service. The annotations used:

  • @WebService denotes that it is a web service interface
  • @WebMethod is used to customize a web service operation
  • @WebResult is used to customize name of the XML element that represents the return value

6.3. Web Service Implementation

The implementation class of the web service endpoint interface:

@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. Publishing the Web Service Endpoints

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 générée encapsule la logique pour obtenir le port du serveur à l'aide d' URL et de QName .

8.2. Connexion au service Web

Le client de service Web utilise le EmployeeService_Service généré pour se connecter au serveur et effectuer des appels de service Web à distance:

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. Conclusion

Cet article est une introduction rapide aux services Web SOAP utilisant JAX-WS .

Nous avons utilisé les approches ascendante et descendante pour créer des services Web SOAP à l'aide de l'API JAX-WS. Nous avons également écrit un client JAX-WS qui peut se connecter à distance au serveur et passer des appels de service Web.

Le code source complet est disponible à l'adresse over sur GitHub.