Object DataSource API

Object DataSource API
Prev	Chapter 10. Object DataSource	Next

The pushTo method is the engine that drives all data source record generation. It takes two parameters, cxt, a PushContext object, and dl a DataListener object. This section will describe the available methods provided by these two objects and the supporting objects on which they depend.

PushContext

The PushContext provides useful methods for other data sources, but is unlikely to be useful within JavaScript as the functions it provides can be done directly.

String getParameter(String name): Get the value of a parameter. You should use ${substitution} in JavaScript instead of calling this method, as substitutions are detected and will be included in prompts, whereas calls to getParameter will not be detected.
String substitute(String s): Performs ${substitution} replacement on an input string. Again, this is not useful within JavaScript, as you can use ${substitution} strings directly in the code.

DataListener

A DataListener receives data from a DataSource for subsequent processing. For Java use, DataListener (an interface) and all the classes referenced by it are in the com.elixirtech.data2 package. The methods listed are all public.

void startData(IDataSource src): This method must be invoked before sending any records or groups, to allow the listener to prepare for receipt. The src should be this (the ObjectDataSource itself).
void startGroup(DataGroup group): This method is called to indicate that the subsequent records are part of a group. This method should not be called if the data is not already sorted and grouped. Where data is grouped, groups may be nested, within other groups, but all records must be within the innermost groups. You are not allowed to have a group that contains both records and child groups. Similarly, if the top level is grouped, it can contain no records outside of those groups.
boolean processRecord(DataRecord record): Each record that the data source supplies is passed to the listener through this method call. Usually the method will return true. If the method returns false, then it indicates that the listener does not want to receive any more records. In this case, you can choose to stop sending records (additional ones will just be discarded anyway), but must send the necessary endGroup and endData calls to gracefully terminate the operation. The same applies if exceptions are caught - you should still send the necessary symmetrical endXXX calls to balance the startXXX calls you have already made.
void endGroup(DataGroup group): This method is called to indicate the end of a group. Each call to startGroup should be matched with a corresponding call to endGroup after the necessary records have been processed.
void endData(IDataSource src): This method must be invoked after sending all records and groups to indicate that no more information is available. The src should be this.

DataGroup

DataGroups delimits a set of sorted records into groups.

DataGroup(int level, String name): Construct a DataGroup at a particular level (starting at one). If groups are nested, then child groups would be at level two, etc. The name may be any String - the use depends on the DataListener. For example, an Excel DataStore will use the group name as the name of the Sheet.
int getLevel(): Retrieve the group level
int getName(): Retrieve the group name

DataRecord

A DataRecord supplies an array of objects conforming to the DataSource schema to the DataListener. The ObjectDataSource supplies a method newRecordInstance() to instantiate a record with the appropriate structure. Note that records cannot be reused - once a record has been passed to the DataListener, you cannot modify it and pass it again.

Object[] getData(): Get the array backing this DataRecord so that you can set values before passing it to the DataListener. You should set the values in the array according to their order in the schema (zero-based).

Prev	Up	Next
Object DataSource Wizard	Home	Working with Object DataSources