// 
//     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.
//

= Общие сведения о внедрении контекстов и зависимостей и JSF 2.x
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Общие сведения о внедрении контекстов и зависимостей и JSF 2.x - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Общие сведения о внедрении контекстов и зависимостей и JSF 2.x

_Предоставлено Энди Гибсоном (Andy Gibson)_

== Внедрение контекстов и зависимостей

1. *Введение в CDI и JSF 2.0*
* <<creating,Создание веб-проекта Java с поддержкой CDI >>
* <<named,Доступ к компонентам из языка выражений JSF>>
* <<upgrading,Переход к EJB>>
* <<seealso,Дополнительные сведения>>


. link:cdi-inject.html[+Работа с внедрением и квалификаторами в CDI+]


. link:cdi-validate.html[+Применение аннотации @Alternative и аннотаций жизненного цикла+]


. link:cdi-events.html[+Обработка событий в CDI+]

Внедрение контекстов и зависимостей (CDI), определяемое документом link:http://jcp.org/en/jsr/detail?id=299[+JSR-299+], является неотъемлемой частью Java EE 6 и обеспечивает архитектуру, позволяющую компонентам Java EE (например, сервлетам, компонентам EJB и JavaBeans) существовать в жизненном цикле приложения с четко определенными контекстами. Кроме того, службы CDI позволяют компонентам Java EE (например, компонентам сеансов EJB и управляемым компонентам JavaServer Faces) внедряться и свободно взаимодействовать путем запуска и обработки событий.

Этот учебный курс основан на записи блога Энди Гибсона (Andy Gibson) link:http://www.andygibson.net/blog/index.php/2009/12/16/getting-started-with-jsf-2-0-and-cdi-in-jee-6-part-1/[+Введение в JSF 2.0 и CDI в JEE 6+]. В нем рассматривается использование среды IDE для настройки веб-проекта Java с поддержкой JSF 2.0 и CDI. Затем описано связывание управляемых компонентов CDI со страницами Facelets и приводится краткий пример интеграции CDI и технологии EJB.

В NetBeans IDE обеспечена встроенная поддержка для внедрения контекстов и зависимостей, включая поддержку создания файла конфигурации CDI `beans.xml` при создании проекта, поддержку редактора и навигации для аннотаций, а также различных мастеров для создания часто используемых артефактов CD.


Для работы с этим учебным курсом требуется программное обеспечение и материалы, перечисленные ниже.

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

|link:https://netbeans.org/downloads/index.html[+IDE NetBeans+] |7.2, 7.3, 7.4, 8.0, пакет Java EE 

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

|link:http://glassfish.dev.java.net/[+Сервер GlassFish+] |Open Source Edition 3.x или 4.x 
|===

NOTE: В комплект Java для IDE NetBeans также входит компонент GlassFish Server Open Source Edition, являющийся контейнером, совместимым с Java EE.


[[creating]]
== Создание веб-проекта Java с поддержкой CDI

В этом упражнении выполняется создание веб-проекта Java с поддержкой JSF 2.x и CDI.

1. Нажмите кнопку 'Создать проект' ( image:images/new-project-btn.png[] ) на главной панели инструментов IDE (Ctrl-Shift-N; ⌘-Shift-N в Mac).
2. В мастере создания проекта выберите категорию Java Web и команду "Веб-приложение". Нажмите кнопку "Далее".
3. Введите `cdiDemo` в качестве имени проекта и укажите местоположение проекта. Нажмите кнопку "Далее".
4. Выберите GlassFish в качестве сервера.
5. В качестве версии Java EE выберите Java EE 6 или Java EE 7 Web.

NOTE:  От выбранной версии Java EE зависит, какая версия CDI будет поддерживаться в приложении. Следует помнить, что между версиями CDI 1.0 и CDI 1.1 существует ряд различий.

* Если в качестве версии Java EE выбрана Java EE 6 Web, убедитесь, что выбран параметр "Разрешить внедрение контекстов и зависимостей". При выборе параметра "Включить внедрение контекстов и зависимостей" создается файл `beans.xml` в папке проекта `WEB-INF` при создании шаблона проекта. Файл `beans.xml` используется CDI для указания серверу, совместимому с Java EE, что проект является модулем, содержащим компоненты CDI. Java EE 6 Web поддерживает CDI 1.0, и в создаваемом файле `beans.xml` будет указана версия CDI 1.0.
* Если в качестве версии Java EE указана Java EE 7 Web, по умолчанию включается поддержка версии CDI 1.1, и файл  ``beans.xml``  не требуется. В Java EE 7 при отсутствии файла  ``beans.xml``  развертываемый архив считается *архивом неявного компонента bean*. Файл `beans.xml` в приложениях Java EE 7 Web создается с помощью мастера создания файлов IDE. По умолчанию развернутый архив становится *архивом явного компонента bean*, поскольку в файле `beans.xml` указывается версия CDI 1.1 и атрибут  ``bean-discovery-mode``  получает значение  ``all`` .

Подробные сведения о типах архивов CDI см. в разделе link:http://docs.oracle.com/javaee/7/tutorial/doc/cdi-adv001.htm[+Упаковка приложений CDI+] в руководстве по Java EE 7.

image::images/new-web-application1.png[title="Если выбран параметр CDI, он создает файл beans.xml для проекта"]


. Нажмите кнопку "Далее".


. На панели "Платформы" выберите параметр JavaServer Faces.


. Перейдите на вкладку "Настройка" и убедитесь, что в качестве предпочтительного языка страницы выбран "Facelets". Нажмите кнопку "Завершить".

При нажатии кнопки "Завершить" в среде IDE создается проект веб-приложения и в редакторе открывается страница приветствия `index.xhtml`.


. В окне "Проекты" разверните узел "Библиотеки > GlassFish Server". Вы увидите, что в этот узел автоматически добавлена библиотека `weld-osgi-bundle.jar`. В состав сервера GlassFish входит Weld, который является реализацией спецификации CDI JSR-299 от JBoss. 

image::images/projects-window1.png[title="Новый проект содержит файл beans.xml CDI, а библиотека GlassFish включает файл Weld JAR"]

Обратите внимание, что если при создании проекта была выбрана версия Java EE 6 Web, папка "Web Pages > WEB-INF" будет содержать файл `beans.xml`. Файл пуст, но может использоваться как альтернатива аннотациям для указания информации, связанной с компонентами, в формате XML.


[[named]]
== Доступ к Beans из языка выражений JSF

В этом упражнении демонстрируется способ связи компонентов, управляемых CDI, со страницами Facelets с помощью синтаксиса EL.


. В окне "Проекты" щелкните правой кнопкой узел "Исходные файлы" и выберите команду "Создать" > "Класс Java".


. В мастере создания класса Java введите имя класса *MessageServerBean* и введите *exercise1* в поле "Пакет". Новый пакет будет создан после завершения работы мастера. Нажмите "Готово". 

image::images/new-java-class.png[title="Создайте новые классы Java с помощью мастера классов Java"]

Создаются новый пакет и класс, после чего класс открывается в редакторе.


. Добавьте к классу аннотации `@Named` и `@Dependent` и создайте одиночный метод для возврата строки.

[source,java]
----

package exercise1;

*import javax.enterprise.context.Dependent;
import javax.inject.Named;*

*@Dependent
@Named*
public class MessageServerBean {

    *public String getMessage() {
        return "Hello World!";
    }*
}
----

Во время добавления аннотаций `@Dependent` и `@Named` нажмите сочетание клавиш Ctrl-Пробел, чтобы включить в редакторе поддержку автозавершения кода и документации Javadoc. Если применить аннотацию с помощью функций автозавершения кода редактора (например, выбрав подходящую аннотацию и нажав ENTER), в файл автоматически добавляется оператор `импорта `. Во всплывающем окне Javadoc также можно нажать кнопку 'Показывать документацию во внешнем веб-браузере' ( image:images/external-web-browser-btn.png[] ) для отображения полноразмерного Javadoc в отдельном окне.

NOTE:  Аннотация  ``@Dependent``  определяет область действия управляемого компонента bean. В *архиве неявного компонента bean* управляемый компонент bean доступен только для обнаружения и может управляться контейнером, только если указана область действия. В данном упражнении приложение будет упаковано как архив неявного компонента bean (при условии, что в качестве версии проекта выбрана Java EE 7 и не создан файл  ``beans.xml`` ). Подробные сведения об области действия управляемых компонентов bean см. в разделе link:http://docs.oracle.com/javaee/7/tutorial/doc/jsf-configure001.htm[+Настройка управляемых компонентов bean с помощью аннотаций+] учебного курса по Java EE 7.


. Сохраните файл (сочетание клавиш Ctrl-S; ⌘-S в Mac). После добавления аннотации `@Named` класс `MessageServerBean` стал _ управляемым компонентом _, в соответствии с определением CDI.


. Переключитесь в редакторе на страницу Facelets `index.xhtml`(нажмите сочетание клавиш CTRL+TAB) и добавьте следующий текст в теги `<h:body>`.

[source,xml]
----

<h:body>
    Hello from Facelets
    *<br/>
    Message is: #{messageServerBean.message}
    <br/>
    Message Server Bean is: #{messageServerBean}*
</h:body>
----

TIP: Для отображения подсказок автозавершения кода можно нажать сочетание клавиш CTRL+ПРОБЕЛ внутри выражения EL. Списки автозавершения редактора содержат управляемые компоненты и их свойства. Поскольку аннотация `@Named` преобразует класс `MessageServerBean` в управляемый компонент, он становится доступным в синтаксисе EL, как если бы он был управляемым компонентом JSF.# 

image::images/facelets-el-completion.png[title="Создайте новые классы Java с помощью мастера классов Java"]


. Нажмите кнопку 'Запустить проект' (image:images/run-project-btn.png[]) на главной панели инструментов IDE. Файл компилируется и развертывается в GlassFish, и страница приветствия приложения (`index.xhtml `) отображается в веб-браузере. На странице отображается текст "Hello World!" из `MessageServerBean`. 

image::images/browser-output1.png[title="На странице приветствия приложения отображаются сведения о MessageServerBean"]


. Вернитесь к компоненту сообщения и измените сообщение на другое (например, "Hello Weld!"). Сохраните файл (Ctrl-S; ⌘-S в Mac), затем обновите браузер. Автоматически отображается новое сообщение. Это происходит благодаря возможности "Развертывание при сохранении" среды IDE, все сохраненные изменения вызывают компиляцию и повторное развертывание на сервере. 

В третьей строке на этой странице видно, что имя класса – `exercise1.MessageServerBean` Обратите внимание, что компонент представляет собой объект POJO (Plain Old Java Object, простой старый объект Java). Несмотря на использование Java EE, при разработке отсутствует комплексная иерархия классов, связанная уровнями транзакций, перехватами и другие сложные особенности.


=== Порядок действий

При развертывании приложения сервер осуществляет поиск управляемых bean-компонентов CDI. В приложениях Java EE 7 классы на пути по умолчанию проверяются на наличие аннотаций CDI. В приложениях Java EE 6 классы проверяются на наличие аннотаций CDI, если модуль содержит файл `beans.xml`. В модуле CDI все компоненты регистрируются в Weld, и для сопоставления компонентов с точками внедрения используется аннотация `@Named`. При отображении страницы `index.xhtml` JSF пытается разрешить значение `messageServerBean` на странице с применением зарегистрированных средств разрешения выражений JSF. Одно из них – средство разрешения Weld EL имеет класс `MessageServerBean`, зарегистрированный под именем `MessageServerBean` Можно было указать другое имя в аннотации `@Named`, но поскольку это не было сделано, класс был зарегистрирован под именем по умолчанию, которое совпадает с именем класса, первая буква которого находится в нижнем регистре. Средство разрешения Weld возвращает экземпляр этого компонента в ответ на запрос JSF. Именование компонентов требуется только при использовании выражений EL и не должно использоваться в качестве механизма внедрения, поскольку CDI обеспечивает безопасность по типу при внедрении по типу класса и аннотациям квалификатора.


[[upgrading]]
== Переход к EJB

Благодаря EJB 3.1 и использованию стека Java EE можно с небольшими изменениями легко развертывать компонент в качестве EJB.

1. Откройте `MessageServerBean` и добавьте аннотацию `javax.ejb.Stateless` на уровне класса, затем замените строку на "Hello EJB!".

[source,java]
----

package exercise1;

*import javax.ejb.Stateless;*
import javax.enterprise.context.Dependent;
import javax.inject.Named;

/**
 *
 * @author nbuser
 */
@Dependent
@Named
*@Stateless*
public class MessageServerBean {

    public String getMessage() {
        return "*Hello EJB!*";
    }
}
----


. Сохраните файл (Ctrl-S; ⌘-S в Mac), затем перейдите в браузер и обновите. Отображается приблизительно следующее: 

image::images/browser-output-ejb1.png[title="Использование аннотации @Stateless преобразует MessageServerBean в EJB"] 

Поразительно, POJO превратился в полнофункциональный EJB с помощью всего одной аннотации. После сохранения изменений и обновления страницы были отображены изменения. Для этого не потребовалось проводить комплексную настройку проекта, создавать локальные интерфейсы или сложные дескрипторы развертывания.


=== Различные типы EJB

Также можно использовать аннотацию `@Stateful`. В качестве альтернативы можно использовать новую аннотацию `@Singleton` для экземпляров единичных классов. При этом существует две аннотации: `javax.ejb.Singleton` и `javax.inject.Singleton`. Эти аннотации соответствуют двум видам единичных классов. Единичный класс CDI `javax.inject.Singleton` позволяет определить экземпляр единичного класса вне EJB при использовании CDI в окружении, отличном от EJB. Единичный класс EJB `javax.ejb.Singleton` предоставляет все возможности EJB, например управление транзакциями. Поэтому можно сделать выбор в зависимости от потребностей и от того, используется ли среда EJB.

link:/about/contact_form.html?to=3&subject=Feedback:%20Getting%20Started%20with%20CDI%20and%20JSF%202.0[+Отправить отзыв по этому учебному курсу+]


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

В следующей части рассматривается внедрение CDI и приводятся подробные сведения об использовании CDI для управления зависимостями в среде Java EE.

* link:cdi-inject.html[+Работа с внедрением и квалификаторами в CDI+]

Дополнительные сведения о CDI и JSF 2.0 приведены в следующих материалах.


=== Внедрение контекстов и зависимостей

* link:cdi-validate.html[+Применение аннотации @Alternative и аннотаций жизненного цикла+]
* link:cdi-events.html[+Обработка событий в CDI+]
* link:http://blogs.oracle.com/enterprisetechtips/entry/using_cdi_and_dependency_injection[+Технические рекомендации по Java EE: использование CDI и внедрения зависимостей для Java в приложении JSF 2.0+]
* link:http://docs.oracle.com/javaee/7/tutorial/doc/cdi-basic.htm[+Учебный курс по Java EE 6. Вводная информация о внедрении контекстов и зависимостей для Java EE+]
* link:http://jcp.org/en/jsr/detail?id=299[+JSR 299: спецификация внедрения контекстов и зависимостей+]


=== JavaServer Faces 2.0

* link:../web/jsf20-intro.html[+Введение в JavaServer Faces 2.x+]
* link:../web/jsf20-crud.html[+Создание приложения JavaServer Faces 2.x CRUD на основе базы данных+]
* link:../../samples/scrum-toys.html[+Scrum Toys – полный пример приложения JSF 2.0+]
* link:http://www.oracle.com/technetwork/java/javaee/javaserverfaces-139869.html[+Технология JavaServer Faces+] (официальная домашняя страница)
* link:http://docs.oracle.com/javaee/7/tutorial/doc/jsf-page.htm[+Учебный курс по Java EE 7. Использование технологии JavaServer Faces на веб-страницах+]
* link:http://jcp.org/en/jsr/summary?id=314[+Спецификация JSR 314 для JavaServer Faces 2.0+]