Руководство системного программиста » История » Редакция 52
Редакция 51 (Rustam Usmanov, 10.05.2016 12:26) → Редакция 52/58 (Rustam Usmanov, 10.05.2016 12:39)
h1. Руководство системного програмиста
{{toc}}
h2. Аннотация
В данном документе приведены общие сведения о программе "Web-сервисы Руслан", ее структура. Описаны порядок настройки и проверки программы, дополнительные возможности.
h2. Глава 1. Общие сведения о программе
Программа "Web-сервисы Руслан" предназначена для обеспечения простого и удобного доступа удалённых пользователей к ресурсам АБИС "Руслан". Удалёнными пользователями могут являться любые пользователи сервера приложений "WildFly":http://wildfly.org, на базе которого функционирует программа. Ресурсами АБИС "Руслан" являются БД, поддерживаемые сервером "Руслан" и записи, содержащиеся в этих базах данных. Доступ к ресурсам заключается в выполнении над ними следующих операций:
* Поиск (по протоколу "SRU 2.0":http://www.loc.gov/standards/sru/sru-2-0.html)
* Извлечение, модификация, создание, удаление (по протоколу "WebDAV":http://tools.ietf.org/html/rfc4918)
* Заказ услуги (бронирование, копия) по найденному библиографическому описанию (по протоколу "NCIP v. 2.0.2":http://www.ncip.info/)
Операции, связанные с чтением данных с ограниченным доступом и записью данных, требуют наличия соответствующих прав у пользователя, а следовательно и идентификации пользователя. Идентификация пользователя осуществляется при помощи провайдера идентификации по протоколу SAML 2.0.
Взаимодействие с сервером "Руслан" осуществляется по протоколу Z39.50.
Ресурсы представляются в двух форматах: XML и JSON, в зависимости от предпочтений пользователя.
Программа может функционировать на любых технических средствах под управлением сервера приложений *WildFly 8.2.**. После установки сервера WildFly необходимо убедиться в том, что установленный "статический модуль":https://docs.jboss.org/author/display/WFLY8/Glossary+--+Module "*PicketLink*":http://picketlink.org имеет версию не ниже *2.7.0.Final*. При необходимости следует "обновить этот модуль":http://picketlink.org/gettingstarted/.
Обязательным требованием для выполнения программы является возможность сетевого взаимодействия с сервером "Руслан" и с сервером *Oracle*, используемым АБИС "Руслан".
h2. Глава 2. Структура программы
Программа "Web-сервисы Руслан" состоит из следующих компонентов:
# @jrzs-ear*.ear@ - Z39.50-клиент, реализованный в виде EJB.
# @ridp*.war@ - провайдер идентификации.
# @rrs-web*.war@ - Web-интерфейс ресурсов АБИС "Руслан"
h2. Глава 3. Настройка программы
h3. 3.1. Установка программы
Установка программы заключается в "развёртывании компонентов программы на сервере приложений WildFly":https://docs.jboss.org/author/display/WFLY8/Application+deployment.
h3. 3.2. Настройка программы
h4. 3.2.1. Настройка сервера приложений WildFly
h5. 3.2.1.1. Настройка источников данных
Все источники данных Oracle, используемые сервером Руслан, должны быть "включены в конфигурацию сервера приложений WildFly":https://docs.jboss.org/author/display/WFLY8/DataSource+configuration. Следует обратить внимание на то, что настройка источников данных предусматривает "установку":https://docs.jboss.org/author/display/WFLY8/Application+deployment "JDBC драйвера Oracle":http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html. Пример результата настройки источников данных, отражённого в конфигурационном файле сервера приложений WildFly, приведён в [[Руководство системного програмиста#Источники данных|Приложении 1]].
h5. 3.2.1.2 Настройка доменов безопасности
В "подсистему безопасности сервера приложений WildFly":https://docs.jboss.org/author/display/WFLY8/Security+subsystem+configuration необходимо "добавить два домена безопасности":https://docs.jboss.org/author/display/WFLY8/Security+subsystem+configuration#Securitysubsystemconfiguration-securitydomains с именами @idp@ и @sp@. Первый используется провайдером идентификации, второй - Web-интерфейсом ресурсов АБИС "Руслан".
Аутентификацию в домене безопасности @idp@ необходимо настроить с использованием модуля входа Z39.50 (класс @com.ols.auth.Z3950LoginModule@). Этот модуль позволяет осуществлять аутентификацию любых пользователей АБИС "Руслан". В Таблице 3-1 представлены параметры модуля входа Z39.50, их назначение и примеры значений.
Таблица 3-1. Параметры модуля входя Z39.50
|_.Параметр|_.Назначение|_.Значение|
|orgId|Уникальный идентификатор организации. Рекомендуется использовать национальный код библиотеки. Значение этого параметра должно совпадать со значением параметра @Org899@ сервера "Руслан"|@19013582@|
|zHost|Адрес сервера Z39.50. Значение этого параметра должно совпадать со значением параметра @Host@ сервера "Руслан".|@testbed.ruslan.ru@|
|zPort|Порт сервера Z39.50. Значение этого параметра должно совпадать со значением параметра @Port@ сервера "Руслан".|@210@|
|zClientBinding|JNDI-имя Z39.50-клиента, реализованного в виде EJB.|@java:global/jrzs/jrzs-ejb/ZClient@|
|debug|Управление выводом отладочных сообщений в журнал.|@true@
@false@|
Аутентификацию в домене безопасности @sp@ необходимо настроить с использованием модуля входа SAML2 (класс @org.picketlink.identity.federation.bindings.wildfly.SAML2LoginModule@).
Пример результата настройки доменов безопасности, отражённого в конфигурационном файле сервера приложений WildFly, приведён в [[Руководство системного програмиста#Домены безопасности|Приложении 1]].
h4. 3.2.2. Настройка провайдера идентификации
Настройка провайдера идентификации заключается в редактировании "конфигурационного файла WEB-INF/picketlink.xml":https://docs.jboss.org/author/display/PLINK/Identity+Provider+Configuration#IdentityProviderConfiguration-Thepicketlink.xmlconfigurationfile, включённого в @ridp*.war@. Как минимум, необходимо указать значения параметров @PicketLinkIDP/IdentityURL@ и @PicketLinkIDP/Trust/Domains@, зависящие от конкретных условий эксплуатации. В первом из них необходимо указать адрес провайдера идентификации (например, @https://host.domain/ridp/@). Во втором - список доменов, разделённых запятой, с которыми установлены доверительные отношения (например, @domain1,domain2@).
h4. 3.2.3. Настройка Web-интерфейса ресурсов АБИС "Руслан"
h5. 3.2.3.1 Настройка провайдера услуг
Web-интерфейс ресурсов АБИС "Руслан" является реализацией провайдера услуг. Для успешного взаимодействия с провайдером идентификации требуется его настройка, которая заключается в редактировании "конфигурационного файла WEB-INF/picketlink.xml":https://docs.jboss.org/author/display/PLINK/Service+Provider+Configuration#ServiceProviderConfiguration-Thepicketlink.xmlconfigurationfile, включённого в @rrs-web*.war@. Как минимум, необходимо указать значения параметров @PicketLinkSP/IdentityURL@ и @PicketLinkSP/ServiceURL@, зависящие от конкретных условий эксплуатации. В первом из них необходимо указать адрес провайдера идентификации (например, @https://host.domain/ridp/@). Во втором - адрес провайдера услуг (например, @https://host.domain/rrs-web/@).
h5. 3.2.3.2 Настройка хранения данных
Настройка хранения данных заключается в редактировании "дескриптора хранения данных WEB-INF/classes/META-INF/persistence.xml":http://java.sun.com/xml/ns/persistence, включённого в @rrs-web*.war@. В этом дескрипторе необходимо определить модули хранения данных (persistence-unit), связав их с [[Руководство системного програмиста#3.2.1.1. Настройка источников данных|ранее определёнными источниками данных]]. Пример дескриптора хранения данных приведён в [[Руководство системного програмиста#Дескриптор хранения данных|Приложении 1]].
h5. 3.2.3.3 Общая настройка
Общая настройка заключается в редактировании "дескриптора развёртывания приложения WEB-INF/web.xml":http://xmlns.jcp.org/xml/ns/javaee, включённого в @rrs-web*.war@. В этом дескрипторе необходимо определить контексты хранения данных (persistence-context-ref), связав их с ранее определёнными модулями хранения данных (persistence-unit). Контексты хранения данных должны быть поименованы (элемент @persistence-context-ref-name@) определённым образом:
* Контекст, связанный через соответствующий модуль хранения данных с управляющим источником данных АБИС "Руслан", должен иметь имя @persistence/<orgId>.Server@
* Контекст, связанный через соответствующий модуль хранения данных с источником библиотечных данных АБИС "Руслан", должен иметь имя @persistence/<orgId>.DbMetadata@.
@orgId@ - национальный код библиотеки.
Пример определения контекстов хранения данных приведён в [[Руководство системного програмиста#Контексты хранения данных в дексрипторе развёртывания|Приложении 1]].
h5. 3.2.3.4 Настройка АБИС "Руслан"
Настройка АБИС "Руслан" заключается в присвоении значений параметрам сервера "Руслан":
* Host - имя узла с экземпляром АБИС "Руслан", по которому Web-интерфейс ресурсов АБИС "Руслан" сможет связываться с сервером Руслан.
* Org899 - национальный код библиотеки, используемый в определениях контекстов хранения данных.
Пример определения контекстов хранения данных приведён в [[Руководство системного програмиста#Контексты хранения данных в дексрипторе развёртывания|Приложении 1]].
h2. Перечень сокращений
table{border:none}.
|EJB|Enterprise JavaBeans|
|JNDI|Java Naming and Directory Interface|
|JSON|JavaScript Object Notation|
|NISO|National Information Standards Organization|
|NCIP|NISO Circulation Interchange Protocol|
|XML|The Extensible Markup Language|
|АБИС|Автоматизированная библиотечно-информационная система|
|БД|База данных|
h2. Приложение 1. Конфигурационный файл сервера приложений WildFly
h3. Источники данных
<pre><code class="xml">
<subsystem xmlns="urn:jboss:domain:datasources:2.0">
<datasources>
<datasource jta="false" jndi-name="java:jboss/datasources/ruslan" pool-name="ruslan" enabled="true" use-ccm="false">
<connection-url>jdbc:oracle:thin:@oracle.test.org:1521/ORA11</connection-url>
<driver-class>oracle.jdbc.OracleDriver</driver-class>
<driver>ojdbc6.jar</driver>
<security>
<user-name>libmgr</user-name>
<password>libmgr_pwd</password>
</security>
<validation>
<validate-on-match>false</validate-on-match>
<background-validation>false</background-validation>
</validation>
<statement>
<share-prepared-statements>false</share-prepared-statements>
</statement>
</datasource>
<datasource jta="false" jndi-name="java:jboss/datasources/lib1" pool-name="lib1" enabled="true" use-ccm="false">
<connection-url>jdbc:oracle:thin:@oracle.test.org:1521/ORA11</connection-url>
<driver-class>oracle.jdbc.OracleDriver</driver-class>
<new-connection-sql>alter session set current_schema=lib1</new-connection-sql>
<driver>ojdbc6.jar</driver>
<security>
<user-name>lib1</user-name>
<password>lib1_pwd</password>
</security>
<validation>
<validate-on-match>false</validate-on-match>
<background-validation>false</background-validation>
</validation>
<statement>
<share-prepared-statements>false</share-prepared-statements>
</statement>
</datasource>
</datasources>
</subsystem>
</code></pre>
h3. Домены безопасности
<pre><code class="xml">
<subsystem xmlns="urn:jboss:domain:security:1.2">
<security-domains>
<security-domain name="idp" cache-type="default">
<authentication>
<login-module code="com.ols.auth.Z3950LoginModule" flag="required">
<module-option name="orgId" value="1"/>
<module-option name="zHost" value="testbed.ruslan.ru"/>
<module-option name="zPort" value="210"/>
<module-option name="zClientBinding" value="java:global/jrzs/jrzs-ejb/ZClient"/>
<module-option name="debug" value="false"/>
</login-module>
</authentication>
</security-domain>
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.wildfly.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
</security-domains>
</subsystem>
</code></pre>
h3. Дескриптор хранения данных
<pre><code class="xml">
<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
<persistence-unit name="ruslan-database">
<jta-data-source>java:jboss/datasources/lib1</jta-data-source>
<class>com.ols.ruslan.persistence.database.Zdbi</class>
</persistence-unit>
<persistence-unit name="ruslan-server">
<jta-data-source>java:jboss/datasources/ruslan</jta-data-source>
<class>com.ols.ruslan.persistence.server.Apoint</class>
<class>com.ols.ruslan.persistence.server.Lusr</class>
<class>com.ols.ruslan.persistence.server.Zacl</class>
<class>com.ols.ruslan.persistence.server.Zparam</class>
</persistence-unit>
</persistence></code></pre>
h3. Контексты хранения данных в дексрипторе развёртывания
<pre><code class="xml">
<persistence-context-ref>
<persistence-context-ref-name>persistence/1.Server</persistence-context-ref-name>
<persistence-unit-name>ruslan-server</persistence-unit-name>
</persistence-context-ref>
<persistence-context-ref>
<persistence-context-ref-name>persistence/1.DbMetadata</persistence-context-ref-name>
<persistence-unit-name>ruslan-database</persistence-unit-name>
</persistence-context-ref>
</code></pre>