Веб-сервисы в Java SE, часть 2: Создание веб-сервисов SOAP

JAX-WS поддерживает веб-службы на основе SOAP. В части 2 этой серии из четырех частей, посвященной веб-службам Java SE, определяется веб-служба преобразования единиц на основе SOAP, создается и затем проверяется эта веб-служба локально через упрощенный HTTP-сервер по умолчанию (обсуждается в части 1), интерпретируется документ WSDL службы. , и получает доступ к сервису из простого клиента.

Определение веб-службы преобразования единиц измерения

Веб-служба преобразования единиц измерения, которую я назвал UC, состоит из четырех функций для преобразования между сантиметрами и дюймами и между градусами Фаренгейта и градусами Цельсия. Хотя этот пример можно было бы спроектировать как отдельный Java-класс, я решил следовать лучшим практикам, создав его как Java-интерфейс и Java-класс. В листинге 1 представлен UCинтерфейс веб-службы .

Листинг 1. Интерфейс конечной точки службы веб-службы UC

package ca.javajeff.uc; import javax.jws.WebMethod; import javax.jws.WebService; @WebService public interface UC { @WebMethod double c2f(double degrees); @WebMethod double cm2in(double cm); @WebMethod double f2c(double degrees); @WebMethod double in2cm(double in); }

UCописывает интерфейс конечной точки службы (SEI) , который представляет собой интерфейс Java, который представляет операции интерфейса веб-службы в терминах абстрактных методов Java. Клиенты общаются с веб-службами на основе SOAP через свои SEI.

UCобъявлен как SEI через @WebServiceаннотацию. Когда интерфейс или класс Java аннотируются @WebService, все publicметоды, параметры, возвращаемые значения и объявленные исключения которых соответствуют правилам, определенным в разделе 5 спецификации JAX-RPC 1.1, описывают операции веб-службы. Потому что только publicметоды могут быть объявлены в интерфейсах, то publicзарезервированное слово не является необходимым при декларировании c2f(), cm2in(), f2c()и in2cm(). Эти методы неявно public.

Каждый метод также снабжен аннотацией @WebMethod. Хотя @WebMethodэто и не обязательно в этом примере, его присутствие подтверждает тот факт, что аннотированный метод предоставляет операцию веб-службы.

В листинге 2 представлен UCImplкласс веб-службы .

Листинг 2. Компонент реализации службы веб-службы UC

package ca.javajeff.uc; import javax.jws.WebService; @WebService(endpointInterface = "ca.javajeff.uc.UC") public class UCImpl implements UC { @Override public double c2f(double degrees) { return degrees * 9.0 / 5.0 + 32; } @Override public double cm2in(double cm) { return cm / 2.54; } @Override public double f2c(double degrees) { return (degrees - 32) * 5.0 / 9.0; } @Override public double in2cm(double in) { return in * 2.54; } }

UCImplописывает компонент реализации службы (SIB) , который обеспечивает реализацию SEI. Этот класс объявлен как SIB через @WebService(endpointInterface = "ca.javajeff.uc.UC")аннотацию. endpointInterfaceЭлемент связывает это SIB его SEI, и необходимо , чтобы избежать неопределенных ошибок типа порта при запуске клиентского приложения , приведенное ниже.

implements UCПоложение не является абсолютно необходимым. Если это предложение отсутствует, UCинтерфейс игнорируется (и является избыточным). Однако лучше оставить, implements UCчтобы компилятор мог проверить, что методы SEI реализованы в SIB.

Заголовки методов SIB не аннотируются, @WebMethodпотому что эта аннотация обычно используется в контексте SEI. Однако, если вам нужно добавить publicметод (который соответствует правилам раздела 5 спецификации JAX-RPC 1.1) в SIB, и если этот метод не предоставляет операцию веб-службы, вы должны аннотировать заголовок метода @WebMethod(exclude = true). Назначив trueна @WebMethod«S excludeэлемента, можно предотвратить этот метод из ассоциируется с операцией.

Эта веб-служба готова к публикации, поэтому к ней можно будет получить доступ с клиентов. В листинге 3 представлено UCPublisherприложение, которое выполняет эту задачу в контексте облегченного HTTP-сервера по умолчанию.

Листинг 3. Публикация UC

import javax.xml.ws.Endpoint; import ca.javajeff.uc.UCImpl; public class UCPublisher { public static void main(String[] args) { Endpoint.publish("//localhost:9901/UC", new UCImpl()); } }

Публикация веб-службы включает в себя один вызов метода EndPointкласса Endpoint publish(String address, Object implementor)класса. В addressидентифицирует параметр URI , присвоенный веб - службе. Я решил опубликовать эту веб-службу на локальном хосте, указав localhost(эквивалент IP-адресу 127.0.0.1) и номер порта 9901(который, скорее всего, доступен). Кроме того, я произвольно выбрал /UCпуть публикации. В implementorпараметр определяет экземпляр UC«S SIB.

publish()Метод создает и публикует конечную точку для указанного implementorобъекта в данный address, и использует implementorые аннотации»для создания веб - служб определения языка (WSDL) и XML - схем документов. Это приводит к созданию и настройке необходимой серверной инфраструктуры с помощью реализации JAX-WS на основе некоторой конфигурации по умолчанию. Кроме того, этот метод заставляет приложение работать бесконечно. (На компьютерах с Windows одновременно нажмите клавиши Ctrl и C, чтобы закрыть приложение.)

Создание и проверка веб-службы

Создать предварительно определенный веб-сервис UC несложно. Во-первых, вам нужно создать подходящую структуру каталогов, содержащую соответствующие файлы. Выполните эту задачу, выполнив следующие шаги:

  1. В текущем каталоге создайте caкаталог. Внутри caсоздайте javajeffкаталог. Наконец, внутри javajeffсоздайте ucкаталог.
  2. Скопируйте листинг 1 в UC.javaисходный файл и сохраните его в формате ca/javajeff/uc.
  3. Скопируйте листинг 2 в UCImpl.javaисходный файл и сохраните его в формате ca/javajeff/uc.
  4. Скопируйте листинг 3 в UCPublisher.javaисходный файл и сохраните этот файл в текущем каталоге, который содержит caкаталог.

Следующая задача - скомпилировать эти исходные файлы. Предполагая, что вы не меняли каталоги, выполните следующую команду для компиляции этих исходных файлов в Java SE 9 (опустите --add-modules java.xml.wsв Java SE 6, 7 или 8):

javac --add-modules java.xml.ws UCPublisher.java

Если эти исходные файлы компилируются успешно, выполните следующую команду, чтобы запустить это приложение в Java 9 (опустите --add-modules java.xml.wsв Java SE 6, 7 или 8):

java --add-modules java.xml.ws UCPublisher

Во время работы приложения используйте веб-браузер, чтобы убедиться, что эта веб-служба работает правильно, и получить доступ к ее документу WSDL. Запустите ваш любимый веб-браузер и введите в адресной строке следующую строку:

//localhost:9901/UC

На экране 1 показана полученная веб-страница в веб-браузере Google Chrome.

Рисунок 1. Веб-страница UC предоставляет подробную информацию об опубликованном веб-сервисе.

На рис. 1 представлены квалифицированные службы и имена портов конечной точки веб-службы. (Обратите внимание, что имя пакета было перевернуто - uc.javajeff.caвместо ca.javajeff.uc). Клиент использует эти имена для доступа к службе.

На рисунке 1 также представлен адресный URI веб-службы, расположение WSDL-документа веб-службы (URI веб-службы с суффиксом ?wsdlстроки запроса) и имя класса реализации веб-службы с указанием пакета.

Интерпретация WSDL-документа веб-службы

Расположение документа WSDL веб-службы UC отображается в виде ссылки. Щелкните эту ссылку, чтобы просмотреть документ WSDL, содержимое которого представлено в листинге 4.

Листинг 4. Документ WSDL UC

Документ WSDL - это документ XML с definitionsкорневым элементом, который делает документ WSDL не более чем набором определений. Этот элемент включает в себя различные xmlnsатрибуты для идентификации различных стандартных пространств имен, targetNameSpaceа также nameатрибуты и:

  • targetNamespaceАтрибут создает пространство имен для всех пользовательских элементов в WSDL - документе (например, c2fэлемент , определенный с помощью messageэлемента с этим именем). Это пространство имен используется, чтобы различать определяемые пользователем элементы текущего документа WSDL и определяемые пользователем элементы импортированных документов WSDL, которые идентифицируются через importэлемент WSDL . Аналогичным образом targetNamespaceатрибут, который появляется в schemaэлементе файла на основе схемы XML, создает пространство имен для его определяемых пользователем элементов простого типа, элементов атрибута и элементов сложного типа.
  • nameАтрибут идентифицирует веб - службу и используется только для документирования службы.

Вложенные в definitionsкоторые types, message, portType, binding, и serviceэлементы: