IBM Workplace Forms Server API предлагает мощные инструменты для расширения возможностей Workplace Forms. С помощью Function Call Interface (FCI) можно легко добавить пользовательские функции к вашим приложениям Workplace Forms.

FCI является частью Workplace Forms Server API. Она предоставляет среду как для Java, так и для C, позволяющую расширять функциональность ваших форм, создавая пользовательские компоненты, которые называются расширениями. Эти расширения содержат пакеты функций, которые можно вызывать из форм Extensible Forms Description Language (XFDL). С помощью этих пользовательских функций можно не только возвратить вычисленное значение, но и напрямую управлять формой. После настройки среды на работу с вашими пользовательскими функциями можно с помощью системных методов Java, методов Form Library или даже других методов FCI в деталях реализовывать поведение каждой функции.

Подробную информацию по FCI см. в Руководстве пользователя по Workplace Forms Java API, которое можно загрузить на странице документации по Workplace Forms на developerWorks. Данная статья относится к Workplace Forms V2.5 и более поздним версиям.

Данная статья предназначена разработчикам Workplace Forms, знакомым с IBM Workplace Forms Viewer и Designer.

Создание расширений с помощью библиотеки FCI

Для создания расширения с помощью библиотеки FCI необходимо выполнить шесть шагов, которые подробно описываются в следующих разделах.

Настойка среды разработки

Для использования библиотеки FCI нужно настроить вашу интегрированную среду разработки, добавив следующие файлы в CLASSPATH:

<Каталог установки Viewer>\2.6\API\70\java\classes\pe_api.jar
<Каталог установки Viewer>\2.6\API\70\java\classes\uwi_api.jar

Если на вашем компьютере установлен Workplace Forms Server API, в указанном ниже каталоге находятся также два JAR-файла:

<Каталог установки API>\Lib\Java

ПРИМЕЧАНИЕ: Файл pe_api.jar используется для компиляции приложений, которые используют API (в том числе библиотеки Form и FCI), а файл uwi_api.jar – для компиляции приложений, для которых требуется обратная совместимость.

Создание класса Extension

В классе Extension содержится метод extensionInit, который инициализирует расширения и предоставляет сервисы для вызовов функций. При инициализации приложения Workplace Forms, API проверяет наличие существующих расширений как в каталоге Extension программы Workplace Forms Viewer, так и в самой открытой форме. Если они будут обнаружены, вызывается метод extensionInit в каждом классе Extension.

Класс Extension должен реализовывать интерфейс Extension, предоставляемый библиотекой FCI. В этом интерфейсе определено несколько методов, однако метод extensionInit – единственный, который необходимо реализовать для создания нового расширения FCI. Этот метод используется для создания экземпляра объекта FunctionCall, содержащего определение и реализацию пользовательских пакетов и функций. Чтобы упростить создание класса Extension, можно расширить заранее определённый класс ExtensionImplBase, в котором для вас реализованы некоторые методы. Таким образом, требуется реализовать только метод extensionInit.

Для создания класса Extension, который называется FCIExtension, выполните следующие шаги:

1. В Workplace Forms Designer создайте новый Java-файл с именем FCIExtension.java.
2. Определите пакет Java, например, com.IBM.extensions.
3. Импортируйте перечисленные ниже файлы (и любые другие файлы, необходимые для Java-файлов, вызывающих библиотеку FCI). Список импортируемых файлов должен предшествовать любым определениям классов или интерфейсов:
• import com.PureEdge.ifx.IFX;
• import com.PureEdge.ifx.ExtensionImplBase;
• import com.PureEdge.ifx.Extension;
• import com.PureEdge.xfdl.FunctionCall;
• import com.PureEdge.xfdl.FunctionCallManager;
• import com.PureEdge.xfdl.FormNodeP;
• import com.PureEdge.IFSUserDataHolder;
• import com.PureEdge.error.UWIException;
4. Реализуйте метод extensionInit как часть класса Extension.
5. Создайте новый объект FunctionCall внутри метода extensionInit. Для этого необходимо вызвать конструктор класса FunctionCall и передать его IFX Manager, как показано в листинге 1.
   
   Листинг 1. Пример нового объекта FunctionCall
   

   public class FCIExtension extends ExtensionImplBase implements Extension { public void extensionInit(IFX IFXMan) throws UWIException { this.theFunctionObject = new FciFunctionCall(IFXMan); } }

   
   

Объект IFXMan представляет IFX Manager. Этот объект позволяет получать доступ к другим сервисам и объектам, которые вы желаете использовать с вашим расширением. UWIException является стандартным исключением.

Создание класса FunctionCall

Теперь создадим класс FunctionCall, который вызывается классом Extension и содержит ваши пользовательские методы. Он также регистрирует объект FunctionCall и каждую из пользовательских функций, которую он поддерживает. Класс FunctionCall должен реализовывать интерфейс FunctionCall, предоставляемый FCI. Нет необходимости реализовывать все функции, определённые в интерфейсе FunctionCall. Обычно класс FunctionCall расширяет заранее определённый суперкласс FunctionCallImplBase и просто реализует необходимый метод.

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

Для реализации класса FunctionCall выполните следующие шаги:

1. В Workplace Forms Designer создайте новый Java-файл с именем FciFunctionCall.java.
2. Определите пакет Java.
3. Импортируйте следующие пакеты API и любые другие необходимые файлы:
• com.PureEdge.ifx.IFX
• com.PureEdge.xfdl.FormNodeP
• com.PureEdge.xfdl.FunctionCallManager
• com.PureEdge.xfdl.FunctionCallImplBase
• com.PureEdge.xfdl.FunctionCall
• com.PureEdge.error.UWIException
4. Создайте класс FunctionCall. Он должен расширять суперкласс com.PureEdge.xfdl.FunctionCallImplBase и реализовывать интерфейс FunctionCall.
5. Задекларируйте уникальный идентификационный номер для каждой пользовательской функции, которую вы хотите создать с помощью FCI. В нашем примере мы создадим две пользовательские функции: functionA и functionB.
6. Определите конструктор класса FunctionCall, который использует IFX Manager.
7. Задекларируйте метод evaluate. Этот метод содержит вашу пользовательскую функцию и ниже описывается подробнее.
8. Добавьте систему помощи к вашей пользовательской функции, вызвав метод help. Этот метод содержит вашу пользовательскую функцию и также подробнее рассматривается ниже.

В следующем примере FciFunctionCall декларирует два пользовательских метода, functionA и functionB, имеющих идентификационные номера 1 и 2, соответственно (листинг 2).

                
public class FciFunctionCall extends FunctionCallImplBase 
_implements FunctionCall { 
public static final int FUNCTIONA = 1; 
public static final int FUNCTIONB = 2;

public FciFunctionCall(IFX IFXMan) throws UWIException 
{ 
/* Дополнительный код удалён */
} 

public void evaluate(……) 
{ 
/* Дополнительный код удалён */
}

public void help(……) 
{ 
/* Дополнительный код удалён */
}
}

Создание конструктора класса FunctionCall

Прежде чем ваши пользовательские функции можно будет сделать доступными приложению Workplace Forms, необходимо зарегистрировать объект FunctionCall и каждую из поддерживаемых им пользовательских функций, чтобы содержащиеся в нём функции и пакеты распознавались.

Класс конструктора FunctionCall принимает IFX Manager в качестве параметра. В ходе процесса конструирования класса выполняется вся работа по регистрации, в том числе регистрация расширений и функций. По существу, IFX Manager управляет расширениями Workplace Forms.

Для регистрации объекта FunctionCall выполните следующее:

1. Извлеките Function Call Manager с помощью объекта getFunctionCall. Он обрабатывает сервисы, характерные для вызовов функций, например, обрабатывает запросы конкретной функции, и представлен объектом FunctionCallManager.
2. Вызовите метод registerInterface объекта IFXMan для регистрации вашего расширения.
3. Зарегистрируйте пакеты пользовательских функций с помощью метода registerFunctionCall объекта FunctionCallManager.

В следующем примере извлекается Function Call Manager, регистрируется расширение, а также две наши пользовательские функции, functionA и functionB. Обратите внимание, что один из параметров каждой функции содержит уникальный идентификатор пользовательской функции (листинг 3).

                
public FciFunctionCall(IFX IFXMan) throws UWIException
{ 
FunctionCallManager theFCM; 
// извлекаем Function Call Manager
if ((theFCM = IFSSingleton.getFunctionCallManager()) == null)
throw new UWIException("Needed Function Call Manager"); 

// регистрируем расширение в IFX Manager
IFXMan.registerInterface(this,   
	FunctionCall.FUNCTIONCALL_INTERFACE_NAME, 
	FunctionCall.FUNCTIONCALL_CURRENT_VERSION, 
	FunctionCall.FUNCTIONCALL_MIN_VERSION_SUPPORTED, 
	0x01000300, 0, null, theFCM.getDefaultListener( ));

// регистрируем функции FUNCTIONA в Function Call Manager
theFCM.registerFunctionCall(this, "my_package", "functionA",
 	FciFunctionCall.FUNCTIONA, FunctionCall.FCI_FOLLOWS_STRICT_
	CALLING_PARAMETERS, "S,S", 0x01000300, "Here is functionA’s 
	description"); 

// регистрируем функции FUNCTIONB в Function Call Manager
theFCM.registerFunctionCall(this, "my_package", "functionB",
	FciFunctionCall.FUNCTIONB, FunctionCall.FCI_FOLLOWS_STRICT_
	CALLING_PARAMETERS, "S,S", 0x01000300, "Here is functionB’s 
	description"); 
}

ПРИМЕЧАНИЕ: Более подробную информацию о методах registerInterface и registerFunctionCall, в том числе описание их параметров, см. в Руководстве пользователя по Workplace Forms Java API.

Создание собственных пользовательских функций

Для создания собственных пользовательских функций необходимо использовать два метода:

• Evaluate. Этот метод вызывается всегда, когда нужно выполнить пользовательскую функцию. Когда пользовательская функция вызывается из приложения Workplace Forms, Forms Library извлекает имя пакета и функции. Затем она вызывает метод evaluate, который проверяет уникальный идентификатор функции и выполняет соответствующий сегмент кода. В этом методе можно либо вернуть значение, либо управлять находящейся в памяти формой напрямую. Ниже приведён пример использования метода evaluate (листинг 4).
  
  Листинг 4. Пример использования метода evaluate
  

  public void evaluate(String thePackageName, String theFunctionName, int theFunctionID, int theFunctionInstance, short theCommand, FormNodeP theForm, FormNodeP theComputeNode, IFSUserDataHolder theFunctionData, IFSUserDataHolder theFunctionInstanceData, FormNodeP[] theArgList, FormNodeP theResult) throws UWIException { // выполняем следующую процедуру во время работы функции if (theCommand == FunctionCall.FCICOMMAND_RUN) { // проверяем, какая пользовательская функция вызывается уникальным идентификатором if (theFunctionID == FciFunctionCall. FUNCTIONA_ID) { /* Дополнительный код удалён */ } if (theFunctionID == FciFunctionCall. FUNCTIONB_ID) { /* Дополнительный код удалён */ } } }

  
  ПРИМЕЧАНИЕ: Более подробную информацию о методе evaluate, в том числе описание его параметров, см. в Инструкции пользователя по Workplace Forms Java API.
  
  
• Help. С помощью этого метода разработчикам форм, работающим в среде разработки, например, Workplace Forms Designer, предоставляется справочная информация. Следует предоставить подробные объяснения по вашей пользовательской функции, чтобы разработчик формы имел возможность выбора и мог правильно использовать ту или иную функцию. Ниже приведён пример метода help (листинг 5).
  
  Листинг 5. Пример использования метода help
  

  public void help(String thePackageName, String theFunctionName, int theFunctionID,IFSUserDataHolder theFunctionData, StringHolder theQuickDesc, StringHolder theFunctionDesc, StringHolder theSampleCode, StringListHolder theArgsNameList, StringListHolder theArgsDescList, ShortListHolder theArgsFlagList, StringHolder theRetValDesc, ShortHolder theRetValFlag) throws UWIException { /* Дополнительный код удалён */ }

  
  

Сборка и упаковка расширения

После создания классов Extension и FunctionCall необходимо сделать следующее:

1. Скомпилируйте исходный код для создания файлов класса.
2. Создайте manifest-файл. В нём должно быть указано, какие классы в JAR-файле являются частью вашего расширения. В приведённом ниже примере показан типичный manifest-файл:
   
   Manifest-Version: 1.0
Name: com/yourcompany/samples/FCIExtension.class
IFS-Extension: True


3. Упакуйте файлы класса в один JAR-файл для распространения. В следующих примерах показан синтаксис, используемый для сборки JAR-файла, где com – это имя верхнего уровня пакета файлов класса:
   
   jar -cvfm FCI.jar manifest.mf com

ПРИМЕЧАНИЕ: Более подробную информацию по созданию JAR- и manifest-файлов см. в документации по Java.

В начало

Тестирование и распространение вашего расширения

Завершив создание расширения, нужно установить его и протестировать. Если вы довольны его производительностью, можете распространять его одним из двух способов:

1. Скопируйте JAR-файл в каталог Extensions программы Workplace Forms Viewer: <каталог установки Viewer>\extensions.
   
   ИЛИ
   
   
2. Встройте расширения в XFDL-формы с помощью Workplace Forms Designer, как показано на рисунке 1. На вкладке Enclosures разверните элемент JAR, правой кнопкой мыши нажмите PAGE1 и выберите из меню Enclose File.

Встраивание расширений в Workplace Forms Designer

Встраиваемые в формы JAR-файлы должны иметь тип MIME application/uwi-jar. Более подробную информацию о Workplace Forms Designer и типах MIME см. в Инструкции пользователя Workplace Forms Designer, которую можно загрузить со страницы документации по Workplace Forms на developerWorks.

Место, куда устанавливается расширение, определяет, какой уровень доступа будет иметь это расширение к системным ресурсам пользователя, например, к системным файлам. В таблице 1 приведена информация по функциям безопасности при установке расширения в определённое место.

В начало

Создание примера расширения FCI

Теперь мы продемонстрируем процесс создания расширений с помощью методов FCI и использования пользовательских функций в XFDL-формах. Мы создадим пример расширения, извлекающий информацию о файлах локальной файловой системы и отображающий его в форме. Этот пример приложения можно также использовать для интеграции с базой данных. Для этого нужно с помощью Java API получить доступ к информации о файлах локальной системы, а с помощью Form API – напрямую управлять XFDL-формами, размещёнными в памяти.

На рисунке 2 показана XFDL-форма, которая используется с вашим расширением. Пример JAR-файла встроен в неё для распространения.

Чтобы получить доступ к функциональности расширения, нажмите кнопку Browse и выберите файл на вашем компьютере. Пример пользовательской функции обратится к информации о файле и отобразит результаты в форме. На рисунке 3 показана форма, в которой отображена информация о файле, извлечённая расширением из локальной файловой системы.

Создание примера класса FunctionCall

Для начала необходимо создать класс FunctionCall, для чего требуется:

• Импортировать все необходимые пакеты.
• Расширить класс FunctionCallImplBase и реализовать интерфейс FunctionCall.
• Задать уникальный ID для вашей пользовательской функции.
• Зарегистрировать объект FunctionCall.
• Зарегистрировать вашу пользовательскую функцию.
• Создать метод evaluate, который будет содержать вашу пользовательскую функцию.

В примере класса FunctionCall, приведённом в файле класс Sample FunctionCall, метод registerFunctionCall передаёт следующую информацию FunctionCallManager:

• Пакет функции – sample_package.
• Имя функции – readFile.
• Функция readFile принимает только один параметр.

Более подробную информацию о методе registerFunctionCall, в том числе описание его параметров, см. в Руководстве пользователя по Workplace Forms Java API.

Создание класса Extension

Далее необходимо создать класс Extension, как показано в листинге 6, что предполагает:

• Импорт всех необходимых пакетов.
• Создание метода extensionInit и передача ему IFX Manager.
• Вызов класса конструктора FunctionCall, который мы создали в разделе "Создание примера класса FunctionCall".

                
package com.ibm.wpforms.samples;

import com.PureEdge.error.UWIException;
import com.PureEdge.ifx.Extension;
import com.PureEdge.ifx.ExtensionImplBase;
import com.PureEdge.ifx.IFX;

public class FCIExtension extends ExtensionImplBase implements Extension {
public void extensionInit(IFX IFXMan) throws UWIException {
new FciFunctionCall(IFXMan);
}
}

Распространение вашей пользовательской функции

Так как пользовательская функция используется для получения доступа к информации о файлах вашей локальной файловой системы, нельзя встроить её в XFDL-форму. Workplace Forms Viewer считает форму небезопасной и генерирует Java-исключение. Следовательно, распространять пользовательскую функцию вашим пользователям следует другими способами. Можно, например, создать папку с общим доступом, отправить файл по электронной почте или Интернету или попросить администратора выполнить установку. Как только JAR-файл окажется на компьютере пользователя, его нужно сохранить в каталоге Extensions продукта Workplace Forms, использующего данное расширение, например, в <каталоге Workplace Forms Viewer>\extensions.

Создание примера XFDL-формы

Прежде чем можно будет использовать вашу пользовательскую функцию, необходимо создать XFDL-форму, запускающую функцию, как показано в файле "Пример XFDL-формы". Пример FCI Extension Eclipse Project с демонстрационной формой можно найти в разделе Загрузка данной статьи. Для получения дополнительной информации о создании XFDL-форм с помощью Workplace Forms Designer см. Руководство пользователя Workplace Forms Designer.

В начало

Использование пользовательской функции внутри формы

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

1. Откройте пример формы в Workplace Forms Designer.
2. Создайте элемент кнопки XFDL в примере формы, выбрав кнопку из палитры и поместив её на страницу формы.
3. Выбрав кнопку, нажмите на вкладку Source.
4. В исходном коде формы добавьте к кнопке пользовательскую опцию: <custom:onSelect></custom:onSelect>
5. Добавьте к пользовательской опции атрибут compute, убедившись, что он находится в пространстве имён XFDL: <custom:onSelect xfdl:compute="">
6. Создайте compute, запускающий вашу пользовательскую функцию при нажатии пользователем на кнопку Browse. После нажатия кнопки задайте место размещения файлов с помощью функции Workplace Viewer fileOpen. Если выбран какой-либо файл, запустите пользовательскую функцию; в противном случае не делайте ничего (листинг 7).

                
<button sid="BUTTON1">
	<itemlocation>
		<x>750</x>
		<y>70</y>
		<height>24</height>
	</itemlocation>
	<value>Browse</value>
	<bgcolor>#C0C0C0</bgcolor>
	<custom:onSelect xfdl:compute="toggle(activated,'off','on') == '1' ? 
	set('fileLocation.value', viewer.fileOpen('C:\\', '*.*'))  +. 
	(fileLocation.value != '' ? sample_package.readFile(fileLocation.value) : '')
 	: ''"></custom:onSelect>
	<fontinfo>
		<fontname>Verdana</fontname>
		<size>10</size>
	</fontinfo>
</button>

В начало

Заключение

Workplace Forms Server API и библиотека Function Call Interface являются мощными гибкими инструментами для расширения функциональности приложений Workplace Forms. Надеемся, что с помощью пошаговых инструкций из нашей статьи разработчики, обладающие небольшим опытом, смогут разработать собственные пользовательские функции.

В начало

Загрузка

Информация о методах загрузки

Ресурсы

Научиться

• Оригинал статьи: Extending the functionality of IBM Workplace Forms with the Function Call Interface (EN).
  
  
• Статья developerWorks Workplace: Введение в IBM Workplace Forms (EN).
  
  
• Статья developerWorks Workplace Обзор IBM Workplace Forms (EN).
  
  
• Статья developerWorks Workplace: Представляем IBM Workplace Forms Server API 2.5 (EN).
  
  
• Страница документации по Workplace Forms на developerWorks (EN).
  
  
• Страница developerWorks по Workplace Forms (EN).
  
  

Получить продукты и технологии

• Загрузите ознакомительную версию Workplace Forms Designer и Viewer V2.6.1.(EN)
  
  

Обсудить

• Примите участие в обсуждении материала на форуме.
  
  

Об авторах

Оценить эту статью

Комментарии

В начало

Содержание

• Создание расширений с помощью библиотеки FCI
• Тестирование и распространение вашего расширения
• Создание примера расширения FCI
• Использование пользовательской функции внутри формы
• Заключение
• Загрузка
• Ресурсы
• Об авторах
• Комментарии