Programming Patterns

A typical DataSource usage pattern involves these steps:

  1. Client calls a workflow rule.
  2. In the workflow rule event-handler method, create DataSource instance and set its properties.
  3. Use the DataSource to access the data.
  4. Return the results to the client.

Here is an example:

/**
* Get work request assigned on or after specified date.
*/
public DataSet getWorkOrders(Date dateFrom) {
// create the DataSource and set its properties
String table = "wo";
String[] fields = ["wo_id", "wo_type", "date_assigned", "description"];

DataSource ds = DataSourceFactory.createDataSourceForFields(table, fields);
ds.addRestriction(Restrictions.gte("wo", "date_assigned", dateFrom));

// create, update, or get records
List<DataRecord> records = ds.getRecords();

// return results to the client
return new DataSetList(records);
}

Loading DataSource from the view file

Data Sources defined in any 2.0 view file can be loaded directly from view files:

/**
* Get work request assigned on or after specified date.
*/
public DataSet getWorkOrders(Date dateFrom) {
// load the DataSource from the view file, and set its properties
DataSource ds = DataSourceFactory.loadDataSourceFromFile("ab-ex-wo", "woDS");
ds.addRestriction(Restrictions.gte("wo", "date_assigned", dateFrom));

// create, update, or get records
List<DataRecord> records = ds.getRecords();

// return results to the client
return new DataSetList(records);
}


DataSourceFactory methods always return a new instance of the DataSource. Your code can modify the returned DataSource instances without affecting other views or workflow rules that use the same DataSource definition from the view file.


Load or create?

Load DataSources from views to allow non-programmers to modify DataSource definitions without editing/compiling/deploying Java classes.Useful modifications include:

  • Adding restrictions;
  • Editing custom SQL queries;
  • Adding fields.


Create DataSources programmatically to ensure that DataSource definitions and the business logic that uses them are always in sync.


DataSource caching

When a view is rendered, the data sources defined in that view are added to the global data source cache. The loadDataSourceFromFile () method uses cached data source definitions when they are available, or loads data source definitions directly from view files if data sources have not been cached yet.

In debug mode (the debug property is in the core.properties file), you can change view files without restarting the server. If you change a data source definition in the view file, you must reload that view in the browser in order for the changed data source definitions to be updated in the global data source cache.