XMLCustomResource (prior to V3.3)
Overview
Components
Creating an XML Custom
Resource Specification
XML Custom Resource,
Resource Parameters
Implemented FPL script commands
Namespaces
XML Schema Import
Example Form
XML Custom Resource Java File
See
also:
Working with Custom Resources
WebServicesCustomResource
XMLRequestResponseCustomResource
!! Use of XMLCustomResource
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.
XMLCustomResource is a java class deployed with Ebase Server to integrate reading and writing XML Documents into Ebase forms. XMLCustomResource is an extension of the CustomResource class. XMLCustomResourceExample is deprecated and is replaced with XMLCustomResource. XMLCustomResource supports all XML syntax and XML namespace syntax. XMLCustomResource can be used to read and write to an XML flat file or a single URL. Also see WebServicesCustomResource for integrating XML based Web Services.
XMLCustomResource can be used to READ and WRITE to a file or URL. This is an extension of CustomResource and may not provide some functionally required. If extra functionality is required then please read the section on creating a CustomResource.
The following items comprise this XML custom resource:
1.
The custom resource
specification in Ebase Designer:
Shared/Resources/Custom_resources/XMLCustomResource
2.
The java implementation jar file containing the java class used by this resource:
ebaseCustomResource.jar
which contains XMLCustomResource.class used for this
particular custom resource.
3.
An example Form (plus
related form elements) in Ebase Designer which contains fields from the custom
resource:
SAMPLES/Forms/XMLCustomResource
4.
A particular XML flat file
which the custom resource in number 1 represents:
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. Number 3 and 4 above are to demonstrate the Flights.xml example. This example are deployed with Ebase to familiarise oneself with the XML Structure so that you can create your own XML Custom Resources.
Creating an XML Custom Resource Specification
Each XML file has a particular structure (often defined by a DTD or XML Schema) for which a Custom Resource Specification must be created. This section explains how to create and configure the flights.xml example deployed with the Ebase samples. This explains in more detail the relationship between the Resource Fields and Form Fields which is not described in this document.
Either open the XMLCustomResource as described above (Number 3) or you can create a new Custom Resource by selecting File/External Resources/Custom Resource from the file menu. If a new Custom Resource is created, you must specify XMLCustomResource in the implementing class field in the dialog. Specify a logical name that best describes your Custom Resource.
As shown in the flights example, the XML Structure
used to READ or WRITE is mirrored within the bottom panel. The XML is written
to / read from a file or url
in the exact structure as described in this panel. You can create new children
of an element by right clicking and selecting 'Add Child Field'. The Root
element cannot be renamed and the root of the actual XML document is a child
field of the Root Element. In the flights.xml
example, the Schedule element is the root of the document.
XML Custom Resource, Resource Parameters
XML Custom Resource supports five Custom Resource parameters.
FILENAME_PREFIX: The filename to read or write to.
Namespaces (Default): A list of default namespaces that can be mapped to an element in the resource fields panel. See Namespaces section in this document for more information on how to use namespaces..
Namespaces (Prefixed): A list of prefixed namespaces that can be mapped to an element in the resource fields panel. See Namespaces section in this document for more information on how to use namespaces.
PROTOCOL_STRING: Path to the location of the filename as described above, or a URL to read/write XML to.
PROTOCOL_TYPE: File (to read/write to file) or URL (to read or write to URL).
XML Custom Resource supports READ or WRITE script commands.
To call the XML Custom Resource from a script, it is invoked in the same way as any other custom resource:
|
FPL: |
API based language
(Javascript): |
|
read XMLCUSTOMRESOURCEEXAMPLE; |
resources.XMLCUSTOMRESOURCEEXAMPLE.executeCommand(CustomResource.COMMAND_READ); resources.XMLCUSTOMRESOURCEEXAMPLE.executeCommand(CustomResource.COMMAND_WRITE); |
XML Custom Resource also supports the following script statementsto update and retrieve table data:
|
FPL: |
API based language
(Javascript): |
|
fetchtable <tablename>; |
tables.<tablename>.fetchTable(); |
(See Working with Custom Resource for more information)
XML Custom Resource supports namespaces associated with an element. Using the Resource Parameters panel you can configure either default namespaces (no prefix) or prefixed namespaces.
Configuring Namespaces in the Resource
The Namespaces (Default) and Namespaces (Prefixed) can be entered as a list of URLs delimited with a ','. The URI must be associated with a prefix regardless of whether prefix is used (default namespaces will omit the prefix). To add a namespace to either default or prefixed namespace, enter the following into the relevant text field : <prefix>=<uri> and to add more than one enter : <prefix>=<uri>,<prefix>=<uri>,<prefix>=<uri> etc...
e.g to configure two prefixed namespaces, the following namespace configuration would be entered into the Namespaces (Prefixed) text field:
po=http://www.somecomapany.com/order/po,addr=http://www.somecompany.com/order/addr
Or to configure one default namespace, the following configuration would be entered into the Namespaces (Default) text field:
d=http://www.somecompany.com/order/purchaseorder
Mapping Namespace to element
To map the namespace to the appropriate element, add the prefix to the beginning of the External Name for the element configured in the Resource Fields Panel and separate using ':'. The prefix will then be associated with that element.
e.g to associate a namespace to an element with the name PurchaseOrder and Address edit the External Name in the Resource Fields Panel:
po:PurchaseOrder
addr:Address
N.B. When assigning prefixed namespaces, you should
associate all child elements with the same prefix as its parent. When assigning
default namespaces to an element, the namespace is automatically inherited by
all the children of namespace element.
(See XML Namespaces for more information)
XML Schema Import
It is possible to import from an XML Schema using the 'import from XML Schema' button. If you are new to XML Schemas then click here for further information.
Using the import from XML Schema, automatically populates the Resource Fields panel. To import from an XML Schema click the 'Import from XML Schema' Button:
1. Select the XML Schema file to import. N.B Must be well formed and have a file extension of .xsd
2. Select the Elements that you would like to import
3.
Click OK
When a form is created, the fields of a resource can be utilised within the form. 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.
The image below shows how
the Resource Fields map to Form Fields in Ebase Designer. N.B.
The flights.xml example contains two tables, which
table data is denoted by the selecting repeats for the repeating row data in
the Resource Fields Panel when configuring the XML Custom Resource.
The image below demonstrates the XML returned
when a 'fetchtable Flights' and 'fetchtable
Passengers' is called after issuing a read XMLCustomResource
when running the example form.
XMLCustomResource class is distributed as a separate download to Ebase application. The class file can be found within ebaseCustomResource.jar.
Updating the XML file
Apache XpathAPI is used to search for XML elements within a file. Here is an example from the java code (see the fetchTable routine) which finds all of the rows of a table:
String tableXPath = pathToRowsOfTableFromRoot(ri, tableId);
List allElementsInPath =
null;
try
{
XObject xobj=(List)XPathAPI.eval(root,tableXPath,resolver);
allElementsInPath
= xobj.list();
}
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 fulfill the path criterion. The resolver variable is a class scope HashMap of all the preconfigured namespaces. If no namespaces are configured, the HashMap remains empty. The resolver cannot be null.
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.