Создание простого веб-сервиса с использованием JBossWS
ОГЛАВЛЕНИЕ
Скачать руководство по веб-сервису jboss - 11.58 KB
Введение
Некоторое время назад мне поручили работу над проектам, в котором нужно было создать простой веб-сервис, который работал бы на сервере приложений JBoss. Во время поиска обстоятельных руководств в интернете я не нашел ничего полезного для себя. В конце концов я разобрался во всех деталях, которые нужно было разработать и реализовать, чтобы заставить такой веб-сервис работать. Я решил кратко изложить изученные вещи в этой статье, не только для ведения собственных записей, но и чтобы помочь тем, кому нужна похожая информация.
Назначение данной статьи – дать обстоятельное руководство по следующим темам:
- Программное обеспечение, требуемое для этой статьи.
- Как создать простой веб-сервис для сервера приложений JBoss?
- Как развернуть и свернуть веб-сервис в сервере приложений JBoss?
- Как разработать простое тестовое приложение для тестирования работающего веб-сервиса?
Установка и настройка необходимого программного обеспечения
Данное руководство требует установку и настройку следующих пакетов программ:
- JDK 1.5 (или выше).
- Apache Ant (текущая версия 1.7.1).
- JBoss App Server (текущая версия 5.0.0 GA).
- JBossWS (текущая версия 3.0.5 GA).
Также рекомендуется использовать Eclipse IDE (интегрированная среда разработки). Но для этого руководства всю работу можно сделать при помощи простого редактора кода (например, UltraEdit32, Crimson Editor или Notepad++), командной строки и Apache Ant.
Для удобства данное руководство было создано в Windows XP. Однако оно относительно легко перемещается на другие платформы.
Установка JDK и Apache Ant
Установить JDK в Windows XP очень легко, достаточно загрузить установщик MSI, затем установить его по умолчанию в "Program Files" или прямо в "C:\". После установки JDK рекомендуется настроить системные переменные:
- Создайте системную среду "JAVA_HOME" и укажите в ней базовый каталог JDK (т.е. C:\Program Files\Java\jdk-1.5.0_17 или C:\jdk-1.5.0_17).
- Также добавьте "%JAVA_HOME%\bin" в системную переменную "PATH (путь)".
После настройки системной переменной откройте командную строку и наберите "java –version (версия java)". Вывод покажет версию JDK, установленную в системе. Это позволит проверить успешность установки JDK. После проверки закройте командную строку.
Установить Apache Ant также просто: загрузите исполняемый двоичный файл-архив с вебстраницы проекта Apache Ant (здесь). Затем распакуйте файл-архив в "C:\". Это распакует файл-архив в "C:\apache-ant-1.7.1". "C:\apache-ant-1.7.1" будет базовым каталогом Apache Ant. После распаковки настройте системные переменные следующим образом:
- Создайте системную среду "ANT_HOME" и укажите в ней базовый каталог Apache Ant (т.е. C:\apache-ant-1.7.1).
- Также добавьте "%ANT_HOME%\bin" в системную переменную "PATH".
После настройки системной переменной выполните проверку, открыв командную строку и введя "ant –version". Если настройка выполнена правильно, вывод покажет версию Apache Ant, установленную в системе.
Установка JBoss и JBossWS
Это руководство учит, как создать веб-сервис, работающий в JBoss. Поэтому обязательно нужно установить и настроить сервер приложений JBoss (текущая версия 5.0.0.GA) и веб-сервисы JBoss (также называются JBossWS, текущая версия 3.0.5.GA). Установочные пакеты (zip архивы) можно найти в следующих местах:
- Скачать сервер приложений JBoss. На настоящей странице загрузки есть два файла-архива, тот, который работает с JDK 1.5, называется jboss-5.0.0.GA.zip. Другой (jboss-5.0.0.GA-jdk6.zip) работает с JDK 1.6.
- Скачать веб-сервисы JBoss
Процесс установки JBoss аналогичен установке Apache Ant. Вам лишь нужно распаковать файл-архив, содержащий исполняемые двоичные файлы сервера приложений JBoss в "C:\". Это создаст новый каталог под названием "C:\jboss-5.0.0.GA", являющийся базовым каталогом сервера приложений JBoss. После распаковки создайте системную среду "JBOSS_HOME" и укажите в ней "C:\jboss-5.0.0.GA". Хотя это необязательно, также можно добавить "%JBOSS_HOME%\bin" в системную переменную "PATH".
Последний шаг – установка пакета JBossWS. Выполните следующие шаги:
- Сначала распакуйте исполняемый двоичный архив JBossWS в "C:\". Это создаст папку "C:\jbossws-native-bin-dist".
- Через проводник Windows зайдите в "C:\jbossws-native-bin-dist". Внутри папки найдите файл "ant.properties.example".
- Создайте копию "ant.properties.example", затем переименуйте ее в "ant.properties".
- Запустите ваш любимый редактор кода (например, UltraEdit32 или Notepad++), затем откройте файл "ant.properties" для редактирования.
- Найдите строку "jboss500.home=@jboss500.home@", замените ее на "jboss500.home=/jboss-5.0.0.GA". Затем сохраните файл и закройте редактор кода.
- Откройте командную строку, перейдите в "C:\jbossws-native-bin-dist". Затем исполните команду "ant deploy-jboss500". Когда она успешно завершится, JBossWS будет установлен и правильно настроен для использования.
Создание простого веб-сервиса
Теперь все готово для создания простого веб-сервиса. Есть два способа создания веб-сервисов:
- Нисходящий. JBossWS используется для создания классов-посредников из существующих файлов WSDL и связанных с ним файлов XSD. Затем реализуется интерфейс порта веб-сервиса.
- Восходящий. Создается простой веб-сервис с помощью POJO. Затем классы упаковываются для развертывания.
В этом руководстве рассматривается восходящий подход, так как это простейший способ создания веб-сервиса. Исходный код можно найти в разделе загрузок. Шаги будут изложены в следующих подразделах.
Создание простого проекта Java
Данное руководство использует Eclipse IDE и Apache Ant для создания проекта-примера. Создание этого проекта-примера не отличается от создания простого проекта Java HelloWorld («привет мир»). Получив исходный код примера, вы сможете увидеть, что в базовом каталоге "webservice", есть две папки:
- "bin": Эта папка используется для хранения скомпонованных выходных файлов.
- "src": Эта папка содержит исходники. Файл исходного кода "Greeting.java" находится в подпапке tutorial/hanbo/webservice.
В базовом каталоге находится несколько текстовых файлов:
- .classpath: Этот файл автоматически создан Eclipse.
- .project: Этот файл автоматически создан Eclipse.
- build.xml: Это файл компоновки Apache Ant.
Сначала посмотрим на файл исходного кода "Greeting.java". Весь исходный код выглядит так:
package tutorial.hanbo.webservice;
import javax.jws.WebService;
import javax.jws.WebMethod;
@WebService
public class Greeting
{
@WebMethod
public String greetClient(String userName)
{
return "Приветствие " + userName + "! Приятного дня!...";
}
}
Это весь код Java, который нужно написать для создания простого веб-сервиса. Давайте подробно рассмотрим исходник:
1. Первая строка объявляет пакет веб-сервиса.
2. Две следующие строки кода импортируют требуемые классы. Они являются аннотациями, используемыми объявлением класса и объявлением метода.
3. Объявите класс под названием "Приветствие"; он снабжен комментарием "веб-сервис", что означает, что класс "Приветствие" – это веб-сервис.
4. Внутри класса "Приветствие" объявите открытый метод с названием "greetClient()". Он снабжен комментарием "веб-метод", что означает, что этот метод – сетевой метод, который может быть вызван дистанционно.
- Метод "greetClient()" принимает параметр строкового типа под названием "username (имя пользователя)". Его тело создаст новый объект “строка/и”? и выполнит возврат.
Если ссылочные библиотеки не добавлены в этот проект, он не будет компилироваться в Eclipse. Поэтому посмотрите файл .classpath и найдите все нужные ссылочные библиотеки (т.е. файлы jar со ссылками). Эти библиотеки были частью пакета JBoss. Их можно найти в 3 разных папках:
• C:\jboss-5.0.0.GA\client
• C:\jboss-5.0.0.GA\lib
• C:\jboss-5.0.0.GA\lib\endorsed
Добавьте все эти файлы jar в трех папках в проект-пример, после этого ошибки компиляции исчезнут. Но следующие два файла jar нужно удалить:
• C:\jboss-5.0.0.GA\client\jaxws-rt.jar
• C:\jboss-5.0.0.GA\client\jaxws-tools.jar
Их нужно удалить из проекта, чтобы избавиться от исключения. Это может быть странная ошибка в JBossWS. Когда я впервые работал над этим примером, столкнулся с исключением в то время, когда пытался развернуть готовый веб-сервис на сервере приложений JBoss. После перебора результатов поиска Google я нашел решение, согласно которому нужно удалить указанные два файла jar из пути классов проекта.
Дескриптор развертывания
Веб-сервис нужно развернуть, чтобы клиенты смогли иметь к нему доступ. В данном руководстве веб-сервис будет упакован как файл war и развернут как сервлет. Файл war содержит дескриптор развертывания, файл с именем "web.xml" задает преобразование URL.сервлет. Когда отправляется запрос к серверу приложений JBoss, JBoss направляет запрос к конкретному сервлету на основании преобразования URL/Servlet, заданного в файлах web.xml.
В базовом каталоге проекта вы найдете файл web.xml в подкаталоге src/resources (ресурсы). Содержимое этого файла выглядит так:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
<servlet>
<servlet-name>GreetingWebService</servlet-name>
<servlet-class>tutorial.hanbo.webservice.Greeting</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>GreetingWebService</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Содержимое данного файла дескриптора понять легко. Все содержимое поделено на две части:
• Первая часть (от <servlet> до </servlet>) указывает, чем является сервлет. Он имеет имя "GreetingWebService" и преобразуется в класс Java "tutorial.hanbo.webservice.Greeting".
• Вторая часть (от <servlet-mapping> до </servlet-mapping>) задает URL для преобразования сервлета. Если запрошенный URL указывает на веб-сервис, то запрос будет обработан веб-сервисом.
Следующий раздел описывает, как упаковать файл war.
Упаковка с помощью Apache Ant
Упаковка файла war может быть выполнена с помощью Apache Ant. В build.xml вы найдете несколько целей. Они используются для выполнения действий компоновки. Одна из целей называется "упаковка". Эта цель используется для создания файла war для развертывания, как показано ниже:
<target name="packaging" >
<war destfile="bin/greeting.war" webxml="src/resources/web.xml">
<classes dir="bin/classes"/>
</war>
</target>
В этом разделе целей есть только одно действие для выполнения – компоновка файла war с использованием задачи с именем "war".
Эта задача принимает три параметра:
• destfile: это первый атрибут тега XML "war", используемый для указания, какое имя имеет файл war и в какую папку он будет помещен.
• webxml: это второй атрибут тега XML "war", используемый для указания, где находится файл web.xml, который будет упакован как часть файла war.
• classes (классы): это субтег XML под тегом XML "war", используемый для указания файлов классов, которые будут включены в файл war.
Для запуска этой цели нужно использовать следующую команду в командной строке:
> ant packaging
Вывод команды выглядит так:
Buildfile: build.xml packaging:В каталоге bin внутри базового каталога проекта находится только что созданный файл war. Используя инструмент сжатия/распаковки zip архива, такой как 7-zip, можно открыть данный файл-архив и изучить его внутреннюю структуру. Внутри есть два каталога, один называется "META-INF", который содержит файл "MANIFEST.MF"; другой называется WEB-INF, внутри него есть подкаталог с названием "classes" и файл с именем "web.xml". Greeting.class находится внутри подкаталога "tutorial/hanbo/webservices" в "classes".
[war] Building war: %project_base_directry%\bin\greeting.war
BUILD SUCCESSFUL
Total time: 1 second
Так как файл war был успешно скомпонован, пришло время его развернуть.
Развертывание и свертывание
Перед тем как пытаться развернуть файл war примера в сервере приложений JBoss, сначала нужно запустить сервер приложений JBoss. Так как JBoss используется только как средство тестирования простого веб-сервиса, в руководстве не рассматривается, как запустить JBoss в качестве сервиса. Вместо этого мы откроем еще одну командную строку, потом запустим сервер приложений JBoss в только что открытой командной строке.
Чтобы запустить сервер приложений JBoss, используйте только что открытую командную строку, чтобы перейти в "C:\jboss-5.0.0.GA\bin", затем запустите скрипт "run.bat". После того как сервер приложений JBoss запустится, придется подождать в течение некоторого времени, пока командная строка не покажет следующий вывод:
15:34:41,889 INFO [ServerImpl] JBoss (Microcontainer)
[5.0.0.GA (build: SVNTag=JBoss_5_0_0_GA date=200812041714)] Started in 5m:3s:150ms
Вышеуказанный вывод означает, что сервер приложений JBoss был успешно запущен.
Чтобы выключить сервер приложений JBoss, запустите командную строку, выполняющую сервер приложений JBoss. Нажмите Ctrl+C, чтобы остановить выполнение, затем закройте командную строку.
Чтобы развернуть файл war, скопируйте файл war (greeting.war), затем вставьте его в "C:\jboss-5.0.0.GA\server\default\deploy". После выполнения этих действий вы заметите, что командная строка, в которой выполняется сервер приложений JBoss, выведет прогресс развертывания в следующем виде:
15:35:21,422 INFO [DefaultEndpointRegistry] register: jboss.ws:context=greeting,endpoint=GreetingWebService
15:35:22,453 INFO [TomcatDeployment] deploy, ctxPath=/greeting, vfsUrl=greeting.war
15:35:28,172 INFO [WSDLFilePublisher] WSDL published to:
file:/C:/jboss-5.0.0.GA/server/default/data/wsdl/greeting.war/GreetingService4604908665079984702.wsdl
Вышеуказанный вывод показывает, что процесс развертывания прошел успешно.
Следующий шаг – протестировать развертывание. Откройте окно браузера, перейдите по адресу "http://localhost:8080/jbossws/services". После того как страница загрузится, вы сможете увидеть раздел "Конечные точки зарегистрированного сервиса", перечисляющий подробную информацию о развертывании веб-сервиса "GreetingWebService". Можно провести еще один тест – просмотреть файл WSDL, созданный динамически JBossWS. Для данного руководства ссылка на созданный WSDL - "http://127.0.0.1:8080/greeting?wsdl". Его можно просмотреть в том же самом окне браузера.
Свернуть веб-сервис можно путем удаления файла war (greeting.war) в "C:\jboss-5.0.0.GA\server\default\deploy". Как только вы сделаете это, командная строка покажет прогресс сворачивания:
16:51:12,229 INFO [TomcatDeployment] undeploy, ctxPath=/greeting, vfsUrl=greeting.war
16:51:13,307 INFO [DefaultEndpointRegistry] remove: jboss.ws:context=greeting,endpoint=GreetingWebService
Вышеуказанный вывод показывает, что процесс сворачивания прошел успешно.
В build.xml указаны две цели для развертывания или сворачивания веб-сервиса. Они используют задачи копирования файла и удаления файла Apache Ant для выполнения операций развертывания и сворачивания. Чтобы развернуть веб-сервис, используйте цель "развернуть". Чтобы свернуть веб-сервис, используйте цель "свернуть".
Тестирование веб-сервиса при помощи клиента веб-сервиса
Если вы не протестируете только что созданный веб-сервис, вы не узнаете, работает он или нет. Так как в этом руководстве, веб-сервис крайне простой, предоставляющий только один веб-метод, принимающий строку в качестве параметра, его можно протестировать посредством динамического вызова. Динамический вызов, как многие отмечают, является "плохим способом создания клиента веб-сервиса". Большинство веб-сервисов в реальных условиях работы используют сложные объекты данных и выполняют сложные операции. Использование динамического вызова, чтобы создавать код для тестирования столь сложных веб-сервисов, может быть крайне трудным. Лучше создавать клиенты веб-сервисов путем использования классов-посредников, созданных JBossWS из файлов WSDL и связанных с ними файлов XSD.
Клиент веб-сервиса – консольное приложение, написанное на Java. Это тестовое приложение выделено в другой проект с названием "webservice-test". Этот проект использует тот же набор jar со ссылками, что и проект веб-сервиса. build.xml предусмотрен не только для компоновки проекта в командной строке, но и для запуска тестового приложения. Чтобы скомпоновать проект, используйте команду "ant compile". После компоновки проекта, чтобы протестировать приложение, используйте команду "ant run-test-app". Но перед запуском этого тестового приложения обязательно сначала разверните веб-сервис.
Посмотрим на исходный код тестового приложения. В исходном коде есть два следующих основных раздела:
• Инструкции импорта, используемые для импорта нескольких классов, используемых клиентом веб-сервиса.
• Главный метод, содержащий поток выполнения программы.
Инструкции импорта выглядят так:
import javax.xml.rpc.Call;
import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceFactory;
import javax.xml.rpc.ParameterMode;
import javax.xml.namespace.QName;
Как показывает вышеуказанный код, импортируются только требуемые классы. Класс ServiceFactory используется для создания объекта Service. Объект Service может создать объект call (вызов). Используя объект Call, можно выполнить дистанционный вызов веб-метода, предоставляемого веб-сервисом. Так как веб-метод принимает входной параметр, потребуется ParameterMode, чтобы указать, как будет использоваться параметр. Так как созданный WSDL тоже использует пространства имен, нужны объекты QName, указывающие классифицированные имена.
Следующий код вызывает веб-сервис:
public static void main(String[] argv)
{
try
{
String NS_XSD
= "http://www.w3.org/2001/XMLSchema";
ServiceFactory factory
= ServiceFactory.newInstance();
Service service = factory.createService(
new QName(
"http://webservice.hanbo.tutorial/",
"GreetingService"
)
);
Call call = service.createCall(new QName(
"http://webservice.hanbo.tutorial/",
"GreetingPort"
));
call.setTargetEndpointAddress(
"http://localhost:8080/greeting?wsdl"
);
call.setOperationName(
new QName(
"http://webservice.hanbo.tutorial/",
"greetClient"
)
);
QName QNAME_TYPE_STRING =
new QName(NS_XSD, "string");
call.setReturnType(QNAME_TYPE_STRING);
call.addParameter(
"arg0", QNAME_TYPE_STRING,
ParameterMode.IN
);
String[] params = { "Murphy Brown" };
String result = (String)call.invoke(params);
System.out.println(result);
}
catch (Exception e)
{
e.printStackTrace();
}
}
Этот кусок кода показывает, как работает динамический вызов. Как видно, он довольно сложный. Алгоритм следующий:
1. Сначала создается объект ServiceFactory.
2. Затем вызывается метод createService() объекта ServiceFactory, чтобы создать объект Service. В качестве параметра ему передается объект QName.
- Объект QName указывает сервис с именем "GreetingService" с пространством имен "http://webservice.hanbo.tutorial/".
3. Используется метод createCall() только что созданного объекта Service, чтобы создать объект Call. Объект Call указывает порт веб-сервиса.
4. Для объекта Call нужно:
- Задать адрес целевой конечной точки (setTargetEndPointAddress()). Это URL динамически созданного WSDL.
- Задать имя операции (setOperationName()). Это имя веб-метода, который нужно вызвать.
- Задать тип возвращаемого значения (setReturnType()). В этом случае возвращается стандартное строковое значение.
- Добавить передаваемые параметры (addParameter()). В этом случае единственный передаваемый параметр – строковый параметр.
5. После установки объекта Call наконец можно вызвать веб-метод путем вызова метода invoke() объекта Call. Параметр, переданный в invoke(), - массив объектов, представляющий собой входной параметр, который будет использовать удаленный веб-метод. В нашем случае есть только один параметр-это строка "Мэрфи Браун".
Если все прошло правильно, приложение можно запустить через Eclipse или Apache Ant в командной строке. Если вы решите запустить его через Apache Ant – команда следующая:
> ant run-test-app
Если все пройдет успешно, вывод будет выглядеть так:
> ant run-test-app
Buildfile: build.xml
run-test-app:
[java] Greeting Murphy Brown! Have a nice day...
BUILD SUCCESSFUL
Total time: 8 seconds
Интересные моменты
Завершено создание, развертывание и тестирование простейшего веб-сервиса. В своей существующей форме веб-сервис абсолютно бесполезен. Это руководство дает скелет веб-сервиса. Любой читатель может использовать его как стартовую точку; добавить больше функций, развернуть и протестировать; затем добавить еще функции, развернуть и протестировать снова, до тех пор, пока конечный продукт не сможет удовлетворить реальные потребности пользователей.