// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= Начало работы с веб-службами JAX-WS
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Начало работы с веб-службами JAX-WS - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Начало работы с веб-службами JAX-WS

link:http://www.jcp.org/en/jsr/detail?id=224[+API -интерфейс Java для веб-служб XML (JAX-WS), JSR 224+], является важным компонентом платформы Java EE. Следующий выпуск интерфейса API Java для RPC на основе XML 1.1 (JAX-RPC), JAX-WS упрощает задачу разработки веб-служб с помощью технологии Java. В нем решены некоторые проблемы JAX-RPC 1.1, и обеспечивается поддержка нескольких протоколов, например SOAP 1.1, SOAP 1.2, XML, а также возможность поддержки дополнительных протоколов наряду с HTTP. В JAX-WS для привязки данных используется JAXB 2.0; также поддерживается индивидуальная настройка для управления интерфейсами создаваемых интерфейсов конечных точек служб. Поддержка аннотаций в JAX-WS упрощает разработку веб-служб и уменьшает размер архивов JAR.

В этом документе рассматриваются основные принципы использования среды IDE для разработки веб-службы JAX-WS. После создания веб-службы будут написаны три разных клиента веб-служб, использующие веб-службу по сети, т.е. "потребляющие" веб-службу. Этими тремя клиентами будут класс Java в приложении для Java SE, сервлет и страница JSP в веб-приложении. Более подробно работа с клиентами освещена в учебном курсе link:./client.html[+Разработка клиентов веб-служб JAX-WS+].


image::images/netbeans-stamp-80-74-73.png[title="Содержимое этой страницы применимо к IDE NetBeans 7.2, 7.3, 7.4 и 8.0"]

* Использование веб-службы

*Для работы с этим учебным курсом требуется следующее программное обеспечение и ресурсы.*

|===
|Программное обеспечение или материал |Требуемая версия 

|link:https://netbeans.org/downloads/index.html[+IDE NetBeans+] |Пакетная загрузка Java EE 

|link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+Комплект для разработчика на языке Java (JDK)+] |JDK 7 или JDK 8
 

|Веб-сервер или сервер приложений, совместимый с Java EE |GlassFish Server Open Source Edition
Oracle WebLogic Server 
|===

*Примечание. *Сервер GlassFish можно установить вместе с дистрибутивом Java EE среды IDE NetBeans. Также можно воспользоваться link:https://glassfish.java.net/download.html[+страницей загрузок GlassFish Server+] или link:http://tomcat.apache.org/download-60.cgi[+страницей загрузок Apache Tomcat+].

*Важно! *Для проектов Java EE требуется GlassFish Server или Oracle WebLogic Server 12c.

Включенный в комплект веб-сервер Tomcat лишь частично совместим с Java EE Однако веб-сервер Tomcat 7.x можно настроить так, чтобы он поддерживал определенную функциональность Java EE. Дополнительные сведения о добавлении поддержки Java EE в Tomcat см. в разделе link:http://openejb.apache.org/[+Проект Apache TomEE+].


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

Цель этого упражнения состоит в создании проекта в соответствии с используемым контейнером развертывания. После создания проекта будет создана веб-служба.


=== Выбор контейнера

Веб-служба может быть развернута в веб-контейнере или в контейнере EJB. Это зависит от конкретной реализации. При создании приложения Java EE всегда используйте веб-контейнер, так как это позволяет поместить компоненты EJB непосредственно в веб-приложение. Например, если развертывание планируется на веб-сервере Tomcat, предоставляющем только веб-контейнер, следует создавать веб-приложение, а не модуль EJB.

1. Выберите 'Файл' > 'Создать проект' (Ctrl-Shift-N в Windows и Linux, ⌘-Shift-N в ОС Mac). Выберите "Веб-приложение" из категории "Java Web" или "Модуль EJB" из категории "Java EE".

Веб-службу JAX-WS можно создать в проекте Maven. Выберите 'Файл' > 'Создать проект' (Ctrl-Shift-N в Linux и Windows, ⌘-Shift-N ы MacOS), а затем веб-приложение Maven или модуль Maven EJB в категории Maven. Если ранее вы не использовали Maven со средой NetBeans, ознакомьтесь с документом link:http://wiki.netbeans.org/MavenBestPractices[+Maven Best Practices+] (Рекомендации по Maven).

2. Дайте проекту имя  ``CalculatorWSApplication`` . Выберите местоположение для проекта. Нажмите кнопку "Далее".
3. Выберите свой сервер и версию Java EE и щелкните "Готово".

Для использования сервера Oracle WebLogic link:../web/jsf-jpa-weblogic.html#01[+зарегистрируйте сервер с помощью среды IDE+]. Кроме этого, если вы используете сервер WebLogic, просмотрите экранную демонстрацию link:../javaee/weblogic-javaee-m1-screencast.html[+Deploying a Web Application to Oracle WebLogic+] (Развертывание веб-приложения на Oracle WebLogic).


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

1. Щелкните правой кнопкой мыши узел  ``CalculatorWSApplication``  и выберите "Создать > Веб-служба".
2. Присвойте веб-службе имя  ``CalculatorWS``  и введите  ``org.me.calculator``  в поле "Пакет". Оставьте установленной кнопку-переключатель "Создать веб-службу с нуля".
3. При создании проекта Java EE на сервере GlassFish или WebLogic выберите 'Реализовать веб-службу' в качестве компонента сеанса без сохранения состояния. 
image::images/generate-ws-ee6.png[]
4. Нажмите кнопку 'Готово'. В окне "Проекты" отображается структура новой веб-службы, а в области редактора отображается исходный код.


==   Добавление операции к веб-службам

Целью этого упражнения является добавление к веб-службам операции, выполняющей сложение двух чисел, полученных от клиента. IDE NetBeans обеспечивает диалоговое окно для добавления операции с веб-службой. Это диалоговое окно можно открыть либо в визуальном конструкторе, либо в контекстном меню веб-службы.

*Внимание!* В проектах Maven визуальный конструктор недоступен.

*Для добавления операции в веб-службу выполните следующие действия.*

1. Либо
* измените представление "Конструктор" в окне редактора. 
image::images/design-view.png[]

Либо

* Найдите узел веб-службы в окне "Проекты". Щелкните узел правой кнопкой мыши. Откроется контекстное меню. 
image::images/add-op-cx-menu-item.png[]
2. Щелкните "Добавить операцию" либо в визуальном конструкторе, либо в контекстном меню. Откроется диалоговое окно "Добавление операции".
3. В верхней части диалогового окна "Добавить операцию" введите  ``add``  в 'Имя' и введите  ``int``  в раскрывающийся список "Тип возвращаемого значения".
4. В нижней части диалогового окна "Добавить операцию" нажмите кнопку "Добавить" и создайте параметр типа  ``int``  с именем  ``i`` .
5. Снова щелкните "Добавить" и создайте параметр типа  ``int``  с именем  ``j`` .

На экране должны быть представлены следующие параметры:


image::images/jaxws-60-add-operation.png[]
6. Нажмите кнопку "ОК" в нижней части диалогового окна "Добавить операцию". Вы вернетесь в редактор.
7. Удалите операцию по умолчанию  ``hello`` . Для этого либо удалите метод  ``hello()``  в исходном коде, либо выберите операцию  ``hello``  в визуальном конструкторе и щелкните "Удалить операцию".

Теперь в Visual Designer отображается следующее:


image::images/design-view-with-op.png[title="В Visual Designer веб-службы отображается добавленная операция"]
8. Нажмите кнопку "Исходный код" и посмотрите на код, созданный в результате предыдущих действий. Он будет различаться в зависимости от того, как создана служба: в качестве компонента Java EE без сохранения состояния или обычным способом. Обратите внимание на разницу в снимках экрана ниже: (Служба Java EE 6 или Java EE 7, не реализованная в качестве компонента без сохранения состояния, похожа на службу Java EE 5.)
image::images/jaxws-60-source.png[] image::images/stateless-ejb-code1.png[]

*Примечание.* При работе в IDE NetBeans 7.3 и 7.4 вы увидите, что в созданной аннотации  ``@WebService``  имя службы указано явно:
 ``@WebService(serviceName = "CalculatorWS")`` .

9. В редакторе расширьте схему операции  ``add``  следующим образом (изменения выделены полужирным шрифтом):

[source,java]
----

    @WebMethod
    public int add(@WebParam(name = "i") int i, @WebParam(name = "j") int j) {
        *int k = i + j;*
        return *k*;
      }
----

Как видно из указанного кода, веб-служба просто получает два числа и затем возвращает их сумму. В следующем разделе рассматривается тестирование веб-службы в среде IDE.


== Развертывание и тестирование веб-службы

После развертывания веб-службы на сервере можно использовать среду IDE для открытия клиента тестирования сервера, если у сервера имеется такой клиент. Серверы GlassFish и WebLogic предоставляют тестовые клиенты.

Если используется веб-сервер Tomcat, клиент тестирования отсутствует. Вы можете только запустить проект и проверить, открывается ли страница веб-служб Tomcat. В этом случае, прежде чем запустить проект, необходимо сделать веб-службу точкой входа в приложение. Чтобы сделать веб-службу точкой входа в приложение щелкните правой кнопкой мыши узел проекта CalculatorWSApplication и выберите 'Свойства'. Откройте 'Свойства выполнения' и введите  ``/CalculatorWS``  в поле 'Относительный адрес'. Нажмите кнопку "ОК". Запустите приложение (повторно щелкните правой кнопкой мыши узел проекта и выберите 'Выполнить').

*Для проверки успешности развертывания на сервере GlassFish или WebLogic выполните следующие действия.*

1. Щелкните проект правой кнопкой мыши и выберите команду "Развернуть". Запускается сервер приложений, выполняется сборка и развертывание приложения на сервере приложений. За ходом выполнения этих операций можно наблюдать в приложении CalculatorWSApplication (запуск-развертывание) и на вкладках серверов GlassFish или Tomcat в окне вывода.
2. На вкладке "Проекты IDE" разверните узел "Веб-службы" проекта "CalculatorWSApplication". Щелкните правой кнопкой мыши узел "CalculatorWS" и выберите "Тестировать веб-службу". 
image::images/jax-ws-testws.png[]

Страница тестирования открывается в браузере, если веб-приложение развернуто на сервере GlassFish. В случае использования веб-сервера Tomcat и развертывания модулей EJB ситуация отличается:

* Если развертывание выполнялось на GlassFish, введите на странице тестирования два числа, как показано ниже: 
image::images/jax-ws-tester.png[]

Отображается сумма этих двух чисел:


image::images/jax-ws-tester2.png[]


== [[Примеры]] 

Можно открыть полную версию компонента сеанса Java EE без сохранения состояния службы Calculator. Для этого выберите Файл > Создать проект (Ctrl-Shift-N в Linux и Windows, ⌘ + Shift + N в MacOS) и перейдите в раздел Образцы > Веб-службы Java > Calculator (EE6).

Служба и клиент калькулятора Maven доступны в пункте "Примеры > Maven".


== Использование веб-службы

После успешного развертывания веб-службы необходимо создать клиент для использования метода веб-службы  ``add`` . Ниже будет рассмотрено создание трех клиентов: класса Java в приложении для Java SE, сервлета и страницы JSP в веб-приложении.

*Примечание.* Более расширенный учебный курс сосредоточен на клиентах: link:../../../kb/docs/websvc/client.html[+Разработка клиентов веб-служб JAX-WS+].


=== Клиент 1: класс Java в приложении для Java SE

В этом разделе будет рассмотрено создание стандартного приложения Java. Мастер, используемый для создания приложения, также создает и класс Java. Затем средства среды IDE будут использоваться для создания клиента и использования веб-службы, созданной в начале этого руководства.

1. Выберите 'Файл' > 'Создать проект' (Ctrl-Shift-N в Windows и Linux, ⌘-Shift-N в ОС Mac). Выберите "Приложение Java" в категории "Java". Присвойте проекту имя  ``CalculatorWS_Client_Application`` . Не снимайте флажок "Создать главный класс" и оставьте все прочие значения по умолчанию. Нажмите кнопку 'Готово'.
2. Щелкните правой кнопкой мыши узел  ``CalculatorWS_Client_Application``  и выберите "Создать > Клиент веб-службы". Появится мастер создания клиента веб-службы.
3. Выберите проект в виде исходного файла WSDL. Нажмите кнопку "Обзор". В проекте CalculatorWSApplication перейдите к веб-службе CalculatorWS. Выберите веб-службу и нажмите кнопку "ОК".
image::images/browse-ws.png[]
4. Не выбирайте имя пакета. Оставьте это поле пустым.
image::images/javaclient-pkg.png[]
5. Оставьте значения остальных параметров по умолчанию и нажмите кнопку "Готово".

В окне "Проекты" появится новый клиент веб-службы с узлом для созданного метода ``add`` :


image::images/ws-ref-in-client-project.png[]
6. Дважды щелкните главный класс, чтобы открыть его в редакторе исходного кода. Перетащите узел  ``add``  в местоположение ниже метода  ``main()`` .
image::images/dnd-add.png[]

На экране должны быть представлены следующие параметры:


[source,java]
----

public static void main(String[] args) {
    // TODO code application logic here
}
private static int add(int i, int j) {
    org.me.calculator.CalculatorWS_Service service = new org.me.calculator.CalculatorWS_Service();
    org.me.calculator.CalculatorWS port = service.getCalculatorWSPort();
    return port.add(i, j);
}
----

*Примечание.* В качестве альтернативы, вместо перетаскивания узла  ``add``  можно щелкнуть правой кнопкой мыши в редакторе, а затем выбрать 'Вставить код' > 'Dspdfnm операцию с веб-службой'.

7. В теле метода  ``main()``  замените комментарий TODO кодом, который инициализирует значения для  ``i``  и  ``j`` , вызывает  ``add()``  и распечатывает результат.

[source,java]
----

public static void main(String[] args) {int i = 3;int j = 4;int result = add(i, j);System.out.println("Result = " + result);
}
----
8. Окружите код метода  ``main()``  блоком try/catch, который распечатывает исключение.

[source,java]
----

public static void main(String[] args) {try {int i = 3;int j = 4;int result = add(i, j);System.out.println("Result = " + result);} catch (Exception ex) {System.out.println("Exception: " + ex);}
}
----
9. Щелкните правой кнопкой мыши узел проекта и выберите "Выполнить".

Теперь в окне "Вывод" отображается сумма:


[source,java]
----

    compile:
    run:
    Result = 7
      BUILD SUCCESSFUL (total time: 1 second)
----


=== Клиент 2: сервлет в веб-приложении

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

1. Выберите 'Файл' > 'Создать проект' (Ctrl-Shift-N в Windows и Linux, ⌘-Shift-N в ОС Mac). Выберите "Веб-приложение" в категории "Java Web". Дайте проекту имя  ``CalculatorWSServletClient`` . Нажмите кнопку "Далее", а затем нажмите кнопку "Готово".
2. Щелкните правой кнопкой мыши узел  ``CalculatorWSServletClient``  и выберите "Создать > Клиент веб-службы".

Появится мастер создания клиента веб-службы.

3. В качестве источника WSDL выберите "Проект" и нажмите кнопку "Обзор", чтобы открыть диалоговое окно "Обзор веб-служб".
4. В проекте CalculatorWSApplication выберите веб-службу CalculatorWS. Нажмите кнопку OK, чтобы закрыть диалоговое окно "Обзор веб-служб".
image::images/browse-ws.png[]
5. Оставьте поле "Имя пакета" в мастере создания клиентов веб-службы пустым и не меняйте значения всех остальных параметров, заданные по умолчанию. Нажмите "Готово".

Узел "Ссылки на веб-службу" в окне "Проекты" отражает структуру только что созданного клиента, включая операцию  ``add`` , рассмотренную ранее в этом учебном курсе.

6. Щелкните правой кнопкой мыши узел проекта  ``CalculatorWSServletClient``  и выберите "Создать > Сервлет". Дайте сервлету имя  ``ClientServlet``  и поместите его в пакет с именем  ``org.me.calculator.client`` . Нажмите кнопку 'Готово'.
7. Чтобы сделать сервлет точкой ввода в приложении щелкните правой кнопкой мыши узел проекта CalculatorWSServletClient и выберите 'Свойства'. Откройте "Свойства выполнения" и введите  ``/ClientServlet``  в поле "Относительный адрес". Нажмите кнопку "ОК".
8. При наличии значков ошибок для  ``ClientServlet.java``  щелкните правой кнопкой мыши узел проекта и выберите 'Очистка и сборка'.
9. В методе  ``processRequest()``  добавьте несколько пустых строк после следующей строки:

[source,xml]
----

    out.println("<h1>Servlet ClientServlet at " + request.getContextPath () + "</h1>");
----
10. В редакторе исходного кода перетащите операцию  ``add``  в любое место тела класса  ``ClientServlet`` . Метод  ``add()``  отображается в конце кода класса.

*Примечание.* В качестве альтернативы, вместо перетаскивания узла  ``add``  можно щелкнуть правой кнопкой мыши в редакторе, а затем выбрать 'Вставить код' > 'Dspdfnm операцию с веб-службой'.


[source,java]
----

private int add(int i, int j) {org.me.calculator.CalculatorWS port = service.getCalculatorWSPort();return port.add(i, j);
}
----
11. Добавьте код, который инициализирует значения для  ``i``  и  ``j`` , вызывает  ``add()``  и распечатывает результат. Добавленный код выделяется *полужирным начертанием*:

[source,xml]
----

protected void processRequest(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
    response.setContentType("text/html;charset=UTF-8");
    PrintWriter out = response.getWriter();
    try {
        out.println("<html>");
        out.println("<head>");
        out.println("<title>Servlet ClientServlet</title>");
        out.println("</head>");
        out.println("<body>");
        out.println("<h1>Servlet ClientServlet at " + request.getContextPath () + "</h1>");

    *    int i = 3;
int j = 4;
int result = add(i, j);
out.println("Result = " + result);*

        out.println("</body>");
        out.println("</html>");
        
    } finally {            out.close();}}
----
12. Окружите добавленный код блоком try/catch, который распечатывает исключение.

[source,xml]
----

protected void processRequest(HttpServletRequest request, HttpServletResponse response)
         throws ServletException, IOException {
    response.setContentType("text/html;charset=UTF-8");
    PrintWriter out = response.getWriter();
    try {
        out.println("<html>");
        out.println("<head>");
        out.println("<title>Servlet ClientServlet</title>");
        out.println("</head>");
        out.println("<body>");
        out.println("<h1>Servlet ClientServlet at " + request.getContextPath () + "</h1>");
        *try {*
            int i = 3;int j = 4;int result = add(i, j);out.println("Result = " + result);
        *} catch (Exception ex) {
            out.println("Exception: " + ex);
        }*
        out.println("</body>");
        out.println("</html>");
        
    } finally {            out.close();}}
----
13. Щелкните правой кнопкой мыши узел проекта и выберите "Выполнить".

Запускается сервер, выполняются сборка и развертывание приложения, и открывается браузер, в котором отображается результат вычисления, как показано ниже: 
image::images/jaxws-60-webclient.png[]


=== Клиент 3: страница JSP в веб-приложении

В этом разделе описана процедура создания нового веб-приложения и использование веб-службы на странице JSP по умолчанию, созданной с помощью мастера "Веб-приложение".

*Примечание.* Если необходимо запустить клиент веб-приложения JSP в Oracle WebLogic см. link:../web/jsf-jpa-weblogic.html[+Запуск приложения Java Server Faces 2.0 в WebLogic+].

1. Выберите 'Файл' > 'Создать проект' (Ctrl-Shift-N в Windows и Linux, ⌘-Shift-N в ОС Mac). Выберите "Веб-приложение" в категории "Java Web". Дайте проекту имя  ``CalculatorWSJSPClient`` . Нажмите кнопку "Далее", а затем нажмите кнопку "Готово".
2. Раскройте узел "Веб-страницы" под узлом проекта и удалите файл  ``index.html`` .
3. Щелкните правой кнопкой мыши узел  ``Веб-страницы``  и выберите пункт меню "Создать > JSP".

Если в меню отсутствует пункт "JSP", выберите "Создать > Другие", затем выберите JSP в категории "Веб" мастера создания файлов.

4. В качестве имени файла JSP в мастере создания файлов укажите *index*. Нажмите "Готово".
5. Щелкните правой кнопкой мыши узел  ``CalculatorWSJSPClient``  и выберите "Создать > Клиент веб-службы".
6. Выберите проект в виде исходного файла WSDL. Нажмите кнопку "Обзор". В проекте CalculatorWSApplication перейдите к веб-службе CalculatorWS. Выберите веб-службу и нажмите кнопку "ОК".
image::images/browse-ws.png[]
7. Не выбирайте имя пакета. Оставьте это поле пустым.
8. Оставьте значения остальных параметров по умолчанию и нажмите кнопку "Готово".

В окне "Проекты" появится новый клиент веб-службы, как показано ниже:

image::images/ws-ref-in-jsp-client.png[]
9. В узле "Ссылки на веб-службы" разверните узел, соответствующий веб-службе. Теперь показана операция  ``add`` , которую требуется вызывать посредством клиента.
10. Перетащите операцию  ``add``  на страницу клиента  ``index.jsp``  ниже тегов H1. Теперь на странице  ``index.jsp``  отображается код для вызова операции службы, показанный ниже:

[source,java]
----

<%
try {
    org.me.calculator.CalculatorWSService service = new org.me.calculator.CalculatorWSService();
    org.me.calculator.CalculatorWS port = service.getCalculatorWSPort();
     // TODO initialize WS operation arguments here
    int i = 0;
    int j = 0;
    // TODO process result here
    int result = port.add(i, j);
    out.println("Result = "+result);
} catch (Exception ex) {
    // TODO handle custom exceptions here
}
%>
----

Измените значения для  ``i``  и  ``j``  с 0 на другие целые числа, например, на 3 и 4. В блоке "catch" замените закомментированную строчку "TODO" на  ``out.println("exception" + ex);`` .

11. Щелкните правой кнопкой мыши узел проекта и выберите "Выполнить".

Запускается сервер, если он не был запущен ранее. После сборки и развертывания приложения открывается браузер, в котором отображается результат вычисления:

image::images/jax-ws-project-jsp-result.png[]


link:/about/contact_form.html?to=3&subject=Feedback:%20JAX-WS%20Services%20in%20NetBeans%20IDE[+Отправить отзыв по этому учебному курсу+]


== Дополнительные сведения

Подробнее об использовании IDE NetBeans для разработки приложений Java EE см. в следующих ресурсах:

* link:./client.html[+Разработка клиентов веб-служб JAX-WS+]
* link:./rest.html[+Начало работы с веб-службами RESTful+]
* link:./wsit.html[+Расширенные возможности взаимодействия веб-служб+]
* link:../../../kb/trails/web.html[+Учебная карта по веб-службам+]

Для отправки комментариев и предложений, получения поддержки и новостей о последних разработках, связанных с Java EE IDE NetBeans link:../../../community/lists/top.html[+присоединяйтесь к списку рассылки nbj2ee@netbeans.org+].