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>

<FirstName>John</FirstName>

<Surname>Smith</Surname>

<DateOfBirth>19561031</DateOfBirth>

</row>

<row>

<FirstName>Jane</FirstName>

<Surname>Smith</Surname>

<MiddleName>Emily</MiddleName>

<DateOfBirth>19530921T00:00:00</DateOfBirth>

</row>

<row>

<FirstName>James</FirstName>

<Surname>Smith</Surname>

                              <DateOfBirth>19830916T00:00:00</DateOfBirth>

</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;