Introdução ao JAX-WS

1. Visão geral

Java API for XML Web Services (JAX-WS) é uma API padronizada para criar e consumir serviços da web SOAP (Simple Object Access Protocol).

Neste artigo, criaremos um serviço da web SOAP e nos conectaremos a ele usando JAX-WS.

2. SOAP

SOAP é uma especificação XML para o envio de mensagens em uma rede. SOAP messages are independent of any operating system and can use a variety of communication protocols including HTTP and SMTP.

O SOAP é pesado para XML, portanto, melhor usado com ferramentas / estruturas. O JAX-WS é uma estrutura que simplifica o uso do SOAP. Faz parte do Java padrão.

3. De cima para baixo vs. Baixo para cima

Existem duas maneiras de criar serviços da web SOAP. Podemos seguir uma abordagem de cima para baixo ou de baixo para cima.

Em uma abordagem de cima para baixo (contrato primeiro), um documento WSDL é criado e as classes Java necessárias são geradas a partir do WSDL. Em uma abordagem ascendente (último contrato),the Java classes are written, and the WSDL is generated from the Aulas Java.

Writing a WSDL file can be quite difficult depending on how complex your web service is. This makes the bottom-up approach an easier option. Por outro lado, como seu WSDL é gerado a partir das classes Java, qualquer mudança no código pode causar uma mudança no WSDL. Este não é o caso da abordagem de cima para baixo.

Neste artigo, daremos uma olhada em ambas as abordagens.

4. Linguagem de definição de serviços da Web (WSDL)

WSDL é uma definição de contrato dos serviços disponíveis. É uma especificação de mensagens de entrada / saída e como chamar o serviço da web. É neutro em termos de linguagem e é definido em XML.

Vejamos os principais elementos de um documento WSDL.

4.1. Definições

O elementodefinitions é o elemento raiz de todos os documentos WSDL. Ele define o nome, o espaço para nome, etc. do serviço e, como você pode ver, pode ser bastante espaçoso:

...

4.2. Tipos

O elementotypes define os tipos de dados usados pelo serviço da web. WSDL usaXSD (XML Schema Definition) como o sistema de tipo que ajuda na interoperabilidade:

4.3. Mensagens

O elementomessage fornece uma definição abstrata dos dados que estão sendo transmitidos. Cada elementomessage descreve a entrada ou saída de um método de serviço e as possíveis exceções:

4.4. Operações e tipos de portas

O elementoportType descreve cadaoperation que pode ser executado e todos os elementosmessage envolvidos. Por exemplo, a operaçãogetEmployee especifica a solicitaçãoinput,outpute possívelfault exceção lançada pelo serviço da weboperation:

4.5. Ligações

O elementobinding fornece detalhes de protocolo e formato de dados para cadaportType:

4.6. Serviços e Portos

O elementoservice define as portas suportadas pelo serviço da web. O elementoport emservice definename,bindingeaddress do serviço:

5. Abordagem de cima para baixo (contrato primeiro)

Vamos começar com uma abordagem de cima para baixo criando um arquivo WSDLemployeeservicetopdown.wsdl. Por razões de simplicidade, ele tem apenas um método:

5.1. Gerando Arquivos de origem de serviço da Web de WSDL

Para gerar arquivos de origem de serviço da web a partir de um documento WSDL, podemos usar a ferramentawsimport que faz parte do JDK (em$JAVA_HOME / bin).

No prompt de comando:

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

Opções de linha de comando usadas:-p especifica o pacote de destino. -s especifica onde colocar os arquivos de origem gerados.

Os arquivos gerados:

EmployeeServiceTopDown.java - é a interface de terminal de serviço (SEI) que contém definições de método
ObjectFactory.java - contém métodos de fábrica para criar instâncias de classes derivadas de esquema programaticamente
EmployeeServiceTopDown_Service.java - é a classe do provedor de serviços que pode ser usada por um cliente JAX-WS

5.2. Interface de terminal de serviço da web

A ferramentawsimport gerou a interface de terminal de serviço da webEmployeeServiceTopDown. Declara os métodos de serviço da web:

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

5.3. Implementação de Serviço da Web

A ferramentawsimport criou a estrutura do serviço da web. Temos que criar a implementação do serviço web:

@WebService(
  name = "EmployeeServiceTopDown",
  endpointInterface = "com.example.jaxws.server.topdown.EmployeeServiceTopDown",
  targetNamespace = "http://topdown.server.jaxws.example.com/")
public class EmployeeServiceTopDownImpl
  implements EmployeeServiceTopDown {

    @Inject
    private EmployeeRepository employeeRepositoryImpl;

    @WebMethod
    public int countEmployees() {
        return employeeRepositoryImpl.count();
    }
}

6. Abordagem ascendente (contrato-último)

Em uma abordagem de baixo para cima, precisamos criar a interface do terminal e as classes de implementação. O WSDL é gerado a partir das classes quando o serviço da web é publicado.

Vamos criar um serviço da web que realizará operações simples de CRUD nos dadosEmployee.

6.1. A classe modelo

A classe do modeloEmployee:

public class Employee {
    private int id;
    private String firstName;

    // standard getters and setters
}

6.2. Interface de terminal de serviço da web

A interface do terminal de serviço da web que declara os métodos de serviço da 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);

    // ...
}

Essa interface define um contrato abstrato para o serviço da web. As anotações usadas:

@WebService denota que é uma interface de serviço da web
@WebMethod é usado para personalizar uma operação de serviço da web
@WebResult é usado para personalizar o nome do elemento XML que representa o valor de retorno

6.3. Implementação de Serviço da Web

A classe de implementação da interface do terminal do serviço da web:

@WebService(endpointInterface = "com.example.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. Publicando os pontos de extremidade de serviço da Web

Para publicar os serviços da web (de cima para baixo e de baixo para cima), precisamos passar um endereço e uma instância da implementação do serviço da web para o métodopublish() da classejavax.xml.ws.Endpoint:

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

        Endpoint.publish("http://localhost:8080/employeeservice",
          new EmployeeServiceImpl());
    }
}

Agora podemos executarEmployeeServicePublisher para iniciar o serviço da web. Para usar os recursos do CDI, os serviços da web podem ser implementados como arquivo WAR em servidores de aplicativos como WildFly ou GlassFish.

8. Cliente de serviço remoto da web

Vamos agora criar um cliente JAX-WS para se conectar ao serviço da webEmployeeService remotamente.

8.1. Gerando artefatos de cliente

Para gerar artefatos de cliente JAX-WS, podemos usar novamente a ferramentawsimport:

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

A classeEmployeeService_Service gerada encapsula a lógica para obter a porta do servidor usandoURLeQName.

8.2. Conectando-se ao serviço da Web

O cliente de serviço da web usa oEmployeeService_Service gerado para se conectar ao servidor e fazer chamadas de serviço da web remotamente:

public class EmployeeServiceClient {
    public static void main(String[] args) throws Exception {
        URL url = new URL("http://localhost:8080/employeeservice?wsdl");

        EmployeeService_Service employeeService_Service
          = new EmployeeService_Service(url);
        EmployeeService employeeServiceProxy
          = employeeService_Service.getEmployeeServiceImplPort();

        List allEmployees
          = employeeServiceProxy.getAllEmployees();
    }
}

9. Conclusão

Este artigo éa quick introduction to SOAP Web services using JAX-WS.

Usamos as abordagens de baixo para cima e de cima para baixo para criar serviços da Web SOAP usando a API JAX-WS. Também criamos um cliente JAX-WS que pode se conectar remotamente ao servidor e fazer chamadas de serviço da web.

O código-fonte completo está disponívelover on GitHub.

TOC

Introdução ao JAX-WS