JavaFXComposerDSTutorial

1 Goal
2 Common Data Sources
3 Example Data Structure

Goal

This document is a guide to Data Sources (DS) in JavaFX Composer, their design and usage.

Getting the Functionality: Create a new JavaFx Composer project and look for the Data Sources category in the Palette window. After you find and expand that category, drag and drop a data source from the palette to the design view (the scene). JavaFx Composer will inject all necessary source files into your project (org.netbeans.javafx.datasrc.* package).

Common Data Sources

To simplify access to data coming from various sources in various formats we have unified the data format on client side so that it is easier for people to start using a remote data source. There are two basic aspects of each data source:

actual source of data (HTTP server, database, file, etc.)
format of data (XML, JSON, etc.).

JavaFX Composer data source framework defines a specialized DataSource class for each source of data (HttpDataSource, FileDataSource, etc.) and defines set of parsers for each supported data format (Parsers.XML_PARSER, etc.)

When a DataSource object retries the data, it typically passes the raw stream to a Parser which understand the format and shich produces a RecordSet, a common data format na JavaFX Composer. You will learn more about this structure later in this chapter.

To summarize, common data source framework consists of three three fundamental entities (classes):

DataSource - responsible for fetching raw data from the source
Parser - responsible for parsing raw data and producing RecordSets and Records
RecordSet - groups Records into an array, maintaining a cursor over it
Record - set of (name->value) pairs holding actual data

Data Source

A Data Source object holds basic properties needed to fetch data from a source. For example, for HTTP Data Source this is URL, Authentication method, etc. For JDBC Data Source this is a connection string, credentials and SQL query. For File Data Source this is a file path.

See the following table for an overview of JavaFX Composer supported data sources.

Name	Class	Supported Data Formats	Description
HTTP	HttpDataSource	XML, JSON, LINE, PROPERTIES	fetches data from HTTP and HTTPS servers. Supports BASIC authentication.
JDBC	DbDataSource	SQL Table	fetches data from a JDBC compliant database by executing an SQL query
File	FileDataSource	XML, JSON, LINE, PROPERTIES	reads a file on the local filesystem
JavaFx Storage	StorageDataSource	XML, JSON, LINE, PROPERTIES	uses javafx.io.Storage API to load data
Resources	ClasspathDataSource	XML, JSON, LINE, PROPERTIES	reads data from runtime classpath using java Classloader.getResourceAsStream

Example Usage: Create a DataSource

var ds = FileDataSource {
    autoRefresh: false
    path: "/home/johny/bookstore.xml"
    parser: Parsers.XML_PARSER
};

This will create a datasource that will read and parse the content of the file "/home/johny/bookstore.xml". XML parser will be used.

Example Usage: Get data from a DataSource

var rs : RecordSet;
rs = ds.getRecordSet();

rs now holds a RecordSet (array of records). To get to the first record, type:

var r : Record;
r = rs.current();

Remember that a RecordSet maintains a cursor over its Records and since we did not used the RecordSet yet, the cursor points to the first Record. Once you have a Record, you can get to the data:

var s : String;
s = r.getString("bookName");

This will set s to the content of the field "bookName".

RecordSet

A RecordSet serves two purposes:

it holds an ordered set of Records
it maintains a cursor over set of Records with the possibility to move it in both directions

The root data element in every data source is a RecordSet and you can get it by calling:

ds.getRecordSet()

Typically, RecordSets contain either a list of Records (ie. books in a bookstore) or contain just one Record (ie. XML element with one child). In the first case you typically get all Records from the RecordSet and pass it to a ListView or iterate over it and do some processing.

var ra : Record [];
ra = ds.getRecordSet().all();
... use the array of Records ...

In the latter case you typically quickly access the single Record in one of these two ways:

var ra : Record;
ra = ds.getRecordSet().current();

var surname : String;
name = ds.getRecordSet().currentString("surname");

rs.currentString() is a shortcut for rs.current().getString().

Record

A Record holds a set of (name, value) pairs. In JDBC data source each row in a table becomes a Record with column names as keys. When parsing XML, each element becomes a separate Record. In JSON, each object is transformed to a Record. Here are some examples of getting data from a record:

var r : Record; // the first book in a book store
r = ds.getRecordSet().current();

var name : String;
name = r.getString("bookName");

var authors : RecordSet;
authors = r.getRecordSet("authors");

var storeLocation : Record;
storeLocation = r.get("location") as Record;

Notice that Records can have fields of type RecordSet and Record, creating a tree-like structure. Below is an example of a real-world data structure where you can better imagine organisation of data in Records and RecordSets.

Example Data Structure

Here is an example how a JSON object maps to the Data Source structure used by the JavaFX Composer. This is a result of https://kenai.com/api/projects URL: