XMLCustomResourceExample (prior to V3.3)
Creating a Custom Resource Specification
See also: Working with Custom resources, How Resources Work
!! Use of XMLCustomResourceExample is deprecated and this documentation is provided to support forms created prior to Ebase V3.3. New forms requiring access to XML or Web Services should use XML Resources.
This example has been provided to demonstrate how a custom resource can be used to manipulate data from an external source; one which is not provided natively by Ebase.
In this case, our custom resource has been created to read, write and update an XML flat file.
The following items comprise this XML custom resource example:
1.
The custom resource
specification in Ebase Designer:
Shared/Resources/Custom_resources/XMLCustomResource
i. Samples/XMLCustomResource.java
i. SAMPLES/Forms/XMLCustomResourceExample
i. Samples/flights.xml
N.B. The java implementation of this custom resource (number 2 above) has itself been written in a generic way. It is intended for use not only with the specific XML file listed in number 4 above, but also for more general use on XML flat files. The given XML file and a sample Form have been included for completeness.
Each XML file has a particular structure (often defined by a DTD or Schema) for which a Custom Resource Specification must be created. Our example uses the XML flat file described in number 4 above. A particular Custom Resource specification was created for this file; its location is described in number 1 above. Many XML files could be created which use this XML Custom Resource, but all of these files would contain the same field names as shown in the resource (fields such as Flights and Passengers).
The Flights.xml file contains a fictional flight schedule for a particular date. For each of the flights departing on that day, a list of passengers is shown. The file contains both element values (FlightNo and Name) and an attribute (Passenger_SpecialNeeds). The custom resource specification parallels the structure of this file; explicitly listing which elements are attributes, which elements are repeating data (form a table of values), and which are keys or unique values. Key values are used when updating an XML element. It is analogous to the way that a Relational Database Management System (RDMS) handles updates on the rows of a relational table.
Example Form
When a form is created, the fields of a resource can be used within the form as described in How Resources Work. There is no difference between using a custom resource and using a native Ebase resource (such as a Database resource) when importing or using resource fields in your form. The difference between these two is that the Custom Resource must have a source Java program associated with it which defines what happens when a script command is issued on the resource or a fetchTable or updateTable command is issued against a table. Our form (number 3 above) has two tables which represent a parent-child relationship within the XML flights table.
The first table, the parent, represents the flights data; the FlightNo and Departure fields. The second table, the child, appears when the passengers of a certain flight are requested. The interaction between these two are done through a script on the button in the parent table. In addition to this script, there are a few others which control the reading of the data from an XML file, the update of data (in memory) and the writing of the data back out to an XML file.
Number 2 above shows the location of the Java source file which controls what happens when a script command is issued within the form. See Working with custom resources if you need to learn about the relationship between a script command and the implementing Custom Resource source file.
Xpath is used to search for XML elements within a file. Here is an example from the java code (number 3 above; see the fetchTable routine)) which finds all of the rows of a table:
String tableXPath =
pathToRowsOfTableFromRoot(ri, tableId);
List allElementsInPath
= null;
try
{
allElementsInPath = (List) XPath.selectNodes(root,
tableXPath);
}
Firstly, the key values are gathered and a path is created to the required repeating element (table) using the pathToRowsOfTableFromRoot function. Then, this path is used in an XPath expressiong to find all of the elements (rows) in the table which fulfil the path criterion.
Here is the rule that is used when searching for a unique element (analogous to an RDBMS row) within a table. When there is just one key field, then only this field's value will be used when searching for a unique "row" within the table. If there are multiple key fields within the element, then ALL of the keys are used in the search. If there are no keys used in a repeating element, then all of the fields will be used in an attempt to find a unique "row". Notice that it is much more efficient for searching to assign a key field or fields; otherwise, all of the fields in the "row" must be used in the search.
The implementing java source file, XMLCustomResource.java, can be used for many XML files other than the provided Flights.xml file. Let us assume that your new file is named myXMLFile.xml. If you want to use the given java implementation on your own myXMLFile.xml file, the steps are as follows:
PROTOCOL_TYPE must be either URL or FILE and denotes whether this 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, the parameters must meet the following requirements:
· PROTOCOL_STRING and FILENAME_PREFIX are both specified.
· PROTOCOL_STRING should specify the full path of a directory e.g. F:\ufs\UfsServer\generatedfiles\ including the final backslash (or forward slash for Linux/Unix systems)
· FILENAME_PREFIX is a file name. (e.g. flights.xml) which is appended to the end of PROTOCOL_STRING to form a unique file identifier.
If URL is specified, the specified URL program must be capable of reading and/or writing XML documents.
When writing to a file (i.e. FILE has been specified for PROTOCOL_TYPE and the WRITE command is being used in a script), a unique suffix is appended to the file name starting from “_nnnnn.xml” where nnnnn is a sequential number starting from 00001. Each resource has its own dedicated sequence.
Both read and write operations are supported. These are displayed as read only and cannot be altered.
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.
This is exactly the same as for other external resources e.g. databases. Any script command that is supported by the custom resource can be issued.
e.g.
|
FPL: |
API based language
(Javascript): |
|
read XMLCUSTOMRESOURCEEXAMPLE; |
resources.XMLCUSTOMRESOURCEEXAMPLE.executeCommand(CustomResource.COMMAND_READ); resources.XMLCUSTOMRESOURCEEXAMPLE.executeCommand(CustomResource.COMMAND_WRITE); |