Grid Browser - Administration Guide : Loading Data

1. Loading Data into the Grid Browser

The data on the row and column axis are typically loaded via an inquiry, through a JPO or via a Java class that implements a specific interface.

In the case when you display a structure, you typically don’t load data into the row-axis – instead, the object, which the Grid Browser were launched for, will be used as root-object within the structure. The data within the row-axis is changed when the user expands or collapses the structure. There are a number of ways to configure how and what data should be returned when expanding an object. This is described in this chapter.

1.1. Configuration

Within the Grid Browser configuration, there are two sections called "Columns" and "Rows". These sections control the appearance of the column and row axis.

Within each of these sections, you will define a "DataLoader" section. The "DataLoader" defines everything regarding the initial load of each axis.

This is illustrated in the configuration snippet below:

<GridBrowser>
    <Columns>
        <DataLoader inquiry="MyInquiry" format="flat">
            <Sort by="name" ascending="true"/>
        </DataLoader>
    </Columns>
    <Rows>
        <DataLoader format="indented">
        ...
        </DataLoader>
    </Rows>
</GridBrowser>

1.2. Format

The format of the data can vary. The column axis typically shows a flat-list of objects. The row axis could show a flat-list, a structure with one root node or a structure with multiple root nodes.

The following values are accepted in the format attribute:

Value	Description
flat	Used for flat list of objects. This is the default value if omitted.
indented	Used for displaying a structure with one root-node.
indented-multi-root	Used for displaying a structure with multiple root-nodes.
vcc-structure	Convenient format when navigating an object structure within the Variant Configuration Central application, where certain object instances are not relevant within the Grid Browser (shadow objects).

Value

Description

flat

Used for flat list of objects. This is the default value if omitted.

indented

Used for displaying a structure with one root-node.

indented-multi-root

Used for displaying a structure with multiple root-nodes.

vcc-structure

Convenient format when navigating an object structure within the Variant Configuration Central application, where certain object instances are not relevant within the Grid Browser (shadow objects).

1.3. Loading via a Dataset

A dataset is a powerful way to express complex data-retrieval by XML configuration, which normally would require implementing a Java class.

To use a dataset, one specifies the name of the dataset within the Data Loader as shown below:

<DataLoader format="flat" dataSet="tvc:dataset/Example.xml"/>

For additional information about data-sets, see the ”TVC Core Administration Guide”.

1.4. Loading via an Inquiry

An inquiry typically contains a MQL statement that returns a set of objects. In some cases the returned data could represent a structure.

To use an inquiry, one specifies the name of the inquiry within the Data Loader, like below:

<DataLoader inquiry="MyInquiry" format="flat">

It is also possible to pass arguments to the inquiry, this is done by:

<DataLoader ...>
    <Arg name="NamePattern" value="A*"/>
    <Arg name="VaultPattern" value="Prod"/>
</DataLoader>

Remember to specify the parameter also on the inquiry.

If the data format is set to indented, the specified inquiry will be used for loading the root nodes (unless the inquiry is constructed to return hierarchical data).

1.5. Loading via a Java Loader

It is possible to use a custom loader written in Java that populates the Grid Browser.

<DataLoader loaderClass="com.acme.gridbrowser.MyLoader"/>

The class must implement the following interface:

com.technia.tvc.gridbrowser.ext.Loader

This interface has one method that you need to implement:

public class MyLoader implements Loader {
    public void loadInto(GridBrowser grid,
                         AbstractTableBean<? extends TableData> t,
                         Map<String, String> args,
                         Format format) throws TVCException {
        /*
         * Logic goes here
         */
    }
}

1.6. Loading via a JPO

It is also possible to invoke a JPO to load the data. Just specify the name of the JPO and the method to be invoked.

<DataLoader jpo="MyJPO" method="getData" format="flat">

The method being invoked must return a "java.util.List" instance containing "java.util.Map" instances representing each row. At minimum, each Map must contain an "id" key pointing to an object-id. Additionally, the "id[connection]" key can contain a connection id.

If the data format is set to indented, the specified JPO will be used for loading the root nodes within the structure.

When the Grid Browser is installed, a program called "TVCGridBrowserSample" is installed to the database. This program contains some examples that illustrate the JPO usage.

It is also possible to provide arguments to the method being invoked. This is done by:

<DataLoader ...>
    <Arg name="firstArg" value="firstValue"/>
    <Arg name="secondArg" value="secondValue"/>
</DataLoader>

1.7. Expanding Structures

The row axis allows showing a structure and allows the user to collapse and expand the structure using the navigation buttons, unless this has been disabled (see this chapter)

What data is retrieved once the user expands a node in the structure is configured within the "Expand" element below the "DataLoader".

There exists a number of different ways to do the expansions, for example:

Using traditional filters. Filters are easy to construct, and by using filters, one can allow the user to change filters or combine different filters in order to get different data in the Grid Browser.
Specifying the relationship pattern, type pattern, object where clause, relationship where clause and directions directly within the configuration. This is the easiest way IF the user never should be able or be allowed to configure how to expand the structure.
Using an Inquiry that returns the next level items
Using a Java class that is responsible for doing the expansion
Using a JPO that is responsible for doing the expansion
Specifying a so called shadow structure.

1.7.1. Filters

The filters are specified within the Filters element below the Expand element like the example below:

<DataLoader>
    <Expand>
        <Filters combinable="true|false" role="role_GlobalUser">
            <Filter name="MyFirstFilter" active="true"/>
            <Filter name="MySecondFilter" active="true"/>
            <Filter name="MyThirdFilter" active="false"/>
        </Filters>
    </Expand>
</DataLoader>

On the "Filters" element you can specify whether or not the filters can be combined together or if they are used one-by-one.

The role attribute defines where to load the filters from (if they are stored in the database).

Each filter used is added below the "Filters" element and you must specify if the filter is active or not.

To enable the Filter chooser, see this chapter.

Figure 1. Filter chooser.

1.7.2. Specifying the Expand Criteria

You can specify the expansion criteria inline in the Grid Browser configuration like the example below illustrates.

<Expand>
    <RelationshipPattern>
        <Relationship>relationship_EBOM</Relationship>
        <Relationship>relationship_PartSpecification</Relationship>
    </RelationshipPattern>
    <TypePattern>
        <Type>type_Part</Type>
        <Type>type_DOCUMENTS</Type>
    </TypePattern>
    <Direction>from</Direction>
    <RelationshipWhere></RelationshipWhere>
    <ObjectWhere></ObjectWhere>
</Expand>

The direction can be any of: "from", "to" or "both".

1.7.3. Other Expansions

The other kinds of expansions that can be made are by using: Inquiries, JPOs, Java classes or by specifying a shadow structure.

This is configured by using the following syntax:

<Expand>
    <Mode>...</Mode>
</Expand>

The value you type in is a string specifying the expansion-mode. This is described in details within this document .

Some examples are show below:

<Expand>
    <Mode>jpo:MyJPO:myExpandMethod</Mode>
</Expand>

<Expand>
    <Mode>java:com.acme.grid.MyExpander</Mode>
</Expand>

<Expand>
    <Mode>shadow:type_FeatureList,type_RequirementList</Mode>
</Expand>

<Expand>
    <Mode>shadow:type_AType,type_AnotherType:relationship_Rel1,relationship_Rel2</Mode>
</Expand>

<Expand>
    <Mode>shadow::relationship_Rel1,relationship_Rel2</Mode>
</Expand>

1.7.4. Initial Expand Mode

In the case when you display multiple root nodes, the first root node is the only one being expanded initially. To change this behaviour, apply the following to your configuration:

<Expand>
    <InitialExpandMode>none|first|all</InitialExpandMode>
</Expand>

The default value is "first".

1.7.5. Initial Expand Depth

The initial expand depth can be defined by applying the following to your configuration:

<Expand>
    <InitialExpandDepth>2</InitialExpandDepth>
</Expand>

The default value is 1.

1.7.6. Freezing the Structure

To disable the possibility to expand and collapse the structure, you can freeze it by applying the following to your configuration:

<DataLoader>
    <Expand>
        <Freeze>true</Freeze>
    </Expand>
</DataLoader>

1.8. Sorting the Data

The loaded data can be sorted. Note that when you for example is displaying a structure on the row axis, or the column axis objects are grouped, the sorting behaviour is differs.

<DataLoader inquiry="MyInquiry">
    <Sort by="modified" ascending="true"/>
</DataLoader>

If you rely on the data being shown in the order they are returned from for example a JPO, or if they already are sorted, you can disable the sorting by applying the following attribute:

<DataLoader sortingDisabled="true" .../>

1.9. Grouping Column Objects

The column objects can be grouped together based upon some condition.

The example below illustrates objects being grouped into two categories:

Figure 2. Column grouping.

To accomplish this, use the <Hierarchy> element within the <Columns> element, see this chapter for configuration details.

This example was created with the following configuration:

<Hierarchy>
    <Level key="originated" dateFormat="yyyy-QQQQ">
        <Label>Originated</Label>
    </Level>
    <Level key="attribute[Country]">
        <Label>Country</Label>
    </Level>
</Hierarchy>

1.10. Examples

1.10.1. Data Set Example

Data sets can be used to load data into the grid browser instance. Data sets is a feature available from TVC Core and is described more in detail in the TVC Core Administration Guide.

The example below illustrates how to define a dataset as a loader:

<DataLoader dataSet="tvc:dataset:tvx:enc/GetRDOsInEBOM.xml">
    <Sort by="Name" ascending="true"/>
</DataLoader>

The code for this data set is shown in the example below:

<DataSet>
    <RemoveDuplicates>
        <Select>
            <Statement><![CDATA[
            $<to[relationship_DesignResponsibility].from.id>
            ]]></Statement>
            <Expand>
                <From>true</From>
                <To>false</To>
                <Depth>0</Depth>
                <TypePattern>
                    <Type>type_Part</Type>
                </TypePattern>
                <RelationshipPattern>
                    <Relationship>relationship_EBOM</Relationship>
                </RelationshipPattern>
            </Expand>
        </Select>
    </RemoveDuplicates>
</DataSet>

This definition will first expand the source object (the object coming from the request) along the EBOM relationship to find all Parts. Secondly, for all Parts, select the design responsible organization. Finally, remove all duplicate objects.

1.10.2. Inquiry Loader Example

First, define an inquiry with the properties like below:

Pattern : '*|*|*|$\{OID}'
Format  : '$\{OID}'
Code    : 'temp query bus $\{TYPE} $\{NAME_PATTERN} * limit 10 select id dump |;'

Argument 1:  Name: NAME_PATTERN
            Value: dummy
Argument 2:  Name: TYPE
            Value: dummy

Define the DataLoader in the grid definition like below:

<DataLoader inquiry="MyInquiry">
    <Arg name="NAME_PATTERN" value="A-*"/>
    <Arg name="TYPE" value="type_Part"/>
</DataLoader>

Once the inquiry is evaluated, it will substitute ${TYPE} with the real name of the type Part, and the ${NAME_PATTERN} with A-*.

For inquiries that returns structured data, the inquiry should be created as below:

Pattern : '${LEVEL}|*|${DIRECTION}|*|*|*|${OID}|${RELID}'
Format  : '${LEVEL}|${DIRECTION}|${OID}|${RELID}'
Code    : 'expand bus ${ID} recurse to all from rel EBOM select bus id select rel id dump |'

Argument 1:  Name: OID
            Value: dummy

1.10.3. JPO Loader Example

First, define a JPO that looks similar to the example below:

public class ${CLASSNAME} {
    public ${CLASSNAME}() {}

    public ${CLASSNAME}(Context ctx, String[] args) {
    }

    public List getData(Context ctx, String[] args) throws Exception {
        HashMap paramMap = (HashMap)JPO.unpackArgs(args);
        String namePattern = (String) paramMap.get("NAME_PATTERN");
        String type = (String) paramMap.get("TYPE");
        ...
    }
}

Define the DataLoader in the grid definition as below:

<DataLoader jpo="MyJPO" method="getData">
    <Arg name="NAME_PATTERN" value="A-*"/>
    <Arg name="TYPE" value="type_Part"/>
</DataLoader>

When the JPO is executed, the arguments are packed and passed to the JPO as arguments.