Работа с REF CURSOR в OA Framework

Допустим, есть функция, возвращающая REF CURSOR

CREATE OR REPLACE PACKAGE XX_TST AS
TYPE crResultSet is REF CURSOR;

function getCursor () return crResultSet;
END XX_TST;

CREATE OR REPLACE PACKAGE BODY XX_TST AS
  function getCursor () return crResultSet IS
  retCursor crResultSet;
  begin
    open retCursor for
    SELECT dummy from dual;
    return retCursor;
  
  end getCursor;

END XX_TST;

Для того, чтобы получить записи из курсора, нужно использовать метод getObject в классе OracleCallableStatement

В Application Module добавляем в раздел import и в нужный метод следующий код
imports:

  import oracle.jdbc.OracleCallableStatement;
  import oracle.jdbc.OracleResultSet;
  import java.sql.Connection;
  import java.sql.SQLException;


В метод:

    try {
    Connection conn = getOADBTransaction().getJdbcConnection();
    OracleCallableStatement mainSt = (OracleCallableStatement)conn.prepareCall("begin :1 := XX_TST.getCursor(); end;");
    mainSt.registerOutParameter(1, oracle.jdbc.driver.OracleTypes.CURSOR);
    mainSt.executeQuery();

    // Получаем результирующий набор из ref курсора
    OracleResultSet mainRs = (OracleResultSet)mainSt.getObject(1);

    // Получаем записи из курсора
    while (mainRs.next())
    {
       ...
    }
    
    } catch (java.sql.SQLException sql_e)
    {
      
    }

Работа с объектами БД из OA Framework

Доработаем пример, представленный в предыдущем посте, добавим поле, кнопку и по нажатию на кнопку будем передавать значение поля в функцию в пакете БД и возвращать результат.

Нажатием правой кнопкой мыши на регионе верхнего уровня (pageLayoutRN) создадим регион типа messageComponentLayout, и в нем создадим элемент типа messageTextInput. Таким же образом на уровне pageLayoutRN создадим кнопку типа submitButton. Указываем свойства Prompt у поля и у кнопки. Это текст, который будет выводиться перед полем и на кнопке.

Создадим контроллер для обработки событий на форме. Щелкаем правой кнопкой мыши на регионе верхнего уровня pageLayoutRN и выбираем пункт “Set New Controller”. Так как контроллеры должны располагаться в каталоге webui, указываем имя пакета xx.oracle.apps.per.xx_xxx_demo.webui. Так же указываем имя нового класса, имена классов должны заканчиваться на CO.

JDeveloper создает шаблон контроллера с 2мя методами, 3 метод processFormData по умолчанию не создается в шаблоне.

Подготовим функцию с 2мя параметрами, один параметр IN и один - OUT

create or replace package xx_xxx_demo_p is 
  function xx_tst (p_value in varchar2, p_error_txt out varchar2) return number; 
end xx_xxx_demo_p; 
/ 

create or replace package body xx_xxx_demo_p is 

function xx_tst (p_value in varchar2, p_error_txt out varchar2) return number is 
begin 
    if p_value = 'ERROR' THEN 
      p_error_txt := 'Ошибка в функции'; 
      return -1; 
    else 
      p_error_txt := 'Завершено без ошибок'; 
      return 0; 
    end if; 
  end; 

end xx_xxx_demo_p;
/

В контроллер в раздел import добавляем
import oracle.apps.fnd.framework.OAApplicationModule; import java.io.Serializable; import oracle.apps.fnd.framework.OAException;

В контроллере в методе processFormRequest после super.processFormRequest(pageContext, webBean); пишем:

if ( pageContext.getParameter("submitBTN") != null) {
  OAApplicationModule am = pageContext.getApplicationModule(webBean);
  Serializable params[] = { pageContext.getParameter("field1") };

  am.invokeMethod("callFunction", params);
  // Если нет ошибок, выводим сообщение

  pageContext.putDialogMessage(new OAException("Ошибок нет", OAException.INFORMATION));

 }

Если нажата кнопка с ID “submitBTN”, то в переменную am получаем Application Module, присоединенный к региону, на который ссылается webBean. Затем формируем массив параметров и передаем их в вызов метода callFunction. Это сделано для того, чтобы вынести логику работы с БД из уровня CONTROLLER в уровень MODEL. Теперь необходимо реализовать метод callFunction для вызова созданной ранее функции.

Выбираем AM и открываем xxXXXDemoAMImpl.java класс.

Добавляем в раздел import: import oracle.jdbc.OracleCallableStatement; import java.sql.Connection; import java.sql.SQLException; import oracle.jdbc.OracleTypes; import oracle.apps.fnd.framework.OAException;

Указываем, что метод callFunction может генерировать исключения типа SQLException. Дописываем справа от метода “throws SQLException”.Добавляем в метод callFunction код вызова функции в БД. Теперь объявление метода выглядит так:

public void callFunction(String val) throws SQLException

{
Connection conn = getOADBTransaction().getJdbcConnection();
String l_sql = "BEGIN :1 := xx_xxx_demo_p.xx_tst(:2, :3); end; ";
OracleCallableStatement ocs = (OracleCallableStatement)conn.prepareCall(l_sql);
ocs.registerOutParameter(1, OracleTypes.NUMBER);
ocs.setString(2, val);
ocs.registerOutParameter(3, OracleTypes.VARCHAR);
ocs.executeUpdate();

int res = ocs.getInt(1);

String err = ocs.getString(3);

if (res == -1)
  throw new OAException(err, OAException.ERROR);

}

Снова запускаем страницу и вводим какой нибудь текст в поле. Результат ни иллюстрации ниже.

Если текст появляется на странице в нечитаемом виде (неправильная кодировка), то идем в настройки проекта и в разделе Compiler выставляем кодировку windows-1251, или Cp1251, изначально, скорее всего, стоит Cp1252 кодировка. 

Пересобираем проект и снова запускаем страницу. Теперь вводим в поле значение ERROR, результат на иллюстрации ниже.

Создание простейшей OAF страницы

Создадим простую OAF страницу. Щелкаем правой клавишей на проекте и выбираем пункт “New”

Выбираем раздел Web Tier -> OA Components, указываем элемент “Page” и указываем название страницы. Имена страниц желательно называть <Имя>PG. В поле Package указываем пакет, который мы указывали при создании данного проекта.

Теперь надо ограничить проект, чтобы не отображались файлы, принадлежащие другим проектам. Открываем свойства проекта и в Project Content указываем в Java Content путь к myprojects каталогу и ниже, в разделе Included указываем путь к каталогу, находящемся перед webui и server.

Затем удаляем все из раздела Resources

Минимальный набор OAF компонентов для запуска страницы – page и Application Module, так что

теперь нам нужно создать Application Module(далее AM). Щелкаем правой клавишей мыши на имени проекта и выбираем “New”, затем выбираем пункт Application Module в разделе Business Tier -> ADF Business Tier.

Поскольку объекты слоя Model должны быть расположены в каталогах server, при создании AM, указываем Package: xx.oracle.apps.per.xx_xxx_demo.server. Указываем имя нового AM ( желательно, чтобы имена Application Module'ей заканчивались на AM )

Поскольку View Object'ов у нас пока нет, то 2й шаг пропускаем.

На 3м шаге указываем AM, который мы хотим использовать как вложенный в наш новый AM. Поскольку таких AM у нас пока нет, то 3й шаг тоже пропускаем.

На 4м шаге указываем Generate Java file(s) для Application Module Class: xxXXXDemoAMImpl. Это означает, что мы сможем реализовывать какие либо методы на уровне AM, например, обращаться в БД, фиксировать транзакции и.т.д. Вторую опцию можно не указывать.

Выбираем созданную ранее страницу и в ней выбираем регион region1, являющийся компонентом самого верхнего уровня и имеющий тип - pageLayout, переименовываем его в pageLayoutRN, например, и указываем в property inspector свойство AM Definition, равное созданному ранее AM, например xx.oracle.apps.per.xx_XXX_demo.server.xxXXXDemoAM.

На этом же регионе указываем свойства Window Title ( название окна в браузере ) и Title (Заголовок страницы )

Пробуем запустить страницу ( щелчок правой кнопкой на странице -> Run).

Если все было указано правильно, увидим следующее

Основные принципы создания веб-формы. Создание проекта

После запуска Jdeveloper щелкаем правой кнопкой мыши на “Applications” и выбираем
New OA Workspace. Таким образом, мы создаем рабочую область, в которой будут содержаться OA Framework проекты. По умолчанию автоматически создается OAF Project

Шаг 1. Указываем имя проекта и пакет по умолчанию, в котором будут создаваться новые объекты. По соглашению, принятому при разработке приложений на OA Framework, стандартные приложения располагаются относительно $JAVA_TOP в каталогах oracle.apps. При разработке своих кастомных приложений, их необходимо помещать в <3rd party identifier>.oracle.apps. Например: mycompany.oracle.apps. или xx.oracle.apps. После apps через “.” указывается код приложения, для которого предназначена данная разработка. Например: .per. – Модуль Human Resources в OEBS.

Затем идет произвольное имя приложения и наконец указываем “webui”. В примере, на иллюстрации выше пакет xx.oracle.apps.per.xx_xxxx_demo.webui означает следующее: xx – нестандартное приложение, расширение. oracle.apps – остается всегда неизменным. per – разработка делается для модуля Human Resources. xx_xxxx_demo – имя разработки. И webui – остается неизменным.

Шаг 2. Указываем, использовать ли соединение с БД при проектировании приложения. Требуется для создания Entity Object, View Object и т.д., когда необходимо указывать таблицы, проверять SQL запросы на корректность синтаксиса, смотреть планы разбора и .т.д.

Если объект соединения не создан и нам требуется его использовать, нажимаем кнопку “New” и создаем объект.

Шаг 3. На данном шаге мы должны указать DBC File, который мы получили выше, логин и пароль для входа в OEBS, и полномочия, под которыми мы будет запускать наше приложение. Для того, чтобы определить код приложения и ключ полномочий, под которыми мы в данный момент работаем, нужно внизу страницы нажать “О данной странице” и перейти на вкладку “Контекст страницы”. В полях Приложение и Полномочия будут указаны необходимые нам данные. В примере на иллюстрации ниже: ID приложения – 242. Application Short Name – AMW. Название приложения – Внутренний контроль.
ID полномочий – 50207. RESPONSIBILITY_KEY – AMW_SSW_NEW_RESP. Имя полномочий – Oracle Internal Controls Manager – суперпользователь (Веб).

На иллюстрации ниже ApplicationShort Name – PER – Это короткое имя модуля Human Resources в OEBS и GLB_SHRMS_MANAGER – Ключ полномочий “Глобальный суперпользователь – руководитель СУПЕР”. Для получения списка полномочий и ключей используем следующий запрос: select v.RESPONSIBILITY_NAME, v.RESPONSIBILITY_KEY from fnd_responsibility_vl v. Для того, чтобы получить имена полномочий на русском языке, перед запросом выполняем команду alter session set nls_language=RUSSIAN.

Проект создан. В следующей статье создадим простейшую OAF страницу

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

Для разработки OAF приложений в OEBS R12 используется специальная сборка Oracle JDeveloper 10g под названием Oracle JDeveloper 10G OA Extension. Сборки зависят от версии патча OEBS, поэтому для начала необходимо определить версию OA Framework окружения, для которого будет осуществляться разработка.

Заходим в ОЕБС и на главном меню внизу страницы слева нажимаем ссылку “О Данной Странице”. Если ссылки нет, то необходимо назначить Вашему пользователю профиль “БОП:Диагностика” (FND:Diagnostics), устанавливаем значение “Y” на уровне пользователя.

После перехода на экран “О Данной Странице” выбираем вкладку “Компоненты технологии”. Нас интересует поле “Структура OA”

Переходим по ссылке https://support.oracle.com/CSP/main/article?cmd=show&type=NOT&doctype=HOWTO&id=416708.1 и находим нужную нам сборку JDeveloper.

Скачиваем архив по ссылке и распаковываем его в папку на диске. Желательно без пробелов в именах путей ( Например: C:/JDev10GR12 ).

Устанавливаем переменную окружения JDEV_USER_HOME. В данном каталоге будут создаваться проекты JDeveloper.

Теперь, для того, чтобы JDeveloper смог устанавливать связь с OEBS и запускать приложения, нам необходимо взять с сервера FND DBC файл. Есть несколько способов. Если есть доступ к файловой системе сервера приложений, то файл можно скопировать непосредственно из файловой системы. Файл лежит в каталоге $FND_SECURE. Файлов может быть несколько. Чтобы определить, какой именно файл нам нужен, заходим в OEBS и в окне “О данной странице” выбираем вкладку “Системные свойства Java”. Там ищем параметр DBCFILE, который указывает на каталог и файл, который нам нужен и забираем этот файл. На DBC файл так же указывает поле “База данных” во вкладке “Контекст страницы”.

Если нет доступа к файловой системе, этот файл можно получить следующим образом. Заходим на домашнюю страницу OEBS, например путь в строке браузера выглядит так: http://host:port/OA_HTML/OA.jsp?OAFunc=OAHOMEPAGE, меняем OA.jsp?OAFunc=OAHOMEPAGE на jsp/fnd/aoljtest.jsp и переходим по новой ссылке. Ссылка теперь имеет вид http://host:port/OA_HTML/jsp/fnd/aoljtest.jsp Вводим параметры подключения к БД данного окружения (например, берем параметры из TNS_NAMES.ora) и нажимаем кнопку test.

После успешного подключения внизу страницы переходим по ссылке “Enter AOL/J Setup Test”

После перехода, видим 2 окна, слева выбираем ссылку “Locate DBC File” и затем в правом окне отображается содержимое DBC файла. Создаем файл и копируем в него текст между строками “DBC file found, content:” и “Next (Verify settings in DBC file)”. Копируем полученный файл в каталог: куда_распаковали_архив\jdevhome\jdev\dbc_files\secure.

Создаем ярлык на рабочем столе для быстрого запуска JDeveloper. Путь к исполняемому файлу куда_распаковали_архив\jdevbin\jdev\bin\jdevw.exe

Запускаем JDeveloper и в меню Tools -> Embedded OC4J Server Preferences -> Global -> Startup устанавливаем “Default Local IP Address”

В следующий раз рассмотрим создание простой формы, работу с БД и перенос простой формы на рабочее окружение

Что происходит при запросе OAF страницы

Когда браузер обращается к OAF странице, http слушатель(listener) получает запрос и перенаправляет его серверу приложений для обработки(в oebs r12 используется OC4J), OA.jsp servlet, являющийся центральным контроллером начинает обработку запроса. OA.jsp, по имени страницы, читает метаданные страницы из MDS репозитория, для того, чтобы создать иерархию элементов страницы (web beans). Для каждого элемента, с которым связан контроллер, OA Framework вызывает метод processRequest() для инициализации свойств элементов страницы. Когда обработка завершена, OA Framework передает web bean иерархию в UIX framework, который генерирует HTML и отправляет его браузеру. Когда браузер инициирует отправку данных посредством вэб формы (например, пользователь нажимает кнопку), OA Framework при необходимости пересоздает иерархию (иерархия кэшируется между запросами к страницам, и необходимость ее пересоздания возникает только в исключительных ситуациях), и затем вызываются методы processFormRequest() для обработки событий. Когда выполнение кода обработчиков завершено, HTML страницы снова создается и отправляется пользователю

Обзор основных компонентов Oracle Application Framework

Уровень MODEL
BC4J : Business Components for Java

BC4J это набор java библиотек и xml файлов, описывающих объекты, которые отражают объекты базы данных, такие как view, tables и связи между ними, например View Objects (VOs), Entity Objects (EOs), View Links, Entity Associations. Так же в BC4J входит такой объект как Application Module (AM).
Все BC4J компоненты на сервере приложений располагаются в каталогах относительно пути, на который указывает переменная окружения $JAVA_TOP, например:

Такие объекты как Application Module, View Object, View Link для приложения project, который принадлежит модулю pa должны располагаться в каталоге $JAVA_TOP/oracle/apps/pa/project/server/
Controller должен находится в каталоге $JAVA_TOP/oracle/apps/pa/project/webui/
Entity Object должен находиться в каталоге $JAVA_TOP/oracle/apps/pa/project/schema/server/

View Object
Данный объект хранит результат выполнения SQL запроса. Предоставляет механизмы для работы с данными и строками. Не предназначен для внесения изменений в таблицы БД, служит только для отображения данных. View Object может быть основан на SQL запросе, на Entity Object, а так же может содержать произвольные столбцы и заполняться программно произвольными данными (например, получаем список файлов в директории и заполняем VO именами файлов, чтобы затем отобразить набор данных пользователю).

Entity Object
Объект представляет собой связь с таблицей БД или использует процедуры PL/SQL для изменения данных (PL/SQL based entity). Если нам необходимо не только отображать данные, но и изменять их, мы должны использовать Entity Object. Каждое поле таблицы ставится в соответствие "Entity Attribute".

Application Module
Данный объект является контейнером для BC4J объектов, а так же AM предоставляет доступ к соединению БД для выполнения команд БД, таких как INSERT, UPDATE, выполнения хранимых объектов БД и т.д., предоставляет доступ к OEBS окружению, а так же позволяет фиксировать или откатывать транзакции.


Уровень VIEW

Страница (Page)
Страница находится на уровне VIEW в шаблоне проектирования MVC, представляет собой xml документ и является набором регионов (header(заголовок), table(таблица) и т.д. ) и каждый регион может содержать как элементы интерфейса, такие как field(поля ввода), button(кнопки), checkbox(триггеры вкл/выкл) так и другие регионы.

Регион (Region)
Регион так же как и страница находится на уровне VIEW в шаблоне проектирования MVC и представляет собой xml документ, который содержит как элементы пользовательского интерфейса, так и другие регионы. Отличие региона от страницы в том, что один регион можно использовать во множестве страниц. Для того, чтобы использовать регион, находящийся в репозитории, на своей странице необходимо создать элемент необходимого типа, например table (region2 на иллюстрации ниже), затем в Property Inspector для region2 выбрать свойство Extends и нажать … Открывается окно, в котором выбираем нужный нам регион, находящийся в репозитории MDS.

Обратите внимание, что свойства импортированного региона изменять нельзя

View реализуется с помощью технологии UI XML (UIX). UIX использует XML для описания компонентов и их иерархии для страницы. UIX Framework преобразовывает web bean иерархию в HTML, который затем отображается в браузере. Метаданные, используемые для описания пользовательского интерфейса хранятся в репозитории, который называется Meta-Data-Service(MDS) в БД. В репозиторий загружаются страницы, регионы и персонализации страниц. Репозиторий и работа с ним более детально будут рассмотрены позднее, при описании переноса приложения на рабочее окружение.

Уровень CONTROLLER

Controller
Обычный java класс, являющийся подклассом oracle.apps.fnd.framework.webui.OAControllerImpl. Присоединяется к регионам на страницах и служит для обработки событий, происходящих на страницах, таких как нажатие на кнопку или вызов списка значений. Имеет всего 3 метода:
1. ProcessRequest – Срабатывает при загрузке страницы, перед отображением страницы пользователю.
2. ProcessFormData – Обычно не используется. Служит для передачи параметров формы при POST запросе в соответствующие BC4J.
3. ProcessFormRequest – Обработка событий. Наиболее часто используемый метод.

Данный блог создавался для накопления информации и обмена опытом по Oracle Applications Framework. В примерах используется Jdeveloper 10G и окружение OEBS R12.