Уеб услуги в 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. Bean за внедряване на услугата на 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описва Bean за внедряване на услуга (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' 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идентифицира параметрите на Ури, възложени на уеб услугата. Избрах да публикувам тази уеб услуга на локалния хост, като посочих localhost(еквивалентно на IP адрес 127.0.0.1) и номер на порт 9901(който е най-вероятно наличен). Също така произволно избрах /UCкато път за публикуване. На implementorидентифицира параметри случай на UCлидер SIB.

В publish()метода създава и публикува крайна точка за конкретния implementorобект в дадения addressи използва най- implementorите анотации "за създаване на Web Services Definition Language (WSDL) и XML Schema документи. Това води до създаването и конфигурирането на необходимата сървърна инфраструктура от изпълнението на 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 Schema, създава пространство на имена за своите дефинирани от потребителя прости елементи от тип, елементи на атрибути и сложни елементи от тип.
  • В nameатрибута идентифицира уеб услугата и се използва само за документиране на услугата.

Вложен в definitionsса types, message, portType, binding, и serviceелементи: