Web-сервис SOAP в Eclipse

Что такое веб-сервис SOAP (Simple Object Access Protocol) и с чем его «едят»? В предыдущей статье было сказано, что web-сервисы представляют собой процесс взаимодействия приложений по протоколу HTTP, а SOAP определяет протокол реализации web-сервиса и является дальнейшим развитием XML-RPC (XML-вызов удалённых процедур). Если не вдаваться в сложности процесса взаимодействия клиент/серверных приложений, то можно сказать, что имеется некий сервер, который управляет информацией (добавляет, удаляет, обновляет, хранит) и выдает клиентам информацию по запросам в формате XML. Клиенты могут обращаться к такому серверу только по протоколу HTTP с оформлением запроса в формате XML. Т.е. клиент с сервером обмениваются только XML-информацией, и ни каких картинок, аудио, видео. Такой сервер может предоставлять информацию (веб-сервис) о погоде, об авиационном или железнодорожном расписании, о курсе валют и т.д.

Каждый web-сервис SOAP имеет описание в виде файла wsdl. WSDL (Web Services Description Language) - язык описания веб-сервисов и доступа к ним в формате XML.

В данной статье рассмотрим вопрос создания WEB-сервиса SOAP в IDE Eclipse с практической точки зрения. Т.е. создадим, запустим и протестируем веб-сервис SOAP. Как говорится, лучше один раз, чем ни разу.

Apache Axis

Для разработки WEB-сервиса были использованы Eclipse Luna (4.4.2), Apache Tomcat v8.5.4 и Apache Axis. Полагаю, что версии Eclipse и Tomcat не критичны для решения данной задачи. Можно использовать и другие версии.

Особо следует сказать об Apache Axis (Apache eXtensible Interaction System), который является фреймворком веб-сервиса с открытым исходным кодом. AXIS включает в себя контейнер для размещения и использования веб-сервисов на серверах приложений, утилиты для работы с WSDL-описаниями, классы для разработки веб-сервисов и их клиентов. В нашем примере AXIS будет использоваться для создания и тестирования WEB-сервиса и вызываться он будет из Eclipse.

Описание примера

Чтобы в Eclipse создать простейший WEB-сервис SOAP, а потом запустить его и протестировать, надо хорошо знать Eclipse, поскольку он всё сделает сам, включая создание файла wsdl. Поэтому кодировать придется очень мало, а в большей степени разбираться со скриншотами интерфейса IDE Eclipse.

Создадим WEB-сервис, который управляет персоналом и позволяет добавлять и удалять сотрудников, просматривать список сотрудников и выполнять поиск сотрудника по идентификатору. Начнем с проекта, тип которого в Eclipse должен быть 'Dynamic Web Project'. Определим наименование проекта как 'SoapServer' :

В проекте создадим класс сотрудника Person, интерфейс описания методов PersonService и класс реализации методов PersonServiceImpl. На этом программирование заканчивается.

Листинг класса Person

Класс сотрудника включает идентификатор id и имя name (проще и не придумать). Также в классе определим методы get/set.

package com.example;

import java.io.Serializable;

public class Person implements Serializable
{
    private static final long serialVersionUID = 1L;

    private int    id;
    private String name;

    public Person() {}

    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
}

Листинг интерфейса PersonService

Интерфейс определяет методы добавления нового сотрудника addPerson, удаление сотрудника deletePerson, получение сотрудника по идентификатору getPerson и чтение списка сотрудников getPersons.

package com.example;

public interface PersonService
{
    public boolean  addPerson   (Person p);
    public boolean  deletePerson(int id);
    public Person   getPerson   (int id);
    public Person[] getPersons  ();
}

Листинг класса PersonServiceImpl

Класс PersonServiceImpl реализует методы интерфейса.

package com.example;

import java.util.Map;
import java.util.Set;
import java.util.HashMap;

public class PersonServiceImpl implements PersonService 
{
    private static Map<Integer,Person> persons;

    public PersonServiceImpl() {
        if (persons == null)
            persons = new HashMap<Integer,Person>();
    }
    @Override
    public boolean addPerson(Person p) {
        if (persons.get(p.getId()) != null)
            return false;
        persons.put(p.getId(), p);
        return true;
    }
    @Override
    public boolean deletePerson(int id) {
        if (persons.get(id) == null)
            return false;
        persons.remove(id);
        return true;
    }
    @Override
    public Person getPerson(int id) {
        return persons.get(id);
    }
    @Override
    public Person[] getPersons() {
        Set<Integer> ids = persons.keySet();
        Person[] p = new Person[ids.size()];
        int i = 0;
        for(Integer id : ids){
            p[i] = persons.get(id);
            i++;
        }
        return p;
    }
}

Примечание : при каждом вызове сервиса (одного из его методов) создается объект PersonServiceImpl, в конструкторе которого выполняется проверка создания коллекции сотрудников. Поэтому коллекция сотрудников объявлена статической.

Cоздание WEB-сервиса SOAP

Для создания WEB-сервиса необходимо выделить реализацию интерфейса PersonServiceImpl и в контекстном меню, вызываемом правой клавишей мыши, выбрать 'Web Service' (New/Other/Web Services/Web Service). Будет открыто окно мастера создания веб-сервиса, в котором представлена конфигурация создания веб-сервиса, включающая Tomcat, Apache Axis и наш проект SoapServer (вот где объявилась среда разработки в виде Tomcat и Apache Axis).

Здесь можно ничего не делать, только проверьте 'Service Implementation', чтобы был выбран соответствующий класс, установите галочки публикации и мониторинга веб-сервиса в нижней части формы ('Publish the Web service', 'Monitor the Web service') и можно переходить к следующему шагу нажатием кнопки Next.

На этом шаге будет представлен список всех методов веб-сервиса (класса реализации интерфейса), описанных в файле PersonServiceImpl.wsdl :

Можно завершить процесс создания WEB-сервиса нажатием кнопки Finish. Но из любопытства все же заглянем в последнее окно и нажмем кнопку Next.

Здесь мы видим, что мастер завершил свою работу и предлагает стартовать Tomcat. Нажимаем на кнопку 'Start server' и завершаем после этого работу с мастером. Теперь можно посмотреть, что сделал мастер разработки WEB-сервиса с нашим проектом.

Структура проекта WEB-сервиса SOAP

Мы только создали два класса и интерфейс, а остальное создал мастер, включая поддиректорию с файлами WEB-INF/PersonServiceImplService, файл WEB-INF/server-config.wsdd и описание сервиса в виде PersonServiceImpl.wsdl в поддиректории WEB-INF/wsdl. Он же внес в дескриптор приложения web.xml изменения, связанные с web-сервисом.

В скриншоте не развернута директория lib, в которую мастер включил необходимые для веб-сервиса библиотеки jar :

• axis.jar
• commons-discovery-0.2.jar
• commons-logging.jar
• jaxrpc.jar
• saaj.jar
• wsdl4j.jar

Дескриптор приложения web.xml

В дескриптор приложения вносить изменений не требуется, если не считать удаление отсутствующих в проекте открываемых страниц по умолчанию (секция <welcome-file-list>. Мастер создания веб-сервиса всю необходимую информацию вписал сам.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xmlns="http://xmlns.jcp.org/xml/ns/javaee" 
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee 
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd" 
         version="3.1">
  <display-name>SoapServer</display-name>
  <!--
  <welcome-file-list>
  </welcome-file-list>
   -->
  <servlet>
    <display-name>Apache-Axis Servlet</display-name>
    <servlet-name>AxisServlet</servlet-name>
    <servlet-class>
        org.apache.axis.transport.http.AxisServlet
	</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>AxisServlet</servlet-name>
    <url-pattern>/servlet/AxisServlet</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>AxisServlet</servlet-name>
    <url-pattern>*.jws</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>AxisServlet</servlet-name>
    <url-pattern>/services/*</url-pattern>
  </servlet-mapping>
  <servlet>
    <display-name>Axis Admin Servlet</display-name>
    <servlet-name>AdminServlet</servlet-name>
    <servlet-class>
        org.apache.axis.transport.http.AdminServlet
    </servlet-class>
    <load-on-startup>100</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>AdminServlet</servlet-name>
    <url-pattern>/servlet/AdminServlet</url-pattern>
  </servlet-mapping>
</web-app>

Старт WEB-сервиса SOAP

Для работы с веб-сервисом необходимо стартовать (если еще не стартовано) web-приложение SoapServer. Для этого, нажимая правой клавишей мыши на проекте, вызываем контекстное меню и выбираем 'Run As/Run on Server'. В открывшемся окне выбора сервера приложений выделяем Tomcat и нажимаем кнопку Finish.

В браузере будет открыта страница проекта по умолчанию, которой у нас нет. Браузер/вкладку с открывшейся с ошибкой страницей можно закрыть, она нам не пригодится. На вкладке серверов (скриншот ниже) можно увидеть, что сервер стартован и приложение SoapServer загружено в его контейнер.

Для старта приложения управления веб-сервисом Axis необходимо найти и нажать в панели инструментов кнопку, представленную на следующем скриншоте с подсказкой 'Launch the Web Service Explorer'.

В результате в браузере будет открыта страница Web Services Explorer, интерфейс которой представлен на следующем скриншоте. Окно приложения Web Services Explorer включает панель инструментов с кнопками (справа вверху) и три области : Navigator, Actions, Status. На строку URL не обращаем внимания, нам с ней не работать.

Первое, что нам необходимо, так это выбрать режим WSDL. Для этого в панели инструментов находим нужную нам кнопку и нажимаем. Корневым элементом в дереве Navigator'а отобразиться 'WSDL Main' и в панели Actions будут представлены компоненты для работы с WSDL (скриншот сверху). Здесь можно подключиться к веб-сервису в Интернете. Но мы пойдем другим путём и выберем наш файл PersonServiceImpl.wsdl с описанием веб-сервиса из запущенного проекта SoapServer. Вводим в строке соответствующий адрес URI, начинающийся с file: и нажимаем кнопку 'GO'. Если всё правильно сделано и всё работает, то в Navigator'e будет отображена структура нашего WEB-сервиса, как это представлено на следующем скриншоте.

Переходим к тестированию методов WEB-сервиса. Выполним только добавление новых сотрудников и просмотрим список. Остальные методы Вы можете проверить самостоятельно.

Добавление сотрудника

Для добавления нового сотрудника выделяем соответствующий метод в Navigator'e; в панели Actions в секции Body будет представлен выбранный метод и параметры. Вводим идентификатор, русскоязычное имя 'Всеволод' и нажимаем кнопку GO. Результат выполнения метода веб-сервиса можно увидеть в панели Status.

Чтобы просмотреть текст запроса и ответа веб-сервиса в панели Status нажимаем на link 'Source'. В результате в интерфейсе панели (скриншот ниже) будут открыты компонент с описанием запроса 'SOAP Request Envelope' и компонент с описанием ответа 'SOAP Response Envelope' в формате XML. Обратите внимание, что русскоязычное имя в запросе отображено в виде вопросительных знаков. После этого были добавлены еще два сотрудника Serg (id=2) и Olga (id=3).

Чтение списка сотрудников

А как будет представлен сотрудник в списке, имя которого имеет кириллицу? Выделяем в Navigator'e метод getPersons, нажимаем кнопку 'GO' и смотрим результат запроса в панели Status в режиме Form (следующий скриншот). Всё нормально, имя представлено верно в кириллице. Т.е. не потребовалось «изголяться» с charset'ами для передачи и чтения текстовой информации не в ASCII-коде.

Но вот при просмотре запроса и ответа в панели Status в режиме Source видим, что кириллица отображается в виде вопросительных знаков.

Заключение

В статье был рассмотрен вопрос создания и тестирования WEB-сервиса в IDE Eclipse. Основную цель, которую я преследовал при изложении данной информации, показать, что такое WEB-сервис SOAP, как его можно практически создать и протестировать. Представленный материал должен позволить Вам взглянуть во «внутренности» WEB-сервиса SOAP и понять сущность данной технологии.

Создание клиента WEB-сервиса на примере рассмотрен здесь. Второй пример SOAP клиента с авторизацией представлен здесь.