LVconf Type: External Server Connection

Overview

Use the LiveView Configuration File Editor to configure the External Server Connection lvconf file type. This configuration is used to define a source of data for a base LiveView data table, where that source is one of:

  • One or more StreamBase® Query Tables in a running StreamBase application module outside of the current LiveView project.

  • Another LiveView data table outside of the current LiveView project.

  • A table in a JDBC data source.

  • A TIBCO ActiveSpaces space.

  • A non-StreamBase table type, where you provide a custom table reading class.

When connecting to a remote data source, you can use either the Mappings feature, or the filtered alias feature, or both. Use the Mappings feature to convert table names from a non-StreamBase table type's allowed character set to the more restrictive table name character set in LiveView. Use the filtered alias feature to provide filtered read-only versions of a data table, such as US and UK versions of a Sales table.

External Server Connection Tab

Use the External Server Connection tab to specify the type of external server, to specify its location by specifying parameters, and to specify retry settings.

In the Type field, use the dropdown list to select one of the following options:

CEP Query Table

Use this selection to specify that the external data source is a Query Table in a running StreamBase application. With this selection, you must also double-click the uri parameter to specify the full StreamBase URI in sb:// or sbs:// format. Specify the path down to the container that holds the Query Table of interest, if applicable. All Query Tables in the specified StreamBase URI become available to serve from LiveView.

LiveView

Use this selection to specify that the external data source is from another LiveView table running on the same system or remotely. When using this option, you must specify at least the uri parameter to specify a LiveView URI in lv:// or lvs:// format. The other options shown in the Table Provider Parameters field typically do not need to be set.

JDBC

Use this selection when the external data source supports JDBC. Run the LiveView JDBC Table sample to learn more about this external data source.

When configuring LiveView to use this data source, you must:

  • configure the data source in a JDBC DataSource configuration file based on one of the following two examples.

    Example 1:

    name = "sample"
    version = 1.0.0
    type = "com.tibco.ep.streambase.configuration.jdbcdatasource"
    configuration = {
      JDBCDataSource = {
        serverURL = "jdbc:derby://localhost:51527/demo"
        driverClassName = "org.apache.derby.jdbc.ClientDriver"
      }
    }

    Example 2:

    name = "JDBC"
    version = 1.0.0
    type = "com.tibco.ep.streambase.configuration.jdbcdatasource"
    configuration = {
      JDBCDataSourceGroup = {
       jdbcDataSources = {    
         sample = { 
  • specify at minimum the dataSourceRefName parameter in the lvconf file, which must refer to the data source configured in the JDBC DataSource configuration file. For example:

    <external-server-connection id="Devices" type="jdbc-tables">
      <parameters>
        <parameter key="dataSourceRefName">sample</parameter>
        </parameters>
        <mappings>
          <mapping selector="DEVICES" formatter="%s"/>
        </mappings>
        <retry-parameters/>
    </external-server-connection>

LiveView supports fetching JDBC tables from an external JDBC data source, where the external data source can be any supported JDBC data source. You can filter the JDBC table list by specifying JDBC tables in the lvconf file. The LiveView Table sample's example below filters for one JDBC table called DEVICES:

<mapping selector="DEVICES" formatter="%s"/>

You can perform any SQL query (for example, a SQL query that joins n JDBC tables) and show the query results in one LiveView table. Also, multiple SQL query-based LiveView tables can be part of the same lvconf of external connection type.

You can query multiple JDBC tables from the same data source and send the results to n number of LiveView tables. To define LiveView tables, use Table as the prefix and enter a table name for each table:

<parameter key="TableYourNewLVTable1">
<parameter key="TableYourNewLVTable2">
...

Append n number of queries to your defined LiveView tables as needed. This example defines two queries for two LiveView tables:

<parameters>
  <parameter key="dataSourceRefName">sample</parameter>
     
  <parameter key="TableYourNewLVTable1">select 
    s.UNIT_ID as ID,
    d.UNIT_NAME as Unit,
    s.SERVICE_OPERATION as Operation,
    s.SERVICE_DATE as Date,
    c.NAME as Company,
    c.PHONE as Phone
    from SERVICE_DATA as s
    inner join DEVICES as d on s.UNIT_ID=d.UNIT_ID
    inner join SERVICE_COMPANY as c on s.SERVICE_CO_ID=c.SERVICE_CO_ID</parameter>
    
  <parameter key="TableYourNewLVTable2">select 
    s.UNIT_ID as ID,
    d.UNIT_NAME as Unit,
    s.SERVICE_OPERATION as Operation,
    s.SERVICE_DATE as Date,
    c.NAME as Company,
    c.PHONE as Phone
    from SERVICE_DATA as s
    inner join DEVICES as d on s.UNIT_ID=d.UNIT_ID
    inner join SERVICE_COMPANY as c on s.SERVICE_CO_ID=c.SERVICE_CO_ID</parameter>
</parameters>
...    
ActiveSpaces

Use this selection to specify that the external data source is TIBCO ActiveSpaces. Run the LiveView ActiveSpaces sample to learn more about using this external data source.

Custom Table Provider

Use this selection to specify that the external data source is in another format not provided by StreamBase or Spotfire LiveView. In this case, you must also specify the fully qualified path to a class in the classpath of the current Studio project. The specified class must know how to locate, read data from, and interpret the custom table type. Remember that the classpath when running projects in Studio is not necessarily the same as when running the same project from the command line. Use the Table Provider Parameters section to specify any parameters needed to locate the custom table.

Parameters Field

The parameters field applies to: CEP-query-tables, LiveView, or Custom Table Provider.

Parameter Description
uri (required): CEP-query-tables expects the URI parameter, stating the URI of the server. For example: sb://com.streambase.liveview:10000.

LiveView expects the same URI parameter, but with the LiveView port. Sample: lv://com.streambase.liveview:11080

username The username for connecting to the CEP server that the external LiveView server is based on.
password (optional): The password for connecting to the CEP server that the external LiveView server is based on.
liveview.streambase.connection.pool.max.connections (optional): default = 200
liveview.streambase.connection.pool.queries.per.connections (optional): default = 10000
liveview.streambase.connection.pool.publishers.per.connections (optional): default = 10000
liveview.streambase.connection.pool.connection.xmlrpc.timeout.millis (optional): default = 5000

Retry Parameters

Whichever server connection type you specify, the Retry Parameters apply equally well. Specify the interval in seconds between retry attempts (default = 10) and number of retries (default = 0) to attempt before abandoning the connection.

Mappings Tab

All settings in the Mappings tab are optional and can be left blank.

Use the Mappings field to combine a regular expression in the Selector column on the left with a formatting string in the Formatter column on the right. Use formatting strings in the manner of the Java.lang.String.format() method (which uses java.util.Formatter conventions).

The mappings feature is not normally required when using the CEP Query Table or LiveView types of external server connections. When using a Custom Table Provider type, use mappings to convert table names and paths from the remote connection to a form usable by LiveView. For example, use mappings to convert table names from a non-StreamBase table type's allowed character set to the character set allowed in LiveView, where table and field names are restricted to certain rules:

  • The name must begin with an alphabetic character or an underscore.

  • The name can contain only alphabetic characters, numerals, and underscores.

  • The name cannot contain hyphens, colons, periods, or other non-alphabetic characters.

Mappings Field

Selector: Required. Regular expression that is to select the names to pass through. To use only part of the name in the formatter, enclose in parentheses the portion of the regular expression that selects that portion.

Formatter: Optional. Formatter string for java.util.String.format that is to be used to create the replacement name from the selection in the selector.

Aliases or Selected Mapping Field

The Table Aliases and Filter fields are used in the same way as in the Aliases tab for Data Table lvconf types. The only difference is that for external sources, each alias or filter setting applies to the currently selected mapping in the Mappings section of this tab. All settings in this tab are optional, and can be left blank.

The combination of a table alias and filter expression creates a read-only filtered view of the table being configured. For example, for a Sales table, you can specify both US and UK views of the Sales table named Sales_US and Sales_UK that each shows only the location-specific sales data to appropriate audiences. Your application still makes all table updates only to the underlying base table, Sales. Those changes are immediately reflected in both filtered alias table views.

Table Aliases

Use this field to specify an alias format string that will provide a new name pattern for data that matches the predicate filter specified in the Filter field. Use formatting strings in the manner of the Java.lang.String.format() method (which uses java.util.Formatter conventions).

When you click the green Plus sign to add a new alias, the default format string is %s_alias. This accepts the current table name and appends an underscore and the string alias. Adjust this default as required.

For example, in the Hello LiveView sample, in the ItemsSales.lvconf file, you can specify an alias of %s_Toys. Since the table name for this configuration is the basename of the lvconf file, ItemsSales, the resulting alias becomes ItemsSales_Toys.

Filter for (selected table alias)

Select an alias specification in the Table Aliases column, then specify a predicate filter in the Filter for column. The filter is a StreamBase expression that is to be ANDed with the predicate that creates the table in a LiveView client application. That is, the predicate expression you enter here is ANDed with the WHERE clause, if any, in the SELECT statement that queries the server.

Continuing the example above, the Filter expression corresponding to the Table Alias format string %s_Toys might be category == 'toy'

You can use either single quotes in your filter expression as shown, or double quotes. Single quotes result in cleaner-looking XML for the underlying lvconf file, because the filter expression attribute is already within double quotes. However, if you use double quotes, they are automatically converted into quote entities and are read correctly.

Source Tab

The Source tab provides a text-based XML configuration file editor, which is a validating XML editor that is aware of the schema that defines the XML syntax of LiveView configuration files. See Text-Based XML Configuration File Editor for more information.