Table Configuration Tasks

Contents

Configuring a Table Join
Configuring Data Persistence
Using xinclude Processing Instructions

This section provides examples of several advanced tasks that are achieved with lvconf files.

Configuring a Table Join

LiveView tables can be joined so that the updates to one table trigger a change in another table. These table joins define a lookup table which holds keys and values, and a target table which is filled in based on values in the lookup table.

While the LiveView Configuration File Editor does provide a form to configure the Preprocessor features of a data table, it does not support the join feature. To implement a table join as described in this section, use the text-based, validating XML editor on your lvconf files.

The <join> element of a data table's lvconf file is a child of the <preprocessor-chain> element. The <join> element takes two attributes:

foreign-key-table

The name of the table from which the join is to be implemented.

liveness

The type of join. Options are:

half-active

The join updates if the local table changes.

full-active

The join updates if either the local or foreign table changes.

For example, suppose you have two tables, JoinTargetTable and JoinForeignTable.

JoinTargetTable has the following fields:

<fields>
   <field name="OrderID" type="string"/>
   <field name="Side" type="string"/>
   <field name="Symbol" type="string"/>
   <field name="CompanyName" type="string"/>
   <field name="Account" type="string"/>
   <field name="Quantity" type="double"/>
   <field name="Price" type="double"/>
</fields>

JoinForeignTable has the following fields:

<fields>
   <field name="Symbol" type="string" ignore-case="true"/>
   <field name="CompanyName" type="string"/>
</fields>

On each update or insert to the target table, the value is picked up from the foreign table at the time of the update.

In half-active joins, changes to the foreign table have no immediate effect on the target table. Changes are only picked up by target table rows as each row is updated. To configure a half-active join, use the following preprocessor-chain element in the file JoinTargetTable.lvconf: 

<preprocessor-chain>
   <join foreign-key-table="JoinForeignTable" liveness="half-active">
      <join-keys>
         <join-key foreign-key="Symbol">Symbol</join-key>
      </join-keys>
      <target-fields>
         <target-field ref="CompanyName">CompanyName</target-field>
      </target-fields>
   </join>
</preprocessor-chain>

When the data is published to JoinTargetTable, it triggers a join process similar to that of the following SQL statement:

SELECT JoinForeignTable.CompanyName As CompanyName, JoinTargetTable.* As *
FROM JoinForeignTable, JoinTargetTable
WHERE JoinForeignTable.Symbol=JoinTargetTable.Symbol

Configuring Data Persistence

LiveView Server, by default, clears all tables in a project and starts data collection anew for every new server session. LiveView provides persistence settings to override this behavior. The <persistence> element is a child of the top-level <table-space> element of Table Space type tables. A Table Space table provides settings that can be imported into one or more data tables by specifying the table-space-ref attribute of the top-level <data-table> element.

Configure data persistence with the Persist Data, Restore Data on Start, and Folder fields of the Table Space tab of Table Space type lvconf files.

These fields correspond to attributes of the <persistence> element as follows:

  • The Persist Data check box determines whether the <persistence> element appears at all in the lvconf file.

  • The Folder field corresponds to the folder attribute. It takes a string value that specifies the name of a folder in the LiveView project folder where you want the persisted data to be stored. To back up your persisted data, copy this folder to a backup location.

  • The Restore Data on Start check box configures the restore-data-on-start attribute. When selected, data tables that import this Table Space reference are to be re-populated from their persisted logs when the server restarts.

Using xinclude Processing Instructions

LiveView configuration files support the use of an XML processing instruction in the form <?xinclude name="xml-include-file.xml". The name attribute can include a full Xpath expression that selects certain elements in the include file.

This feature allows you to share configuration elements across multiple tables. This feature is not supported by the forms-based lvconf editor. You must use and continue to use the text-based XML editor to configure processing instructions.

The following example illustrates how to use an XML processing instruction inside an lvconf file to include a subset of another lvconf file as a preprocessing step.

  1. Load the basic alerting sample:

    1. Start StreamBase Studio.

    2. Select File → Load StreamBase Sample from Studio's top-level menu.

    3. In the Load StreamBase Projects dialog, open the TIBCO LiveView category.

    4. Select the sample whose description is Shows basic alerting features with pre-configured alert rules and press OK.

  2. Add a file called incl.xml with exactly the following contents to the project folder. This file must not have an XML or DOCTYPE declaration: 

    <container>

    <commonFields>
        <field name="totalQty" type="int"></field>
        <field name="avgPrice" type="double"></field>
    </commonFields>
    
    <commonAggregations>
        <field ref="totalQty">Sum(quantityRemaining)</field>
        <field ref="avgPrice">Avg(lastSoldPrice)</field>
    </commonAggregations>

</container>

  3. Edit the file ItemsByCat.lvconf file to pull in the fields from the incl.xml file: 

    <liveview-configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/lvconf/">
 
 <!-- for details on this configuration, see ItemsByCatColor.lvconf -->
 <data-table table-space-ref="DefaultTableSpace" id="ItemsByCat"
          description="Live view of total quantity and average last sold price, aggregating by category"
             short-description="Rollup of items by category">
  <fields>
   <field name="category" type="string"></field>
         <!-- The following processing instruction pulls in the common fields.  
              Note the xpath to select the elements ends with a wildcard reference (/*).  
              This pulls in the children of commonFields, but not the commonFields node itself. -->
   <?xinclude incl.xml#/container/commonFields/* ?>
  </fields>
  <primary-key>
    <field ref="category"/>
  </primary-key>
  <data-sources>
   <data-source>
    <aggregation table-ref="Items">
     <field-map>
      <field ref="category">category</field>           
         <!-- Pull in several nodes by using /* in the xpath. -->
         <?xinclude incl.xml#/container/commonAggregations/* ?>
      </field-map>
    </aggregation>
   </data-source>
  </data-sources>
 </data-table>
</liveview-configuration>

  4. Run the project by right-clicking on an lvconf file and selecting Run As → LiveView Project.

  5. When you see message All tables have been loaded in the Console view, start LiveView Desktop.

  6. Double-click the ItemsByCat table in the Tables pane of LiveView Desktop. Notice that the table contains the field category, and, in addition, the fields totalQty and avgPrice that you configured in the incl.xml file.