Revision as of 14:32, 2 August 2010 by Msandor (Talk | contribs)


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 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();
var first = rs[0];

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();;
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");
var val = r.getValue();
var children = r.getChildren();

This will set s to the content of the attribute "bookName", val to the value of the current Record and children to sequence of child Records


In pre-M8 API the cursor was maintained in a special RecordSet object, now cursor methods are available directly on a DataSource. You can either call getData() to get all data at once or use cursors to access data sequentially. The latter is more appropriate for accessing large sets of data without having to load them all into memory. JDBC data source directly supports this usecase via its lazyLoading property. Cusor API has the following methods:

  • next() - moves the cursor to the next Record
  • prev() - moves the cursor to the previous Record
  • hasNext() - returns true if there is a next Record
  • hasPrev() - returns true if there is a previous Record
  • current() - retrieves the current Record under the cursor
  • currentIndex() - retrieves the index of the current Record
  • setCurrentIndex() - sets the index of the current Record (random access, may be slow)
  • close() - should be called where you are finished with the cursor


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 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.


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