JavaFXComposerNewInM8

(Difference between revisions)
m (Write Support)
m (New Data Source API)
Line 1: Line 1:
== New Data Source API ==
== New Data Source API ==
-
=== Classes ===
+
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.)
-
=== Structure ===
+
When a DataSource object retries the data, it typically passes the raw stream to a Parser which understand the format and which produces a sequence of Records, a common data format na JavaFX Composer. You will learn more about this structure later in this chapter.
-
=== Filter ===
+
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 Records
 +
* '''Record''' - a named structure holding three elements: a single value, set of attributes (name->value pairs) and child Records (if any)
 +
 
 +
=== 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.
 +
 
 +
{| border="1" cellpadding="10" cellspacing="0"
 +
! 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 ===
 +
<pre>
 +
var ds = FileDataSource {
 +
    autoRefresh: false
 +
    path: "/home/johny/bookstore.xml"
 +
    parser: Parsers.XML_PARSER
 +
};
 +
</pre>
 +
 
 +
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 ===
 +
<pre>
 +
var rs : Record [];
 +
rs = ds.getData();
 +
</pre>
 +
 
 +
rs now holds a sequence of Records. You can also access Records in a cursor-like way by calling:
 +
<pre>
 +
var r : Record;
 +
r = ds.current();
 +
</pre>
 +
 
 +
Remember that a DataSource maintains a cursor over its Records and initially the cursor points to the first Record. Once you have a Record, you can get to the data:
 +
 
 +
<pre>
 +
var s : String;
 +
s = r.getAttrString("bookName");
 +
</pre>
 +
 
 +
This will set s to the content of the attribute "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:
 +
<pre>ds.getRecordSet()</pre>
 +
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.
 +
<pre>
 +
var ra : Record [];
 +
ra = ds.getRecordSet().all();
 +
... use the array of Records ...
 +
</pre>
 +
In the latter case you typically quickly access the single Record in one of these two ways:
 +
<pre>
 +
var ra : Record;
 +
ra = ds.getRecordSet().current();
 +
 
 +
var surname : String;
 +
name = ds.getRecordSet().currentString("surname");
 +
</pre>
 +
rs.currentString() is a shortcut for rs.current().getString().
 +
 
 +
== Record ==
 +
 
 +
Each Record has a name and holds three elements:
 +
* a value
 +
* set of attributes (name=>value pairs)
 +
* child Records
 +
 
 +
For example, in JDBC data source each row in a table becomes a Record with column names as attribute 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:
 +
<pre>
 +
var r : Record; // the first book in a book store
 +
r = ds.current();
 +
 
 +
var name : String;
 +
name = r.getAttrString("bookName");
 +
 
 +
var authors : RecordSet;
 +
authors = r.getAttr("authors") as RecordSet;
 +
 
 +
var storeLocation : Record;
 +
storeLocation = r.getAttr("location") as Record;
 +
</pre>
 +
 
 +
Notice that Records can have attributes of type Record [] and Record, creating a tree-like structure.
=== Location ===
=== Location ===

Revision as of 13:56, 2 August 2010

Contents

New Data Source API

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 which produces a sequence of Records, 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 Records
  • Record - a named structure holding three elements: a single value, set of attributes (name->value pairs) and child Records (if any)

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 : Record [];
rs = ds.getData();

rs now holds a sequence of Records. You can also access Records in a cursor-like way by calling:

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

Remember that a DataSource maintains a cursor over its Records and initially the cursor points to the first Record. Once you have a Record, you can get to the data:

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

This will set s to the content of the attribute "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

Each Record has a name and holds three elements:

  • a value
  • set of attributes (name=>value pairs)
  • child Records

For example, in JDBC data source each row in a table becomes a Record with column names as attribute 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.current();

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

var authors : RecordSet;
authors = r.getAttr("authors") as RecordSet;

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

Notice that Records can have attributes of type Record [] and Record, creating a tree-like structure.

Location

Location is new concept in M8 API and defines a precise location of a particular data or value, it's like a pointer to a variable. Once you have a Location you simply get and set the value it points to by calling get() and set() method on the Location object which makes sure the appropriate Record's attribute is accessed. You get a Location object by calling Record.getLocation(locationSpec: String) method. The locationSpec string has two parts:

  • a filter specification (see previous paragraph) that locates a Record
  • an attribute specification; can be empty in which case the Location will point to the Records' direct value, rather that one of its attributes' value

Here are examples of location specifications:

  • /bookstore/address/#zip - "/bookstore/address" navigates to the "address" Record and "#zip" selects the "zip" attribute of the "address" Record
  • /rss/channel/title - "/rss/channel/title" navigates to the "title" Record and since there is no attribute specification the Location will get/set the value of the "title" Record

Write Support

Unlike in the previous API version, every Record is now read/write. Attributes of a Record can be modified using the setAttr() method and its value can be changed with the setValue() method. Even more convenient is to get a Location object for the value you want to work with (read and/or modify) and use get() and set() methods on the Location object. All changes are propagated to the original Record. Whenever data in a Record change, the Record is marked dirty, see the next paragraph.

Dirty Flag

When a Record is modified it is marked dirty and all its parent Records are marked dirty as well. Dirty flag is a synthetic attribute of a Record and can be read and written by getDirty() and setDirty() methods. Calling setDirty(true) marks all parents dirty and setDirty(false) marks all descentants clean. You can check the dirty flag to see whether it is necessary to commit changes, ie. synchronize in-memory data with the original data source.

Data Source Customizer

New Data Source Components

Sequence-based Controls

The DSListView, DSChoiceBox controls are working with a sequence of the Records taken from a specified DataSource and Filter.

Item-based Controls

The DSCheckBox, DSLabel, DSPasswordBox, DSTextBox controls are working with a single attribute value specified by a Location within a DataSource.

New Validation Component

Form Customizer Improvements

Design usability improvements

  • The behavior of image placeholder has changed, allowing user to switch between standard and placeholder view.
  • Improved and simplified guidelines to lower confusion
  • Added new handlers to allow easily move parent container if child is selected.

Palette

Some categories in the Palette are collapsed initially, so only Layouts, Controls, new Data Sources and Templates categories are expanded.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo