Data Group Gatherer

The DataGroupGatherer class is provided to help developers create data plugins to gather data in fSeries. fSeries allows for the development of different data group types to gather data in different ways or from different sources. This class provides optional helper methods to more easily create data gathering plugins.

Namespace: fSeries.fData

Assembly: PluginHelpers.dll

The class provides a number of methods that provide access to the fSeries Data Gatherer during the process of gathering data based on a DSD (Data Set Definition). The following members are available.

Constructor

Name	Description
DataGroupGatherer()	Construction. Requires no parameters.

Read-Only / Set Once Data Gatherer Properties and Methods

These properties provide direct access to properties of the Data Gather and current data group (provided their setter properties are included).

Name	Type	Description
DataContainer	System.Xml.XmlNode	The Xml node to which row elements must be added to create the set of data for the data group.
ParameterValues	Systems.Collections.Generic.Dictionary<System.String,System.String>	A dictionary list of the key/value pairs from the Parameters property of the data group.
DataGatherer	Fibonacci.FAE.DataGatherer	Provides access to the DataGatherer class. Set once.
DataGroup	Fibonaci.FAE.DataGroup	Provides access to the DataGroup class for the data group being gathered. Set once.
Parameters	System.String	The parameter string (in querystring format key=value&key=value&…) defining the action required by the plugin. See also ParameterValues property. Set once.
Definition	System.Xml.XmlNode	The Xml node containing all data group definitions for the DSD (the “dataGroups” element).
Instance	System.String	The current configuration instance in operation.
Context	System.String	The context in which the plugin is being executed.
ContextData	System.String	The data associated with the context in which the plugin is being executed.
SamplePlaceholders	System.Boolean	Whether the Data Gather is operating with sample placeholders (indicates that a test load is being done or a schema is being created).
UserId	System.String	The logged in users identity.
Password	System.String	The logged in user’s password.
UserData(string Key)	System.String	Returns a value from the custom data obtained at login for the logged in user, for the key provided.
AllowAccess	System.String	Comma separated list of permission sets to which access is allowed for the current permission id
DenyAccess	System.String	Comma separated list of permission sets to which access is denied to the current permission id

Data/Schema Gathering Methods and Properties

Name	Type	Description
SetStatus(string Description, string Status, string Format)	Void	Adds or sets a status value that can be seen within fTest when testing the data gathering. Use for information and debugging. Format is optional and is passed on to the output of the data gatherer.
Schema	System.Xml.XmlNode	The element that contains the schema for the current data group.
Data	System.Xml.XmlNode	The element that contains the data for the current data group. This is the same element as DataContainer.
Row	System.Xml.XmlNode	The current data row. Values may be added to this element either by your code or using the AddValue method.
AddRow	void	Adds a new data row to the Data Container. The added row becomes the current row.

AddValue Method

This method adds a field value to the current data row (see Row method). If a data row has not already been added the first use of AddValue will create one. AddValue automatically updates the Schema for the data group, although this may be overridden to add your own schema if necessary. There are many overloads of this method in order to add values of different formats. Note that the format of a field is set on the first use of AddValue for the field and no exception is thrown if different formats are used for the same field. Adding a field with different formats may therefore cause confusion in outputs.

The field name must be a valid Xml element name. Attempts to add a value to a field with an invalid name are ignored.

Name	Description
AddValue(string Name, string Value)	Add a text value
AddValue(string Name, double Value)	Add a numeric value
AddValue(string Name, DateTime Value)	Add a date/time value
AddValue(string Name, bool Value)	Add a boolean value
AddValue(string Name, string Value, string Format)	Add a value with the specified format. The value will be added without checking its format, exactly as supplied. Available formats are: text, number, dateTime, or Boolean.
AddValue(string Name, string Value, DataFormat Format)	Add a value with the specified format. The value will be added without checking its format, exactly as supplied.

Shared Values and Object

These methods provide access to a repository of values and objects that may be saved from plugins and retrieved either by the same plugin or by others. This makes it possible to pass data from one data group to those processed later in the DSD, or their child data groups.

Name	Type	Description
SharedValue(string Id)	System.String	Retrieves the specified value from the repository.
AddSharedValue(string Id,string Value)	void	Saves a named value to the repository.
RemoveSharedValue(string Id)	Void	Removes the specified value from the repository.
SharedObject(string Id)	System.Object	Retrieves the specified object from the repository.
AddSharedObject(string Id, object Object)	void	Saves a named object to the repository.
RemoveSharedObject(string Id)	Void	Removes the specified object from the repository.

Sample Code

Making the Object Available

In your data plugin class, provide a public property that can be set by the calling Data Gatherer, as follows:

private DataGroupGatherer oDGG = new DataGroupGatherer();

public DataGroupGatherer DataGroupGatherer { set { oDGG = value; } }

The calling Data Gatherer will then set the oDGG object via the DataGroupGatherer property at the earliest opportunity, making its functionality available to your class.

Creating a Full Set of Data

In this full sample code a simple data group is created containing a list of family members with their names and dates of birth.

using System;

using fSeries.fData;

namespace fSeriesSampleClasses

{

public class fSeriesDataPlugin

{

//This allows fAdmin to locate this as a valid plugin and identify it

public string fSeriesPlugin { get { return “MyFamily”; } }

//This allows fAdmin to identify the plugin’s purpose (if specific) – data or extend

public string fSeriesPluginPurpose { get { return “data”; } }

//This allows fAdmin to identify the plugin’s available load methods

public string fSeriesPluginDataMethods { get { return “Load”; } }

//This allows fAdmin to identify the plugin’s available extend methods

public string fSeriesPluginExtendMethods { get { return “”; } }

private DataGroupGatherer oDGG = new DataGroupGatherer();

//Expose a public property that the DataGatherer can set

public DataGroupGatherer DataGroupGatherer { set { oDGG = value; } }

//This method loads the data and is referred to above in fSeriesPluginDataMethods

public void Load()

{

//start a new row for a family member

oDGG.AddRow();

//now add the family member’s details

oDGG.AddValue(“FirstName”, “John”);

oDGG.AddValue(“Surname”, “Smith”);

oDGG.AddValue(“DateOfBirth”, “1956-10-31″,DataGroupGatherer.DataFormat.dateTime);

//now the next member

oDGG.AddRow();

oDGG.AddValue(“FirstName”, “Jane”);

oDGG.AddValue(“Surname”, “Smith”);

oDGG.AddValue(“MiddleName”, “Emily”);

oDGG.AddValue(“DateOfBirth”, new DateTime(1953, 9, 21));

//and the last

oDGG.AddRow();

oDGG.AddValue(“FirstName”, “James”);

oDGG.AddValue(“Surname”, “Smith”);

oDGG.AddValue(“DateOfBirth”, new DateTime(1983, 9, 16));

}

The data gathered is as follows:

<data>

<row>

<Surname>Smith</Surname>

</row>

<row>

<Surname>Smith</Surname>

<MiddleName>Emily</MiddleName>

</row>

<row>

<FirstName>James</FirstName>

<Surname>Smith</Surname>

</row>

</data>

The schema generated is as follows:

<xs:schema id=”data“ xmlns=”” xmlns:xs=”http://www.w3.org/2001/XMLSchema“ xmlns:msdata=”urn:schemasmicrosoftcom:xmlmsdata“>

<xs:element name=”data“ msdata:IsDataSet=”true“ msdata:UseCurrentLocale=”true“>

<xs:complexType>

<xs:choice minOccurs=”0“ maxOccurs=”unbounded“>

<xs:element name=”row“>

<xs:complexType>

<xs:sequence>

<xs:element name=”FirstName“ type=”xs:text“ minOccurs=”0” />

<xs:element name=”Surname“ type=”xs:text“ minOccurs=”0” />

<xs:element name=”DateOfBirth“ type=”xs:dateTime“ minOccurs=”0” />

<xs:element name=”MiddleName“ type=”xs:text“ minOccurs=”0” />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:choice>

</xs:complexType>

</xs:element>

</xs:schema>

Adding Data Manually

Depending on how you gather data you may wish to either add rows one at a time or create a full data element (if you are not using the AddValue method).

To add individual rows use the Row property:

XmlNode xRow = oDGG.Data.OwnerDocument.CreateElement(“row”);

. Add the rows values

oDGG.Row = xRow;

Note that AddValue may be used after adding a row in this way to add or change further values.

To create a full data element

XmlDocument xData = new XmlDocument();

. Create data element

oDGG.Data = xData.DocumentElement;

Creating a Schema

If your plugin requires a schema that cannot be implied from the data (the default option for the Data Gatherer) or automatically created by using the AddValue method, you can create a schema and inform the DataGatherer. If you use AddValue this action MUST be included after all values have been added.

XmlDocument xSchema = new XmlDocument();

. Create schema

oDGG.Schema = xSchema.DocumentElement;