Desenvolvendo Serviços da Web JAX-WS com Anotações

O Java™ API for XML-Based Web Services (JAX-WS) suporta dois tipos diferentes de implementações de terminal em serviço, a interface de terminal da web em serviço padrão e uma nova interface de Provedor para permitir que os serviços trabalhem no nível de mensagem XML. Usando anotações na implementação do terminal em serviço ou cliente, é possível definir o terminal em serviço como um serviço da Web.

Sobre Esta Tarefa

Essa tarefa é uma etapa obrigatória para desenvolver serviços da Web JAX-WS.

A tecnologia JAX-WS suporta a implementação de serviços da Web baseados em ambas as interfaces, de terminal de serviço padrão e de um Provedor Terminais JAX-WS são como implementações de terminal na especificação Java API for XML-based RPC (JAX-RPC). Diferentemente do JAX-RPC, o requisito para uma service endpoint interface (SEI) é opcional para serviços da Web JAX-WS. Os serviços JAX-WS que não possuem uma SEI associada são considerados portadores de uma SEI implícita, enquanto que os serviços que possuem uma SEI associada são considerados portadores de uma SEI explícita. As interfaces do terminal em serviço requeridas pelo JAX-WS também são mais genéricas do que as interfaces de terminal em serviço requeridas pelo JAX-RPC. Com o JAX-WS, o SEI não precisa estender a interface java.rmi.Remote, conforme necessário pela especificação JAX-RPC.

O modelo de programação JAX-WS também usa suporte para anotação de classes Java com metadados para definir uma implementação de terminal em serviço com um serviço da Web e definir como um cliente pode acessar o serviço da Web. O JAX-WS suporta anotações com base no Recurso de Metadados para a especificação de Linguagem de Programação Java (JSR 175), Metadados de Serviços da Web para a especificação Java Platform (JSR 181) e anotações definidas pela especificação JAX-WS 2.0 (JSR 224), que inclui anotações do Java Architecture for XML Binding (JAXB). Usando anotações, a implementação de terminal em serviço pode descrever independentemente o serviço da Web sem requerer um arquivo WSDL. As anotações podem fornecer todas as informações de WSDL necessárias para configurar a implementação do seu terminal em serviço ou cliente de serviços da Web. É possível especificar anotações na interface do terminal em serviço utilizada pelo cliente e pelo servidor ou na classe de implementação de serviço do lado do servidor.

Para obter detalhes quanto aos padrões e especificações suportados, consulte as especificações de serviços da Web e a documentação da API.

Ao desenvolver um serviço da Web JAX-WS que inicia a partir de classes Java existentes, conhecido como abordagem ascendente, você deve anotar a classe com a anotação @WebService (javax.jws.WebService) ou @WebServiceProvider (javax.xml.ws.Provider) para definir inicialmente a classe como um serviço da Web. A anotação @WebService define o serviço como um terminal baseado no SEI, enquanto a anotação @WebServiceProvider define o serviço como um terminal baseado em Provedor.

Desenvolva serviços da Web JAX-WS baseados em SEI

Para um terminal baseado em SEI, a service endpoint interface (SEI), seja uma classe Java ou uma interface Java, declara os método de negócios fornecidos por um serviço da Web particular. Os únicos métodos que um cliente de serviços da Web pode chamar em um terminal JAX-WS são os métodos de negócios definidos na SEI explícita ou implícita.

Todos os terminais baseados no SEI precisam ter a anotação @WebService incluída na classe de implementação. Se a implementação de serviço usar o SEI explícito, essa interface deverá ser referenciada pelo atributo endpointInterface na anotação @WebService. Se a implementação de serviço não usar uma SEI explícita, o serviço será descrito implicitamente pela classe de implementação e será uma SEI implícita.

Desenvolva serviços da Web JAX-WS usando a interface de Provedor

O modelo de programação JAX-WS apresenta a interface do Provedor para os terminais do Provedor, javax.xml.ws.Provider, como uma alternativa dinâmica para os terminais baseados no SEI. A interface do Provedor suporta uma abordagem mais orientada para sistema de mensagens para os serviços da Web. Com a interface do Provedor, você pode criar uma classe Java que implementa uma interface simples para produzir uma classe de implementação de serviço genérica. A interface do Provedor define um método, invoke, que usa genéricos para controlar os tipos de entrada e saída ao trabalhar com várias mensagens ou cargas úteis da mensagem. Todos os terminais do Provedor devem ser anotados com a anotação @WebServiceProvider (javax.xml.ws.WebServiceProvider). Uma implementação de serviço não pode especificar a anotação @WebService se ela implementar a interface javax.xml.ws.Provider.

A partir do WebSphere Application Server Versão 7.0 e posterior, nos módulos do aplicativo Java EE 5 (módulos de aplicativo da web versão 2.5 ou superior, ou módulos EJB versão 3.0 ou superior) ocorre a varredura de anotações para identificação de serviços e clientes JAX-WS. Entretanto, os módulos aplicativos pré-Java EE 5 (módulos aplicativos da web versão 2.4 ou anterior, ou módulos EJB versão 2.1 ou anterior) não são digitalizados para anotações JAX-WS, por padrão, para considerações de desempenho. No Feature Pack for Web Services Versão 6.1, o comportamento padrão é digitalizar módulos aplicativos da web pré-Java EE 5 para identificar serviços JAX-WS e digitalizar módulos aplicativos da web pré-Java EE 5 e módulos EJB para clientes de serviço durante a instalação do aplicativo. Como o comportamento padrão para o WebSphere Application Server Versão 7.0 e mais recente é não varrer módulos pré-Java EE 5 para anotações durante a instalação do aplicativo ou inicialização do servidor, para preservar a compatibilidade com versões anteriores com o feature pack de liberações anteriores, deve-se configurar a propriedade UseWSFEP61ScanPolicy no META-INF/MANIFEST.MF de um arquivo web application archive (WAR) ou módulo EJB ou definir a propriedade customizada de Java virtual machine, com.ibm.websphere.webservices.UseWSFEP61ScanPolicy, em servidores para solicitar varredura durante a instalação do aplicativo e inicialização do servidor. Para aprender mais sobre a varredura de anotações, consulte as informações de anotações do JAX-WS.

Procedimento

  1. Determine se você deseja definir os seus serviços da Web usando terminais SEI ou a interface do Provedor. Se preferir uma abstração centrada em Java de alto nível que oculte os detalhes da conversão entre objetos Java e sua representação XML, considere usar terminais baseados em SEI para desenvolver seus serviços da Web. Porém, se preferir que o seu serviço da Web opere mais no nível de mensagem XML, considere usar terminais baseados em Provedor.
  2. Anote os terminais de serviço.
    1. Anote o terminal baseado no SEI com a anotação javax.jws.WebService.
      • Para um terminal baseado no SEI, anote a classe de implementação com a anotação javax.jws.WebService. É possível escolher referenciar explicitamente uma interface de terminal em serviço ao definir o atributo @WebService.endpointInterface, que especifica esse terminal como um SEI explícito. Nesse caso, a interface Java que é referenciada também deve conter a anotação javax.jws.WebService. Se o atributo endpointInterface não estiver definido ou estiver vazio, o bean de implementação será considerado um SEI implícito. É possível incluir a anotação @WebMethod nos métodos de uma interface de terminal em serviço para customizar os mapeamentos Java-para-WSDL. Todos os métodos públicos são considerados métodos expostos, independente se a anotação @WebMethod for especificada. É incorreto ter uma anotação @WebMethod em uma interface de terminal em serviço que contenha o atributo exclude.
      • Se usar um SEI implícito, poderá aplicar controle mais granular sobre como os métodos são expostos por meio do uso seletivo da anotação @WebMethod. Para uma explicação mais detalhada, consulte os métodos de exposição nas informações de serviços da Web JAX-WS baseados em SEI.
    2. Anote o terminal baseado em Provedor com a anotação javax.xml.ws.WebServiceProvider.
      • Para um terminal baseado em Provedor, anote a classe de implementação com a anotação javax.xml.ws.WebServiceProvider. Essa anotação deve ser especificada apenas em uma classe que implementa uma classe javax.xml.ws.Provider.interface fortemente tipada, como Provider<Source> ou Provider<SOAPMessage>, em contraste com uma classe que é ilimitada, como Provider<T>. Uma classe fortemente tipada é aquela que é associada a um tipo Java de entrada e saída específico, como Source ou SOAPMessage, por exemplo.
        @WebServiceProvider(
                serviceName="StringProviderService", 
                wsdlLocation="META-INF/echostring.wsdl", 
                targetNamespace="http://stringprovider.sample.test.org")
      • (opcional) De acordo com a especificação JAX-WS 2.2, se estiver definindo um terminal baseado em Provedor para que a implementação de Provedor retorne um valor nulo, nenhuma resposta é necessária. Se a anotação javax.xml.ws.WebServiceProvider não especificar um WSDL e o método invoke() do Provedor retornar um valor nulo, o comportamento padrão do ambiente de tempo de execução JAX-WS é retornar uma resposta que consiste de um SOAPEnvelope que contenha um SOAPBody vazio. É possível configurar a propriedade JVM, jaxws.provider.interpretNullAsOneway, para true se desejar que o ambiente de tempo de execução JAX-WS interprete esse cenário como uma operação somente solicitação e que não retorne nenhuma resposta.
  3. Entenda e aplica as boas práticas para os métodos de exposição como operações em serviços da Web JAX-WS baseados em SEI.

    Devido às ambiguidades nas diversas especificações de serviços da Web quanto a como os métodos são expostos como operações de serviços da Web para terminais baseados sem SEI, é possível assegurar comportamento consistente seguindo as boas práticas, independentemente da implementação JAX-WS que você usar.

Resultados

Você definiu a implementação do terminal em serviço que representa a aplicação dos serviços da Web. Consulte a documentação de anotações JAX-WS para saber mais sobre as anotações JAX-WS suportadas.

Interface e Implementação de Terminal em Serviço JavaBeans de Amostra

O seguinte exemplo ilustra uma implementação de terminal em serviço JavaBeans e a interface de terminal em serviço associada:
/** This is an excerpt from the service implementation file, EchoServicePortTypeImpl.java. 
package com.ibm.was.wssample.echo;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.Marshaller;
import javax.xml.bind.Unmarshaller;
import javax.xml.transform.stream.StreamSource;

@javax.jws.WebService(serviceName = "EchoService", endpointInterface = 
"com.ibm.was.wssample.echo.EchoServicePortType", targetNamespace="http://com/ibm/was/wssample/echo/", 
portName="EchoServicePort")
public class EchoServicePortTypeImpl implements EchoServicePortType {

                public EchoServicePortTypeImpl() {
                }

                public String echo(String obj) {
                        String str;
                        ....
                        str = obj;
                        ....
                        
                        return str;

                }

}
/**  Esta é uma amostra da interface de serviço EchoServicePortType.java. */

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.xml.ws.*;


@WebService(name = "EchoServicePortType", targetNamespace = "http://com/ibm/was/wssample/echo/", 
wsdlLocation="WEB-INF/wsdl/Echo.wsdl")
public interface EchoServicePortType {


    /** ...the method process ...*/
        @WebMethod

}
O exemplo a seguir ilustra uma interface de terminal em serviço do Provedor simples para uma classe Java:
package jaxws.provider.source;

import javax.xml.ws.Provider;
import javax.xml.ws.WebServiceProvider;
import javax.xml.transform.Source;

@WebServiceProvider()
public class SourceProvider implements Provider<Source> {

    public Source echo(Source data) {
        return data;
    }
}

No exemplo de implementação do provedor, o tipo javax.xml.transform.Source é especificado no método <Origem> genérico. O método <Source> genérico especifica que os tipos de entrada e saída são objetos Source.

O que Fazer Depois

Desenvolva artefatos Java para aplicativos JAX-WS a partir de JavaBeans. Para saber mais, consulte as informações sobre como gerar artefatos Java para aplicativos JAX-WS.


Ícone que indica o tipo de tópico Tópico de Tarefa



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_devjaxwsendpt
Nome do arquivo: twbs_devjaxwsendpt.html