Topic Map Web Service Configuration

Topic Map Web Service Configuration
	Topic Map Web Service Definition

The Topic Map Web Service provides several configuration options which are managed by editing the Web.config file for the web application. This section describes these options and how they are configured.

Named Query Configuration

The TMWS Query operation allows clients to execute only named queries configured on the server. This allows the server administrator control over what queries are executed, prevents arbitrary SQL execution on the TMCore server and also allows the administrator to optionally specify caching to improve response times. Queries are configured on the server by adding one or more query elements to the queries custom section of the Web.config file. The structure is shown below:

<configuration>
  <configSections>
    <section name="queries" type="NetworkedPlanet.TMService.QuerySectionHandler, tmws" />
    <!-- Other section configurations go here -->
  </configSections>
  <!-- Other configuration elements go here -->
  <queries>
    <query name="NAME" topicMapParam="TM_PARAM_NAME">
      <tmrql>QUERY_STRING</tmrql>
      <param name="PARAM_NAME" type="PARAM_TYPE" />
    </query>
  </queries>
</configuration>

query/@name

This attribute specifies the name for the query. This name is used in invocations to the Query operation of the web service. This attribute is REQUIRED.

query/@topicMapParam

This attribute specifies the name of a query parameter which will receive the OID of the topic map identified in the query invocation. The parameter name should be in standard SQL parameter name syntax. This attribute is OPTIONAL. If this attribute is ommitted, then no topic map OID parameter will be provided.

query/@cacheTimeout

This attribute specifies the number of seconds that the results from the query will be cached by TMWS. Query results are cached based on parameters as well as the query, so only executing an identical query with result in the cached result being returned. This attribute is OPTIONAL.

query/tmrql

This element contains the SQL query to be executed. The query may contain an number of SQL parameters, but each parameter must match up either with the name provided in the topicMapParam attribute or one of the parameters defined by the following param elements. This element is REQUIRED.

query/param

This element provides a definition for one of the parameters to the query. This element is OPTIONAL and REPEATABLE.

When a query is executed, the values passed in the args parameter are bound to the parameters defined by the param elements in the order in which they are specified in the query configuration - so the first value in the args array is bound to the parameter defined by the first param element under the query element of the query being executed, and so on. An "Oid" type parameter must be bound to an value that can be parsed as an integer.

query/param/@name

Specifies the name of the attribute. The name must conform to standard SQL parameter name syntax. This attribute is REQUIRED.

query/param/@type

Specifies the type of the attribute. Currently only two types are supported: "Oid" and "String". Use Oid parameters to pass around topic, association or other topic map object identifiers. Use String parameters to pass around subject identifiers, subject locators, source locators, name strings, resource locators and occurrence and variant string values. This attribute is REQUIRED and its values are treated in a case-insensitive manner.

Example 7. Example of Query Configuration

<configuration>
  <configSections>
    <section name="queries" type="NetworkedPlanet.TMService.QuerySectionHandler, tmws" />
  </configSections>

  <queries>
    <query name="basic" topicMapParam="@tmId">
      <tmrql>SELECT topic_id FROM tm_topic WHERE topicmap=@tmId</tmrql>
    </query>
    <query name="topicByName" topicMapParam="@tmId">
      <tmrql>
      SELECT 
          tm_topic.topic_id, 
          dbo.tm_displayName(tm_topic.topic_id) as name, 
          tm_topic.type_id, 
          dbo.tm_displayName(type_id) AS typeName 
      FROM 
          tm_nameValue JOIN tm_topic ON tm_nameValue.topic_id=tm_topic.topic_id 
      WHERE 
          tm_topic.topicmap=@tmId AND name_value LIKE @nameValue
      </tmrql>
      <param name="@nameValue" type="string"/>
    </query>
    <query name="relatedTopics">
      <tmrql>SELECT DISTINCT r2p as topic_id FROM tm_assoc2 WHERE r1p=@topicId</tmrql>
      <param name="@topicId" type="oid"/>
    </query>
  </queries>
</configuration>

Query Ontology Configuration

The query configuration supports the use of an application ontology to make TMRQL query strings shorter and easier to read. The application ontology defines two kinds of mappings:

A mapping from a short code to a subject identifier URL. When the short code appears in a query string enclosed in curly braces (e.g. {shortcode}), it will be replaced by the object identifier of the topic in the topic map that has the mapped subject identifier.
A mapping from a short code to a subject identifier URL prefix. When the short code appears in a query string combined with a colon (:) and followed by a suffix (e.g. {shortcode:suffix}), it will be replaced by the object identifier of the topic in the topic map that has a subject identifier that matches the suffix part concatenated to the subject identifier URL prefix.

The use of application ontology has several benefits - it makes queries shorter and easier to read; it avoids having to constantly perform subject identifier look-ups for ontology topics which typically do not change very frequently; and it enables more efficient lookup by object identifier without the need to hardcode the object identifier value into the query string.

The ApplicationOntology object that performs this is described in detail in the TMCore API Guide. The structure for the configuration section for the ontology is shown below.

<configuration>
  <configSections>
    <section name="ontology" type="NetworkedPlanet.TMCore.Utils.OntologySectionHandler, tmcore" />
  </configSections>

  <ontology>
    <subject key="fruit" identifier="http://www.example.com/psi/types/fruit"/>
    <identifierPrefix prefix="fr" identifier="http://www.example.com/psi/fruits/"/>
  </ontology>
</configuration>

ontology: This is the wrapper element for the configuration. It must be named "ontology", all in lower case as shown. The configuration section must also be registered in the configSections portion of the Web.config file as shown in the example above.
ontology/subject: This element defines a single short-code to subject identifier mapping. This element is OPTIONAL an REPEATABLE. The example shown above maps the short-code "fruit" to the subject identifier URI "http://www.example.com/psi/types/fruit".
ontology/subject/@key: This attribute specifies the short-code for the subject identifier URI. This attribute is REQUIRED.
ontology/subject/@identifier: This attribute specifies the subject identifier URI that the short-code is mapped to. This attribute is REQUIRED.
identifierPrefix: This element defines a single short-code to subject identifier prefix mapping. This element is OPTIONAL and REPEATABLE. The example shown above maps the short-code "fr" to the prefix string "http://www.example.com/psi/fruits/", so the code fr:apple would be replaced by the object identifier of the topic that has the URI "http://www.example.com/psi/fruits/apple" as a subject identifier.
identifierPrefix/@prefix: This attribute specifies the short-code for the identifier prefix. This attribute is REQUIRED.
identifierPrefix/@identifier: This attribute specifies the URI prefix that the short-code is mapped to. This attribute is REQUIRED.

Once specified, the ontology configuration can be used in the TMRQL query strings of named queries as shown in the following example

Example 8. Using The Application Ontology for TMWS Named Queries

<configuration>

  <configSections>
    <section name="queries" type="NetworkedPlanet.TMService.QuerySectionHandler, tmws" />
    <section name="ontology" type="NetworkedPlanet.TMCore.Utils.OntologySectionHandler, tmcore" />
  </configSections>
  ...

  <ontology>
    <subject key="fruit" identifier="http://www.example.com/psi/types/fruit"/>
    <identifierPrefix prefix="fr" identifier="http://www.example.com/psi/fruits/"/>
  </ontology>

  <queries>

    <query name="fruitByName" topicMapParam="@tmId" cacheTimeout="60">
      <!-- Select topics with a name like @nameValue that are typed as fruit -->
      <tmrql>
      SELECT 
        tm_topic.topic_id, 
        dbo.tm_displayName(tm_topic.topic_id) as name
      FROM 
        tm_nameValue JOIN tm_topic ON tm_nameValue.topic_id=tm_topic.topic_id 
      WHERE 
        tm_topic.topicmap=@tmId AND name_value LIKE @nameValue AND tm_topic.type_id={fruit}
      </tmrql>
      <param name="@nameValue" type="string"/>
    </query>

    <query name="relatedToOrange" topicMapParam="@tmId" cacheTimeout="60">
      <!-- Select all topics that are related to the orange -->
      <tmrql>SELECT DISTINCT r2p as topic_id FROM tm_assoc2 WHERE r1p={fr:orange}</tmrql>
    </query>
  </queries>
  ...
</configuration>

The query named "fruitByName" shows the use of a full identifier short-code. In this case, the string "{fruit}" will be replaced by the object identifier of topic that has the subject identifier "http://www.example.com/psi/types/fruit". In the query "relatedToOrange", a prefix short-code is used instead so that the string "{fr:orange}" will be replaced by the object identifier of the topic that has the subject identifier "http://www.example.com/psi/fruits/orange".

Note

Only the TMRQL query string contained in the tmrql element of the query configuration is processed against the application ontology. It is not possible to pass in short-codes as parameters to a query.

Deprecated Query Configuration

This version of TMCore deprecates the old configuration for named queries. This form of configuration is still supported, but it is recommended that you do not use this form of configuration any longer as it is susceptible to SQL injection attacks.

Under the deprecated query configuration, a query is configured on the server by adding an entry to the appSettings element of the web.config for the web service. The value of the entry should be a normal TMRQL query string. To specify that a parameter passed in to the query should appear in the query, use the syntax {#} where # is replaced by the index of the argument in the argument list (starting with 0). For example:

<appSettings>
  ...
  <add key="query.topics.by.name"
       value="select topic_id as id, dbo.tm_displayName(topic_id) as name from tm_nameValue
  join topicmap on topicmap.id=tm_nameValue.topicmap and topicmap.mapname='{0}' and name_value like '%{1}%'" />
  ...
</appSettings>

ITopicMap object timeouts

Each time a query is executed by TMWS, it requires an ITopicMap instance. Obtaining a new reference has a small affect on performance because obtaining a map handle requires queries on tables in the database. By default, TMWS caches the ITopicMap instance for 60 seconds. This settings may be modified by setting the following property in the application config (Web.config) within /configuration/appSettings:

<add key="networkedplanet.com.tmcore.topicmapcache.timeout" value="0"/>

Setting the value of zero causes no caching to occur. You may need this if you have applications which are regularly deleting topic maps from the database.