Working with XML resources (prior to V3.2)

Creating an XML resource in the designer1

Coding FPL script commands to access the resource. 2

What is an XML resource?

An XML resource is a specific implementation of a custom resource. It represents a connection to an XML resource and is implemented by a supplied Java class. This class supports the following operations:

· Creation and automatic naming of XML files in a specified directory

· Reading a single named XML file

· Reading and/or writing XML to or from a named URL

XML documents will be created (for write operations) or must be specied (for read operations) in a fixed format. See XML document format.

The steps involved in using an XML resource are the same as the steps for using other external resources:

1. Create the resource as described below.

2. Add the resource to the Resources View of a form.

3. Map the form fields to the resource fields.

4. Issue Read/Write script commands against the resource name.

Creating an XML resource in the designer

To create an XML resource, right click in the designer tree and select New > Custom Resource. In the popup window enter:

Custom Resource Name: the name for the new resource

Implementing class: com.ebasetech.ufs.mapping.XMLResource

This class is included with Ebase and does not need to be added to the classpath.

You will then see a dialog box similar to the one shown below.

Resource parameters:

PROTOCOL_TYPE must be either URL or FILE and denotes whether this XML resource is communicating with a URL (i.e. a program) or a FILE. It is not case sensitive (file/File/FILE are all valid). This parameter is required.

PROTOCOL_STRING is a string representing either a valid URL if URL is specified for PROTOCOL_TYPE (e.g. http://localhost/myXMLReceiver), or a valid file path if FILE is specified for PROTOCOL_TYPE.

This parameter is required.

If FILE is specified, this parameter can be either:

· A directory name (for use with the WRITE command) and requires that parameter PROTOCOL_PREFIX is also specified. It should specify the full path of a directory e.g. D:/UFS/xml/ including the final backslash (or forwardslash for Linux/Unix systems)

· A file name (for use with the READ command) This should specify the full path of the file(e.g. D:/UFS/xml/FnTestOUT.xml.

If URL is specified, the specified URL program must be capable of reading and/or writing XML documents.

PROTOCOL_PREFIX is required only when writing to a file (i.e. FILE has been specified for PROTOCOL_TYPE). It represents a numeric prefix, to which will be appended with "_nnnnn.xml" where nnnnn is a sequential number starting from 00001. Each Xml resource has its own dedicated sequence.

The table below shows the combination of parameters and commands that are supported.

PROTOCOL_TYPE

READ command

WRITE command

FILE

PROTOCOL_STRING contains full path name to file

PROTOCOL_STRING contains full path of directory

PROTOCOL_PREFIX contains prefix for created files

URL

PROTOCOL_STRING contains the URL

Implemented script commands

Both READ and WRITE operations are supported. These are displayed as read only and cannot be altered.

Resource fields

These represent the names of the individual tags within the XML document. Resource fields are also mapped to form fields as for all Ebase external resources. Note that custom resource field names are case sensitive and the resource field names must match the XML tag names including case.

Coding FPL script commands to access the resource

This is the same as for other custom resources: any script command that is supported by the custom resource can be issued.

e.g.

FPL:

API based language (Javascript):

read XMLIN;

write XMLOUTURL;

resources.XMLIN.executeCommand(CustomResource.COMMAND_READ);

write XMLOUTURL(CustomResource.COMMAND_WRITE);

XML document format

The following xml was generated by issuing a WRITE command to a custom resource with resource fields ADATE, anumber, ASTRING.

<?xml version="1.0" encoding="ISO-8859-1"?>

<Data>

<ASTRING>This was entered in a

text box</ASTRING>

</Data>

</UFSDocument>

<UFSDocument Id> represents the form which issued the Write command.

<UFSRelease> and <createdDate> are for information only and need not be supplied for input documents.

Tags enclosed within <Data> are resource field names (not form field names). Unmapped resource fields are written out with no data.

When reading xml, the only expected tags are <UFSDocument> and <Data>. Tags enclosed within <Data>, if any, are matched against resource field names, and if mapped to a form field, the form field is set to the value of the xml tag.