Руслан-Нео » Web-сервисы Руслан

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://downloads.jboss.org/picketlink/2/2.7.0.Final/picketlink-installer-2.7.0.Final.zip. При необходимости следует "обновить этот модуль":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, их назначение и примеры значений. При необходимости осуществления аутентификации на нескольких серверах Руслан, в конфигурацию домена безопасности можно включить несколько экземпляров модуля входа 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@) следующим образом (с указанием национального кода библиотеки вместо @orgId@):

* Контекст, связанный через соответствующий модуль хранения данных с управляющим источником данных АБИС "Руслан", должен иметь имя @persistence/orgId.Server@;

* Контекст, связанный через соответствующий модуль хранения данных с источником библиотечных данных АБИС "Руслан", должен иметь имя @persistence/orgId.DbMetadata@.

Пример определения контекстов хранения данных приведён в [[Руководство системного програмиста#Контексты хранения данных в дескрипторе развёртывания|Приложении 1]].

h5. 3.2.3.4 Настройка АБИС "Руслан"

Настройка АБИС "Руслан" заключается в присвоении значений параметрам сервера "Руслан":

* Host - имя узла с экземпляром АБИС "Руслан", по которому Web-интерфейс ресурсов АБИС "Руслан" сможет  связываться с сервером Руслан;

* Org899 - национальный код библиотеки, используемый в определениях контекстов хранения данных.

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>