type="javax.mail.Session")

})

public class SomeMessageBean {

...

}

Код показывает аннотацию @Resource, содержащую две декларации @

Resource. Одна — очередь Java Message Service (JMS), другая — сеанс JavaMailTM.

15.4. Адаптеры ресурсов

Адаптер ресурса является компонентом Java EE, который реализует архитек-

туру Java EE Connector Architecture для системы Enterprise Information System (EIS).

Примерами EIS являются системы планирования ресурсов предприятия (ERP), об-

работки транзакций (TP) и баз данных. Адаптер ресурсов облегчает связь между при-

ложением Java EE и EIS.

Расположенный в файле Resource Adapter Archive (RAR) адаптер ресурса может быть развернут на любом сервере Java EE, наподобие приложения Java EE. Файл

RAR может содержаться в файле архива (EAR) или может существовать как отдель-

ный файл.

Адаптеры ресурса аналогичны драйверу JDBC. Оба обеспечивают стандартный API, через который приложение может иметь доступ к ресурсу за пределами сервера Java EE. Для адаптера ресурса целевая система — EIS; для драйвера JDBC — это DBMS (СУБД). Адаптеры ресурсов и драйверы JDBC используются прикладными раз-

работчиками. В большинстве случаев оба типа программного обеспечения поступают

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

Контракты адаптера ресурса

Адаптер ресурса — посредник между сервером Java EE и EIS, использующий

интерфейсы (контракты). Контракт приложения определяет API, через который ком-

понент Java EE, например, бин, получает доступ к EIS. Этот API — единственный способ доступа к EIS. Системные контракты ссылаются на сервисы адаптера ресурса, которые управляются сервером Java EE. Сам адаптер ресурса и системные контракты прозрачны для компонент Java EE.

Контракты управления

Архитектура соединений Java EE определяет системные контракты, которые позволяют управлять жизненным циклом адаптерного ресурса и потоками данных.

Управление жизненным циклом архитектуры коннекторов определяет контракт,

который позволяет серверу управлять жизненным циклом адаптера ресурса. Этот

контракт обеспечивает для сервера механизм начальной загрузки экземпляра адап-

тера ресурса в период развертывания или запуска сервера. Он также обеспечивает

средства для сервера, чтобы уведомить адаптер ресурса, когда он выгружается или когда происходит нормальное выключение сервера.

Контракт управления работой

Контракт управления работой архитектуры коннекторов гарантирует, что адаптеры ресурса используют процесс («нить») соответствующим допустимым способом.

Это позволяет прикладному серверу управлять процессом для адаптеров ресурса.

Адаптеры ресурса, которые неправильно используют процессы, могут подвергнуть опасности весь сервер. Например, адаптер ресурса мог создать слишком много

184

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

сервера, поскольку создание и уничтожение процесса являются затратными опера-

циями.

Контракт управления работой устанавливает пул средств для прикладного сер-

вера и многократного использования процессов, аналогично пулу соединений для повторного их использования. Придерживаясь этого контракта, адаптер ресурса не дол-

жен сам управлять процессом. Вместо этого адаптер ресурса заставляет прикладной

сервер создавать и обеспечивать нужные нити. Когда адаптер ресурса завершается

в данной нити, он возвращает её серверу. Прикладной сервер, управляя процессом,

может вернуть его в пул и использовать многократно позже, или же он может уничтожить процесс. Обрабатывая нить этим способом, сервер улучшает скорость работы и

более эффективное использование ресурсов.

Помимо передачи управления процессами прикладному серверу, архитектура

коннекторов обеспечивает гибкую модель для адаптера ресурса, который использует

процесс:

•запрос может заказать блокировку (остановить свое собственное выполнение), пока рабочая нить не завершится;

•запрос может блокироваться, пока он ожидает получение рабочей нити. Когда прикладной сервер возвратит рабочую нить, запрашивающая нить и рабочая нить выполняются параллельно;

•адаптер ресурса может поставить работу для нити в очередь. Нить выполнит работу из очереди в последующее время. Адаптер ресурса продолжает свое собственное выполнение из точки, в которой он передал работу в очередь параллельно с её выполнением.

С последними двумя методами запрашивающий процесс и рабочий процесс мо-

гут выполняться одновременно независимо друг от друга. Для этих методов контракт

определяет механизм слушателей, чтобы уведомить адаптер ресурса о завершении нитью своей операции.

Адаптер ресурса может также определить контекст выполнения для нити и для элементов управления контекстом, в котором нить выполняется.

Контракт общего рабочего контекста

Контракт общего рабочего контекста позволяет адаптеру ресурса управлять контекстами, в которых представленный экземпляр Work выполняется серверным

WorkManager. Контракт общего рабочего контекста также позволяет серверу поддерживать новый приток сообщений и схемы поставки. Он также обеспечивает развитое

окружение выполнения рабочего контекста для адаптера ресурса, пока сохраняется контроль над параллельным поведением в управляющей среде.

Контекст общего рабочего контракта предписывает следующие контексты:

Transaction Context и Security Context.

Контекст транзакции

Контекст транзакции между адаптером ресурса и прикладным сервером исполь-

зуетвкачествемеханизмаGeneric Work Context, описывающийстандартыWorkContext и TransactionContext. Он представляет стандартный интерфейс для использования адаптером ресурса, чтобы передавать контекстную информацию транзакции от EIS к серверу.

185

Контекст безопасности

Контекст безопасности между адаптером ресурса и сервером использует в качестве механизма Generic Work Context, описывающий стандарты WorkContext и

TransactionContext. Он может быть предусмотрен адаптером ресурса при передаче

работы на выполнение. SecurityContext обеспечивает портируемый механизм для

адаптера ресурса, чтобы передавать контекстную информацию безопасности в при-

кладной сервер. Этот рабочий контекст используется EIS или адаптером ресурса в контекстной информации безопасности потока, передавая работу в WorkContext для

выполнения.

15.5. Аннотации метаданных

Архитектура Java EE Connector Architecture 1.6 предлагает множество аннотаций, чтобы минимизировать потребность в дескрипторах развертывания.

Аннотация @Connector может быть использована разработчиком для задания

компонента JavaBeans как адаптера ресурса. Эта аннотация используется для обе-

спечения метаданных о возможностях адаптера ресурса. Дополнительно можно соз-

дать компонент JavaBeans как реализацию интерфейса ResourceAdapter.

Аннотация @ConnectionDefinition определяет набор интерфейсов связи и классов, относящихся к конкретному типу коннектора. Роль этой аннотации идентична роли

элемента connection-definition в дескрипторе развертывания.

Аннотация @AdministeredObject определяет компонент JavaBeans как управляющий объект.

Аннотация @Activation содержит информацию конфигурации, относящуюся к внутренности коннектора для экземпляра EIS.

Аннотация@ConfigPropertyможетбытьиспользованавкомпонентахJavaBeans,

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

струментальные средства конфигурации, чтобы автоматически исследовать свойства

конфигурации компонента JavaBeans через обследование JavaBeans и не требует использования дескриптора развертывания.

Спецификация дает возможность адаптеру ресурса работать в режиме смешан-

ных форм, что позволяет разработчику адаптера ресурса использовать как аннотации

метаданных, так и дескрипторы развертывания в приложениях. Компоновщик приложения может использовать дескриптор развертывания, чтобы отменить аннотации ме-

таданных, определённые разработчиком адаптера ресурса.

Новый атрибут metadata-complete введен в дескриптор развертывания

Connector 1.6 (файл ra.xml). Атрибут metadata-complete определяет, что дескриптор

развертывания для адаптерного модуля ресурса завершен, и файлы класса модуля

адаптера ресурса должны быть изучены на наличие аннотаций, которые определяют

информацию развертывания.

Для просмотра полного списка аннотаций и компонентов JavaBeans, введенных в Java EE 6, обратитесь к ресурсу http://jcp.org/en/jsr/detail?id=322.

Использование аннотаций во многих случаях уменьшает или полностью устра-

няет необходимость в дескрипторах развертывания. Использование аннотаций также

186

уменьшает необходимость синхронизировать изменения в дескрипторе развертыва-

ния и исходном коде.

Следующие примеры показывают дескрипторы развертывания и эквивалентные аннотации.

Пример 1

Аннотация @Connector

Следующий дескриптор развертывания определяет соединение:

<connector xmlns "http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/connector_1_6.xsd" version="1.6">

<description>Sample adapter using the JavaMail API</description> <display-name>InboundResourceAdapter</display-name> <icon></icon>

<vendor-name>Sun Microsystems, Inc</vendor-name> <eis-type>MAIL</eis-type> <resourceadapter-version>1.0</resourceadapter-version>

...

...

...

<authentication-mechanism> <authentication-mechanism-type>BasicPassword</authentication-

mechanism-type> <credential-interface>javax.resource.spi.security. PasswordCredential</credential-interface> </authentication-mechanism> <reauthentication-support>false</reauthentication-support>

...

...

</connector>

Эквивалентная аннотация метаданных выглядит следующим образом:

@Connector(

description = "Sample adapter using the JavaMail API", displayName = "InboundResourceAdapter",

vendorName = "Sun Microsystems, Inc.", eisType = "MAIL",

version = "1.0", authMechanisms = {

@AuthenticationMechanism( authMechanism = "BasicPassword",

credentialInterface = AuthenticationMechanism.CredentialInterface.PasswordCredential

)

}

187

/*

//Since the following attribute values denote the default values of the annotation,

//they need not be specified explicitly

transactionSupport =

TransactionSupport.TransactionSupportLevel.NoTransaction, reauthenticationSupport = false

*/

)

public class ResourceAdapterImpl

implements ResourceAdapter, java.io.Serializable

{

...

...

}

Пример 2

Аннотация @ConnectionDefinition

Фрагмент дескриптора следующего развертывания описывает определение соединения:

<connection-definition> <managedconnectionfactory-class> samples.mailra.ra.outbound.ManagedConnectionFactoryImpl </managedconnectionfactory-class> <config-property><config-property-name>serverName</config- property-name>

<config-property-type>java.lang.String</config-property-type> <config-property-value>UnknownHostName</config-property-value>

...

...

<connectionfactoryinterface>samples.mailra.api.JavaMailConnectionFactory</connection factory-interface>

<connectionfactory-impl- class>samples.mailra.ra.outbound.JavaMailConnectionFactoryImpl</ connectionfactory-impl-class>

<connectioninterface>samples.mailra.api.JavaMailConnection</connectioninterface>

<credentialinterface>javax.resource.spi.security.PasswordCredential</ credential-interface>

<connection-impl- class>samples.mailra.ra.outbound.JavaMailConnectionImpl</ connection-impl-class>

</connectiondefinition>

188

Эквивалентная аннотация метаданных выглядит следующим образом:

@ConnectionDefinition( connectionFactory =

samples.mailra..api.JavaMailConnectionFactory.class, connectionFactoryImpl =

samples.mailra.ra.outbound.JavaMailConnectionFactoryImpl.class, connection =

samples.connectors.mailconnector.api.JavaMailConnection.class, connectionImpl =

samples.mailra..ra.outbound.JavaMailConnectionImpl.class

)

public class ManagedConnectionFactoryImpl implements ManagedConnectionFactory, Serializable

{

...

...

@ConfigProperty(

defaultValue = "UnknownHostName"

)

public void setServerName(String serverName)

{

...

}

}

Пример 3

Аннотация @Activation

Следующий фрагмент дескриптора развертывания описывает возможности обмена сообщениями адаптера ресурса:

<messageadapter>

<messagelistener> <messagelistener-type>samples.mailra.api.JavaMailMessageListener</ messagelistener-type>

<activationspec>

<activationspecclass>samples.mailra.ra.inbound.ActivationSpecImpl</activationspec -class>

required-config-property> <config-property-name>serverName</config-property-name>

</required-config-property> <required-config-property>

<config-property-name>userName</config-property-value> </required-config-property>

<required-config-property> <config-property-name>password</config-property-value>

</required-config-property> <required-config-property>

<config-property-name>folderName</config-property-value>

189

</required-config-property> <required-config-property>

<description>Normally imap or pop3</description> <config-property-name>protocol</config-property-name> <config-property-value>IMAP</config-property-value> </required-config-property>

</activationspec>

</messagelistener>

</messageadapter>

Эквивалентная аннотация метаданных выглядит следующим образом:

@Activation( messageListeners =

{samples.mailra.api.JavaMailMessageListener.class}

)

public class ActivationSpecImpl implements javax.resource.spi.ActivationSpec,

java.io.Serializable

{

...

@ConfigProperty()

// serverName property value

private String serverName = new String(""); @ConfigProperty()

// userName property value

private String userName = new String(""); @ConfigProperty()

// password property value

private String password = new String(""); @ConfigProperty()

// folderName property value

private String folderName = new String("Inbox");

//protocol property value

//Normally imap or pop3 @ConfigProperty(

description = "Normally imap or pop3"

)

private String protocol = new String("imap");

...

...

}

190

15.6. Интерфейс CommonClient

Здесь описывается, как использовать API Connector Architecture Common Client Interface (CCI) и адаптер ресурса, чтобы иметь доступ к данным из EIS.

Спецификация архитектуры соединений Java EE CCI определяет набор интерфейсов и классов, чьи методы позволяют клиенту выполнять типичные операции доступа к данным. Интерфейсы и классы CCI следующие:

•ConnectionFactory обеспечивает прикладной компонент экземпляром связи с EIS;

•Connection представляет связь с основным EIS;

•ConnectionSpec обеспечивает средства прикладного компонента для передачи задаваемых свойств связи в ConnectionFactory при получении запроса на соединение;

•Interaction обеспечивает средства для прикладного компонента, чтобы выполнять функции EIS, как например, хранимые процедуры базы данных;

•InteractionSpec обеспечивает хранение свойств, относящихся к взаимодействию прикладного компонента с EIS;

•Record — суперкласс для различных подклассов Record: MappedRecord,

IndexedRecord или ResultSet, которые наследуются от интерфейса Record;

•RecordFactory обеспечивает прикладной компонент экземпляром Record;

•IndexedRecord представляет упорядоченную совокупность экземпляров

Record с интерфейсом java.util.List.

Клиент или прикладной компонент используют интерфейс CCI для взаимодействия с основным EIS заданным способом. Компонент должен установить связь с менеджером ресурса EIS, используя ConnectionFactory. Объект Connection представляет фактическую связь с EIS и используется для последующего взаимодействия с EIS.

Компонент выполняет свое взаимодействие с EIS, например, доступ к данным из заданной таблицы, используя объект взаимодействия. Прикладной компонент определяет объект Interaction, используя объект InteractionSpec. Когда прикладной компонент читает данные из EIS (например, из таблиц базы данных) или записывает данные в таблицы, он использует конкретный тип экземпляра Record: MappedRecord, IndexedRecord или ResultSet. Подобно тому как ConnectionFactory создаёт экземпляр

Connection, RecordFactory создаёт экземпляры Record.

Примечание. Приложение-клиент, использующее адаптер ресурса CCI, аналогично любому другому клиенту Java EE, который использует методы бинов.

191