Создание простого веб-сервиса и клиентов с JAX-WS

В этом разделе показано, как собрать и развернуть простой веб-сервис и два клиента: консольный клиент и веб-клиент. Исходный код сервиса находится в каталоге tut-install/examples/jaxws/helloservice-war/, а клиенты — в каталогах tut-install/examples/jaxws/hello-appclient/ и tut-install/examples/jaxws/hello-webclient/.

Рисунок 31-1 иллюстрирует, как технология JAX-WS управляет связью между веб-сервисом и клиентом.

Рисунок 31-1. Связь между веб-сервисом JAX-WS и клиентом

Диаграмма, показывающая связь клиента и веб-сервиса с помощью сообщения SOAP.

Отправной точкой для разработки веб-сервиса JAX-WS является класс Java, аннотированный javax.jws.WebService. Аннотация @WebService определяет класс как конечную точку веб-сервиса.

Интерфейс конечной точки сервиса или реализация конечной точки сервиса (SEI) — это соответственно интерфейс или класс Java, объявляющий методы, которые клиент может вызывать у сервиса. Интерфейс не требуется при создании конечной точки JAX-WS. Класс реализации веб-сервиса неявно определяет SEI.

Можно указать явный интерфейс, добавив элемент endpointInterface в аннотацию @WebService в классе реализации. Затем нужно предоставить интерфейс, который определяет публичные методы, доступные в классе реализации конечной точки.

Основные шаги для создания веб-сервиса и клиента

Основные шаги для создания веб-сервиса и клиента следующие.

Закодируйте класс реализации.
Скомпилируйте класс реализации.
Упакуйте файлы в WAR-файл.
Разверните WAR-файл. Артефакты веб-сервиса, используемые для связи с клиентами, создаются сервером GlassFish во время развёртывания.
Закодируйте клиентский класс.
Используйте цель Maven wsimport для генерации и компиляции артефактов веб-сервиса, необходимых для подключения к сервису.
Скомпилируйте клиентский класс.
Запустите клиент.

Если вы используете IDE NetBeans для создания сервиса и клиента, среда разработки выполняет задачу wsimport.

В следующих разделах эти шаги рассматриваются более подробно.

Требования к конечной точке JAX-WS

Конечные точки JAX-WS должны соответствовать этим требованиям.

Реализующий класс должен быть аннотирован javax.jws.WebService или javax.jws.WebServiceProvider.
Реализующий класс может явно ссылаться на SEI через элемент endpointInterface аннотации @WebService, но не обязательно. Если endpointInterface не указан в @WebService, SEI неявно определяется для реализующего класса.
Бизнес-методы реализующего класса должны быть публичными и не должны объявляться static или final.
Бизнес-методы, предоставляемые клиентам веб-сервисов, должны быть аннотированы javax.jws.WebMethod.
Бизнес-методы, предоставляемые клиентам веб-сервисов, должны иметь JAXB-совместимые параметры и типы возвращаемых данных. См. список привязок типов данных JAXB по умолчанию в разделе Типы, поддерживаемые JAX-WS.
Реализующий класс не должен быть объявлен final и не должен быть abstract.
Реализующий класс должен иметь публичный конструктор по умолчанию.
Реализующий класс не должен определять метод finalize.
Реализующий класс может использовать аннотации javax.annotation.PostConstruct или javax.annotation.PreDestroy в своих Callback-методах событий жизненного цикла.

Метод @PostConstruct вызывается контейнером до того, как реализующий класс начинает отвечать клиентам веб-сервиса.

Метод @PreDestroy вызывается контейнером перед удалением конечной точки.

Кодирование класса реализации конечной точки сервиса

В этом примере класс реализации Hello аннотируется как конечная точка веб-сервиса с помощью аннотации @WebService. Hello объявляет один метод с именем sayHello, аннотированный @WebMethod, который предоставляет аннотированный метод клиентам веб-сервиса. Метод sayHello возвращает приветствие клиенту, используя переданное ему имя для создания приветствия. Класс реализации также должен определять конструктор по умолчанию — публичный, без аргументов.

package javaeetutorial.helloservice;

import javax.jws.WebService;
import javax.jws.WebMethod;

@WebService
public class Hello {
    private final String message = "Hello, ";

    public Hello() {
    }

    @WebMethod
    public String sayHello(String name) {
        return message + name + ".";
    }
}

Сборка, упаковка и развёртывание сервиса

Вы можете использовать IDE NetBeans или Maven для сборки, упаковки и развёртывания приложения helloservice-war.

Здесь рассматриваются следующие темы:

Сборка, упаковка и развёртывание сервиса в IDE NetBeans
Сборка, упаковка и развёртывание сервиса с помощью Maven

Сборка, упаковка и развёртывание сервиса в IDE NetBeans

Удостоверьтесь, чтобы GlassFish Server был запущен (см. Запуск и остановка сервера GlassFish).
В меню «Файл» выберите «Открыть проект».
В диалоговом окне «Открыть проект» перейдите к:
```
tut-install/examples/jaxws
```
Выберите каталог helloservice-war.
Нажмите Открыть проект.
На вкладке «Проекты» кликните правой кнопкой мыши проект helloservice-war и выберите «Выполнить».

Эта команда собирает и упаковывает приложение в WAR-файл, helloservice-war.war, расположенный в tut-install/examples/jaxws/helloservice-war/target/ и развёртывает этот WAR-файл в GlassFish Server. Он также открывает интерфейс тестирования веб-сервиса по URL, указанному в Тестирование сервиса без клиента.

Дальнейшие шаги

Вы можете просмотреть WSDL-файл развёрнутого сервиса, запросив URL http://localhost:8080/helloservice-war/HelloService?wsdl в веб-браузере. Теперь вы готовы создать клиента, который обращается к этому сервису.

Сборка, упаковка и развёртывание сервиса с помощью Maven

Удостоверьтесь, чтобы GlassFish Server был запущен (см. Запуск и остановка сервера GlassFish).
В окне терминала перейдите в:
```
tut-install/examples/jaxws/helloservice-war/
```
Введите следующую команду:
```
mvn install
```
Эта команда собирает и упаковывает приложение в WAR-файл helloservice-war.war, расположенный в каталоге target, а затем развёртывает WAR на сервере GlassFish.

Дальнейшие шаги

Тестирование методов конечной точки веб-сервиса

Сервер GlassFish позволяет тестировать методы конечной точки веб-сервиса.

Здесь рассматриваются следующие темы:

Тестирование сервиса без клиента

Тестирование сервиса без клиента

Чтобы проверить метод sayHello в HelloService, выполните следующие действия.

Откройте интерфейс тестирования веб-сервиса, введя следующий URL в веб-браузере:
```
http://localhost:8080/helloservice-war/HelloService?Tester
```
В разделе Методы введите имя в качестве параметра метода sayHello.
Нажмите sayHello.

Вы перейдете на страницу вызова метода sayHello.

В разделе Method returned вы увидите ответ от конечной точки.

Простой консольный клиент JAX-WS

Класс HelloAppClient является консольным клиентом, который обращается к методу sayHello в HelloService. Этот вызов осуществляется через порт — локальный объект, который действует как прокси для удалённого сервиса. Порт создаётся во время разработки с помощью цели Maven wsimport, которая генерирует переносимые артефакты JAX-WS на основе имеющегося WSDL-файла.

Здесь рассматриваются следующие темы:

Кодирование консольного клиента
Запуск консольного клиента

Кодирование консольного клиента

При вызове удалённых методов порта клиент выполняет эти шаги.

Использует сгенерированный класс helloservice.endpoint.HelloService, который представляет сервис по URI WSDL-файла развёрнутого сервиса:

import javaeetutorial.helloservice.endpoint.HelloService;
import javax.xml.ws.WebServiceRef;

public class HelloAppClient {
    @WebServiceRef(wsdlLocation =
      "http://localhost:8080/helloservice-war/HelloService?WSDL")
    private static HelloService service;

Извлекает прокси для сервиса, также известный как порт, вызывая getHelloPort в сервисе:
```
javaeetutorial.helloservice.endpoint.Hello port = service.getHelloPort();
```
Порт реализует SEI, определённый сервисом.
Он вызывает метод sayHello порта, передавая строку сервису:
```
return port.sayHello(arg0);
```

Вот полный исходный код HelloAppClient.java, который находится в каталоге tut-install/examples/jaxws/hello-appclient/src/main/java/javaeetutorial/hello/appclient/:

package javaeetutorial.hello.appclient;

import javaeetutorial.helloservice.endpoint.HelloService;
import javax.xml.ws.WebServiceRef;

public class HelloAppClient {
    @WebServiceRef(wsdlLocation =
      "http://localhost:8080/helloservice-war/HelloService?WSDL")
    private static HelloService service;

    /**
     * @param args аргументы командной строки
     */
    public static void main(String[] args) {
       System.out.println(sayHello("world"));
    }

    private static String sayHello(java.lang.String arg0) {
        javaeetutorial.helloservice.endpoint.Hello port =
                service.getHelloPort();
        return port.sayHello(arg0);
    }
}

Запуск консольного клиента

Вы можете использовать IDE NetBeans или Maven для сборки, упаковки, развёртывания и запуска приложения hello-appclient. Чтобы собрать клиента, вы должны сначала развернуть helloservice-war, как описано в Сборка, упаковка и развёртывание сервиса.

Здесь рассматриваются следующие темы:

Запуск консольного клиента с IDE NetBeans

Запуск консольного клиента с IDE NetBeans

В меню «Файл» выберите «Открыть проект».
В диалоговом окне «Открыть проект» перейдите к:
```
tut-install/examples/jaxws
```
Выберите каталог hello-appclient.
Нажмите Открыть проект.
На вкладке «Проекты» кликните правой кнопкой мыши проект hello-appclient и выберите «Сборка».

Эта команда запускает цель wsimport, затем собирает, упаковывает и запускает клиент. Вы увидите выходные данные клиентского приложения на вкладке вывода hello-appclient:
```
--- exec-maven-plugin:1.2.1:exec (run-appclient) @ hello-appclient ---
Hello, world.
```

Запуск консольного клиента с помощью Maven

В окне терминала перейдите в:
```
tut-install/examples/jaxws/hello-appclient/
```
Введите следующую команду:
```
mvn install
```
Эта команда запускает цель wsimport, затем собирает, упаковывает и запускает клиент. Выходные данные клиентского приложения выглядят так:
```
--- exec-maven-plugin:1.2.1:exec (run-appclient) @ hello-appclient ---
Hello, world.
```

Простой веб-клиент JAX-WS

HelloServlet — это сервлет, который, подобно Java-клиенту, вызывает метод sayHello веб-сервиса. Как и клиентское приложение, он делает этот вызов через порт.

Здесь рассматриваются следующие темы:

Кодирование сервлета
Запуск веб-клиента

Кодирование сервлета

Чтобы вызвать метод для порта, клиент выполняет эти шаги.

Он импортирует конечную точку HelloService и аннотацию @WebServiceRef:
```
import javaeetutorial.helloservice.endpoint.HelloService;
...
import javax.xml.ws.WebServiceRef;
```
Он определяет ссылку на веб-сервис, указывая местоположение WSDL:
```
@WebServiceRef(wsdlLocation =
  "http://localhost:8080/helloservice-war/HelloService?WSDL")
```

Он объявляет веб-сервис, а затем определяет приватный метод, который вызывает метод sayHello для порта:

private HelloService service;
...
private String sayHello(java.lang.String arg0) {
    javaeetutorial.helloservice.endpoint.Hello port =
            service.getHelloPort();
    return port.sayHello(arg0);
}

В сервлете он вызывает этот приватный метод:
```
out.println("<p>" + sayHello("world") + "</p>");
```

Ниже приведены важные части кода HelloServlet. Код находится в каталоге tut-install/examples/jaxws/hello-webclient/src/java/javaeetutorial/hello/webclient/.

package javaeetutorial.hello.webclient;

import javaeetutorial.helloservice.endpoint.HelloService;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.xml.ws.WebServiceRef;

@WebServlet(name="HelloServlet", urlPatterns={"/HelloServlet"})
public class HelloServlet extends HttpServlet {
    @WebServiceRef(wsdlLocation =
      "http://localhost:8080/helloservice-war/HelloService?WSDL")
    private HelloService service;

    /**
     * Обработка как HTTP <code>GET</code>,
     *   так и <code>POST</code> запросов.
     * @param request объект запроса
     * @param response объект ответа
     * @throws ServletException ошибка, специфичная для сервлетов
     * @throws IOException ошибка ввода/вывода
     */
    protected void processRequest(HttpServletRequest request,
            HttpServletResponse response)
    throws ServletException, IOException {
        response.setContentType("text/html;charset=UTF-8");
        try (PrintWriter out = response.getWriter()) {

            out.println("<html lang=\"en\">");
            out.println("<head>");
            out.println("<title>Servlet HelloServlet</title>");
            out.println("</head>");
            out.println("<body>");
            out.println("<h1>Servlet HelloServlet at " +
                request.getContextPath () + "</h1>");
            out.println("<p>" + sayHello("world") + "</p>");
            out.println("</body>");
            out.println("</html>");
        }
    }

    // методы doGet and doPost methods, которые вызывают методы processRequest, and
    //   getServletInfo

    private String sayHello(java.lang.String arg0) {
        javaeetutorial.helloservice.endpoint.Hello port =
                service.getHelloPort();
        return port.sayHello(arg0);
    }
}

Запуск веб-клиента

Вы можете использовать IDE NetBeans или Maven для сборки, упаковки, развёртывания и запуска приложения hello-webclient. Чтобы собрать клиента, вы должны сначала развернуть helloservice-war, как описано в Сборка, упаковка и развёртывание сервиса.

Здесь рассматриваются следующие темы:

Запуск веб-клиента в IDE NetBeans
Запуск веб-клиента с помощью Maven

Запуск веб-клиента в IDE NetBeans

В меню «Файл» выберите «Открыть проект».
В диалоговом окне «Открыть проект» перейдите к:
```
tut-install/examples/jaxws
```
Выберите каталог hello-webclient.
Нажмите Открыть проект.
На вкладке «Проекты» кликните правой кнопкой мыши проект hello-webclient и выберите «Сборка».

Эта задача запускает цель wsimport, собирает и упаковывает приложение в WAR-файл, hello-webclient.war, расположенный в каталоге target, и развёртывает его на сервере GlassFish.
В веб-браузере введите следующий URL:
```
http://localhost:8080/hello-webclient/HelloServlet
```
Вывод метода sayHello появится в окне.

Запуск веб-клиента с помощью Maven

В окне терминала перейдите в:
```
tut-install/examples/jaxws/hello-webclient/
```
Введите следующую команду:
```
mvn install
```
Эта команда запускает цель wsimport, затем собирает и упаковывает приложение в WAR-файл, hello-webclient.war, расположенный в каталоге target , WAR-файл затем развёртывается на сервере GlassFish.
В веб-браузере введите следующий URL:
```
http://localhost:8080/hello-webclient/HelloServlet
```
Вывод метода sayHello появится в окне.