| NetworkedPlanet | TMCore Web Services Guide |
Table of Contents
The TMCore product provides two principle ways to access and update topic map data. The full .NET API is suitable for complex applications that need fine-grained control over the update of topics and is also suitable for creating your own ASP.NET controls or other server-side applications. The TMCore Web Services interface is suitable for creating n-tier applications and for developing client-server applications. There are several major advantages to using the Web Services interface over the .NET API:
Performance
Many of the operations are more coarse-grained than those of the .NET API but are written to be executed efficiently. In some cases, the Web Service implementations can out-perform the use of the .NET API by several times.
In addition you can more easily make use of multiple levels of caching using the Web Services in an n-tier application.
Ease Of Deployment
None of the TMCore libraries are required to access the Web Services (although you can make use of our web services client library in your .NET applications). This makes it much easier to distribute your applications across multiple machines.
Portability
The Web Services interfaces support both simple HTTP GET and POST requests and SOAP. This makes it possible to write applications to access and update TMCore data from any language that provides libraries for SOAP or HTTP interactions - Perl, Ruby, Python and even Javascript can all be used to access the topic map via the Web Services interface.
A small set of XML schemas define the input and output data structures for all of our web services. There are 6 main schemas and all of these schemas are described in detail in the Appendix to this document.
The Topic Map Fragment Schema represents topics and associations from a topic map. It is used both to retrieve information from the topic map and to update the topic map.
The Hierarchy Schema is used to retrieve information about hierarchies contained in a topic map.
The Topic Map Transaction Schema is used to update the topic map. It allows updates to several topics or associations to be made in a single transaction.
The NPCL Schema is used to retrieve the Networked Planet Constraint Language (NPCL) schema from a topic map.
The NPCL Forms Schema presents the Networked Planet Constraint Language schema for a topic map along with some additional information which makes it easy to create your own constrained editing front-ends, such as an HTML form for entering a new topic of a particular type.
The Results Schema is used to convey the results of Web Service operations.
This document describes all of the web services provided by TMCore. The first part of this document provides an overview of how the TMCore web services are described in the rest of the document and how that description maps to the actual SOAP and HTTP implementations. There then follows sections describing each of the services provided by TMCore. Currently TMCore provides two separate services, the Topic Map Web Service which provides basic query, browse and update methods and the NPCL Web Service which provides access to the NPCL schema information for a topic map. Finally, the appendix of this document provide a detailed description of each of the XML schemas used by the services.
TMCore provides several separate web services. Each of these services expose a number of methods which can be invoked either by a SOAP client or by simple HTTP page requests (e.g. using the AJAX architecture).
Rather than redundantly repeat a lot of information for both the SOAP and HTTP interfaces, we present each web service described in terms of the operation it performs, the parameters or XML document expected on the input and the XML document generated on the output. All of these factors are the same for both interface types.
The following sections provide an introduction to the description of the web services APIs and details on how the API descriptions presented later map into SOAP or HTTP requests and responses.
Each API is described as a list of methods. Each method description has the following sections:
This section specifies the name of the operation. For the
SOAP implementation, this is the SOAP operation name. For the
ASP.NET implementation, the operation name is the name of the
ASP.NET page that implements that operation. When invoking the
operation on the ASP.NET implementation, the request should be
made to an address constructed by concatenating the base URL of
the service, a forward slash, the operation name and string
".aspx". For example, if you have the Topic Map Web Service
installed on your local machine at
http://localhost/tmws, then the URL for the
GetTopicMaps operation is
http://localhost/tmws/GetTopicMaps.aspx.
This section lists the input parameters for the operation. All parameters are assumed to be REQUIRED unless they are explicitly flagged with as OPTIONAL. All parameter are assumed to be string literals, unless the parameter description specifies a different type.
For a SOAP invocation, each parameter maps to an element in the SOAP input message for the operation where the element name is the same as the parameter name.
For an ASP.NET implementation, the mapping of parameters depends upon how the operation is invoked. All ASP.NET implementations support both invocation using an HTTP GET and invocation using an HTTP POST. When invoking the operation using an HTTP GET, each parameter should be provided as a query parameter in the URL. When invoking the message using an HTTP POST, the body of the POST request must contain only an XML document. The XML document POSTed to the ASP.NET page must use the following syntax:
<request> <param name="PARAMETER NAME"> VALUE </param> </request>
The request element is the outer wrapper
for the request parameters. Each parameter is specified using a
param element. The name
attribute of the param element is required and
must be set to the name of the parameter whose value is specified.
The content of the param element must be the
parameter value. The param element may contain
an XML fragment if allowed by the parameter type.
Example 1. POST Invocation Examples
The following examples relate to invocation of methods exposed by the NetworkedPlanet Topic Map Web Service.
To invoke a method that takes no parameters, post an empty requets element. For example to invoke the GetTopicMaps operation you could post the following content to the GetTopicMaps.aspx page:
<request />
To invoke the GetTopicBySubjectIdentifier operation to get the topic with the subject identifier http://www.example.com/mypsi/ in the topic map named 'mytopicmap', post the following content to the GetTopicBySubjectIdentifier.aspx page:
<request> <param name="topicmap">mytopicmap</param> <param name="locator">http://www.example.com/mypsi/</param> </request>
To invoke the Save operation to update a topic in the topic map 'mytopicmap', post the following content to the Save.aspx page (the full content of the tmfragment parameter is ommitted for brevity):
<request>
<param name="topicmap">mytopicmap</param>
<param name="tmfragment">
<topicmap xmlns="http://www.networkedplanet.com/2005/01/topicmap/data/">
...
</topicmap>
</param>
</request>A few operations take an array of strings as a parameter.
To make these requests, simply wrap each separate string
parameter in its own param element. For
example to delete two topics from a topic map (an operation
which takes an array of topic object identifiers in the
parameter named "oids"), post the following content to the
DeleteTopics.aspx page:
<request> <param name="topicmap">mytopicmap</param> <param name="oids">1234</param> <param name="oids">5678</param> </request>
A request element can contain its
param elements in any order - you do not
have to match the order in which the parameters are
specified on an operation and you can mix lists of values
for string array parameters in with other parameter
specifications.
The Returns section describes what results are returned by the operation if it is successful, and how those results are represented. The return result from any operation is always an XML document. For operations that only update the topic map (and do not request information from it), the SOAP response body content may differ from the HTTP interface response body, in that a successful SOAP operation simply returns an empty response body (using the normal SOAP headers to indicate success) whereas the HTTP interface will always return an XML document in the response body as well as an HTTP status code indicating success.
The Errors section list operation-specific error conditions. Each error condition is described in a table that shows the error code, the condition under which the error is raised and the structure of any error-specific details.
For a SOAP implementation of an operation, an error is notified to the caller as a SOAP fault. The fault element will contain a faultstring value which contains an error message, and a faultdetail element which will contain the full error description XML document as described below.
For an ASP.NET implementation, successes or failed execution of an operation will be indicated using HTTP status codes.
| 200 (OK) for completely successful operations. |
| 403 (Bad Request) for failed or partially successful operations, where failures occurred due to bad input being supplied by the user. |
| 500 (Internal Server Error) for failed or partially successful operation, where failures occurred due to circumstances outside of the users control. |
For invocations which require multiple operations to be executed (for example passing multiple topic IDs to DeleteTopics), if any of the operations fail then an error status code will be returned. The caller must check the body of the response which will either be the XML document described in the Returns section, or will be an error description XML document as described below to determine which parts of the operation succeeded.
All of the HTTP web services can be invoked using an HTTP POST with the POST request body containing a request XML as described in the section above. The request document should be POSTed to the .aspx page that implements the operation. The requester should check the status and content of the HTTP response received. A 200 OK status code indicates that the request was successfully processed.
Example 2. Calling HTTP Web Services From C#
The listing below shows an example of invoking a web serivce
over HTTP from within a C# program. Note that the GetResponse()
method has been written to be generic and can be used to access any
of the NetworkedPlanet web service operations. A complete working
program based on this example code can be found in the
examples/CS directory of your
installation.
private void ProcessRequest(string serviceApplicationUrl, string topicmapName, string searchString)
{
// First construct the URL. We start with the path to the application
// directory provided by the user. Expand this by adding the operation
// ASPX page address (with a slash separator if needed).
string requestUrl = serviceApplicationUrl;
if (!requestUrl.EndsWith("/"))
{
requestUrl += "/";
}
requestUrl += "GetTopicsByName.aspx";
Hashtable parameters = new Hashtable();
parameters["topicmap"] = topicmapName;
parameters["name"] = searchString;
XmlDocument responseDoc = new XmlDocument();
try
{
HttpStatusCode statusCode = GetResponse(requestUrl, parameters, responseDoc);
if (statusCode == HttpStatusCode.OK)
{
System.Console.WriteLine("Search request was processed successfully. Results follow.");
}
else
{
System.Console.WriteLine("Search request failed: " + statusCode.ToString() + ". Details follow.");
}
XmlTextWriter writer = new XmlTextWriter(System.Console.Out);
writer.Formatting = Formatting.Indented;
responseDoc.WriteTo(writer);
}
catch (System.Net.WebException webex)
{
System.Console.Error.WriteLine("Error encountered in sending request. Please check the service application URL and try again.");
System.Console.Error.WriteLine(" Error detail: " + webex.Message);
}
}
/// <summary>
/// Attempts to contact a NetworkedPlanet webservice, passing in the specified parameters.
/// </summary>
/// <param name="requestUrl">The URL of the service to contact</param>
/// <param name="parameters">The parameters to pass to the service.</param>
/// <param name="responseDoc">The response XML received from the web service</param>
/// <returns>The HTTP status code of the response</returns>
/// <exception cref="System.Net.WebException">Raised if the service could not be reached.</exception>
/// <remarks>The <c>parameters</c> hashtable must use string keys and the value for each key must be either
/// a string or an IList of string.</remarks>
private HttpStatusCode GetResponse(string requestUrl, Hashtable parameters, XmlDocument responseDoc)
{
// Construct the request XML
XmlDocument requestDoc = new XmlDocument();
XmlElement requestEl = requestDoc.CreateElement("request");
requestDoc.AppendChild(requestEl);
// Parameters should be either strings or lists of strings
foreach(string key in parameters.Keys)
{
if (parameters[key] is string)
{
XmlElement param = requestDoc.CreateElement("param");
param.SetAttribute("name", key);
param.InnerXml = parameters[key] as string;
requestEl.AppendChild(param);
}
else if (parameters[key] is IList)
{
// If the parameter is a list of strings, write a separate
// param element for each item in the list.
foreach(string item in (parameters[key] as IList))
{
XmlElement param = requestDoc.CreateElement("param");
param.SetAttribute("name", "key");
param.InnerXml = item;
requestEl.AppendChild(param);
}
}
}
// Perform an ASCII encoding of the request xml
ASCIIEncoding encoding = new ASCIIEncoding();
byte[] encodedBody = encoding.GetBytes(requestDoc.OuterXml);
// Construct the request object
HttpWebRequest webRequest = HttpWebRequest.Create(requestUrl) as HttpWebRequest;
webRequest.ContentType = "text/xml";
webRequest.ContentLength = encodedBody.Length;
webRequest.Method = "POST";
Stream bodyStream = webRequest.GetRequestStream();
bodyStream.Write(encodedBody, 0, encodedBody.Length);
bodyStream.Close();
HttpWebResponse webResponse = null;
try
{
webResponse = webRequest.GetResponse() as HttpWebResponse;
}
catch (System.Net.WebException webEx)
{
webResponse = webEx.Response as HttpWebResponse;
}
// NOTE: this will throw an exception out to the caller if the
// response is not an XML document.
responseDoc.Load(webResponse.GetResponseStream());
return webResponse.StatusCode;
}Example 3. Calling HTTP Web Services From VB.NET
' Contains the logic for issuing a search request and processing
' the results.
Sub DoRequest(ByVal serviceUrl As String, ByVal topicmapName As String, ByVal searchString As String)
Dim requestUrl As String
requestUrl = serviceUrl
If Not (requestUrl.EndsWith("/")) Then
requestUrl = requestUrl + "/"
End If
requestUrl = requestUrl + "GetTopicsByName.aspx"
System.Console.WriteLine(requestUrl)
Dim params As New Hashtable
params("topicmap") = topicmapName
params("name") = searchString
Dim responseDoc As New Xml.XmlDocument
Dim responseCode As HttpStatusCode
Try
responseCode = GetResponse(requestUrl, params, responseDoc)
If (responseCode.Equals(HttpStatusCode.OK)) Then
System.Console.WriteLine("Search process successfully. Results follow:")
Else
System.Console.WriteLine("Search request failed. Error details follow:")
End If
Dim writer As XmlTextWriter
writer = New XmlTextWriter(System.Console.Out)
writer.Formatting = Formatting.Indented
responseDoc.WriteTo(writer)
Catch ex As WebException
System.Console.Error.WriteLine("Error processing request: " + ex.Message)
System.Console.Error.WriteLine(" Please check the service URL and try again.")
End Try
End Sub
' Performs the "heavy lifing" of the application. This function posts
' a set of parameters (defined in the params Hashtable) to the
' URL specified by requestUrl and parses the response into
' responseDoc. Because all of the NetworkedPlanet web service
' operations use the same request format, this method can
' be reused to invoke any of the operations we support.
' The keys in the params Hashtable must be strings and the
' values must be either strings or ILists of strings.
Function GetResponse(ByVal requestUrl As String, ByVal params As Hashtable, ByVal responseDoc As XmlDocument) As HttpStatusCode
Dim requestDoc As XmlDocument
Dim requestEl As XmlElement
Dim paramEl As XmlElement
Dim key As String
requestDoc = New XmlDocument
requestEl = requestDoc.CreateElement("request")
requestDoc.AppendChild(requestEl)
For Each key In params.Keys
If (TypeOf params(key) Is IList) Then
' Extract each item in the list in turn add add
' a separate param element for it
Dim paramValue As String
For Each paramValue In params(key)
paramEl = requestDoc.CreateElement("param")
paramEl.SetAttribute("name", key)
paramEl.InnerXml = paramValue
requestEl.AppendChild(paramEl)
Next
Else
' Create a single param element for the item value
paramEl = requestDoc.CreateElement("param")
paramEl.SetAttribute("name", key)
paramEl.InnerXml = params(key)
requestEl.AppendChild(paramEl)
End If
Next
System.Console.WriteLine(requestDoc.OuterXml)
Dim encodedBody As Byte()
Dim asciiEncoding As New ASCIIEncoding
encodedBody = asciiEncoding.GetBytes(requestDoc.OuterXml)
Dim httpRequest As HttpWebRequest
httpRequest = HttpWebRequest.Create(requestUrl)
httpRequest.Method = "POST"
httpRequest.ContentLength = encodedBody.Length
httpRequest.ContentType = "text/xml"
Dim requestStream As Stream
requestStream = httpRequest.GetRequestStream()
requestStream.Write(encodedBody, 0, encodedBody.Length)
requestStream.Close()
Dim httpResponse As HttpWebResponse
Try
httpResponse = httpRequest.GetResponse()
Catch ex As WebException
httpResponse = ex.Response
End Try
If httpResponse.ContentType = "text/xml" Then
Dim reader As New XmlTextReader(httpResponse.GetResponseStream())
responseDoc.Load(reader)
Else
' We shouldn't get non XML content return from NetworkedPlanet
' requests, but this handles the case that the server returns s
' some default error page (e.g. if access is denied) by embedding
' the response text inside a wrapper element
responseDoc.AppendChild(responseDoc.CreateElement("NonXmlResponse"))
Dim rdr As New StreamReader(httpResponse.GetResponseStream())
responseDoc.InnerText = rdr.ReadToEnd()
rdr.Close()
End If
Return httpResponse.StatusCode
End Function
Example 4. Calling HTTP Web Services From Javascript
The following example shows the use of the XmlHttpRequest object provided by some browsers. There are a number of cross-browser libraries that help you avoid browser issues in using Javascript.
/**
* Construct and post the request and handle the response
*/
function DoSearch()
{
// Assumes that our page has three text fields for providing the request parameters
oServiceUrl = document.getElementById("serviceUrl")
oTopicmap = document.getElementById("topicmap")
oSearchString = document.getElementById("searchString")
// A placeholder element on our page for progress / result messages
oMessage = document.getElementById("message");
szRequestUrl = oServiceUrl.value
if (szRequestUrl.charAt(szRequestUrl.length - 1) != "/") {
szRequestUrl = szRequestUrl + "/"
}
szRequestUrl = szRequestUrl + "GetTopicsByName.aspx"
szRequestBody = "<request><param name='topicmap'>" + oTopicmap.value +
"</param><param name='name'>" + oSearchString.value + "</param></request>"
oMessage.innerText = "Sending request. Please wait...";
oMessage.className = "pending";
DoPost(szRequestUrl, szRequestBody);
}
/**
* Posts the specified content to the specified URL using
* the global asynchronous request object 'req'. When the
* request status changes, the ProcessRequestChange function
* will be invoked
*/
function DoPost(url, content)
{
if (window.XMLHttpRequest) {
req = new XMLHttpRequest();
req.onreadystatechange = ProcessRequestChange;
req.open("POST", url, true);
req.send(content);
} else if (window.ActiveXObject) {
req = new ActiveXObject("Microsoft.XMLHTTP");
if (req) {
req.onreadystatechange = ProcessRequestChange;
req.open("POST", url, true);
req.send(content);
}
}
}
function ProcessRequestChange()
{
if (req.readyState == 4) {
if (req.status == 200) {
// Handle successful response.
// Response XML can be found in req.responseXML
} else {
// Handle error reponse.
// Error XML document can be found in req.responseXML
}
}
}Although the HTTP interface also accepts HTTP GET requests, these are restricted by the limitations imposed on URL lenght and URL parameter structures. We therefore recommend that you always use POST requests for consistency.
The SOAP service implementation endpoints are provided by the .asmx files contained in the service web applications. This is TMService.asmx for the Topic Maps Web Service and NpclSchemaService.asmx for the NPCL Web Service. These endpoints provide a WSDL description if you invoke an HTTP GET on them with a single parameter "wsdl" - e.g. http://localhost/tmws/TMService.asmx?wsdl.
From the WSDL file you can generate the client-side proxy for accessing the web service. In .NET this is done using the wsdl.exe tool. For your convenience we have provided a .NET assembly, serviceclient.dll. This assembly contains client stubs for the Topic Maps Web Service and NPCL Web Service as well as classes for creating and serializing / de-serializing the XML structures that are used as parameters and return values for the web service operations.
The following code shows a method that invokes the
GetTopicsByName operation on the Topic Maps Web Service and
processes the response. The sample code shown here uses the
utilities provided by the serviceclient.dll assembly. The full code
for this example can be found in
examples/CS/WebServices/TopicsByNameSOAP. As
the code below shows, the response from the web service can be
deserialized into the appropriate class from the
NetworkedPlanet.WebServiceClient.Tmws namespace (for TMWS
operations) or NetworkedPlanet.WebServiceClient.Npcl namespace (for
NPCL Web Service operations) - there are also a set of common
structures for reporting lists of results and/or errors in the
NetworkedPlanet.WebServiceClient.Common namespace.
Example 5. Calling SOAP Web Services From C#
using System;
using System.Web.Services.Protocols;
using System.Xml;
using System.Xml.Serialization;
using NetworkedPlanet.WebServiceClient;
using NetworkedPlanet.WebServiceClient.Tmws;
using NetworkedPlanet.WebServiceClient.Common;
private static void ProcessRequest(string endpointUrl, string tmName, string queryString)
{
// Create a new TMWS SOAP client bound to the specified endpoint.
TMSClient tmwsClient = new TMSClient(endpointUrl);
try
{
XmlNode results = tmwsClient.GetTopicsByName(tmName, queryString);
XmlSerializer ser = new XmlSerializer(typeof(TopicMapFragment));
TopicMapFragment resultsFragment = ser.Deserialize(new XmlNodeReader(results)) as TopicMapFragment;
foreach(Topic t in resultsFragment.topiclist)
{
if (!t.stub)
{
System.Console.WriteLine("Topic {0}: {1}", t.oid, t.names[0].namestring);
}
}
}
catch (SoapException ex)
{
if (ex.Detail != null)
{
// SoapExceptions from TMWS will usually contain an XML fragment with a detailed description of the error
// If the SoapException was raised due to a TMWS error, the SOAP detail element will contain
// results structure which can be deserialized to extract information.
XmlNamespaceManager nsmgr = new XmlNamespaceManager(ex.Detail.OwnerDocument.NameTable);
nsmgr.AddNamespace("res", "http://www.networkedplanet.com/schema/ws-results");
XmlElement resultsEl = ex.Detail.SelectSingleNode("res:results", nsmgr) as XmlElement;
if (resultsEl != null)
{
// We have a results element which can be deserialized to an
// instance of the NetworkedPlanet.WebServiceClient.Common.ResultListType class
XmlSerializer ser = new XmlSerializer(typeof(ResultListType));
ResultListType resultList = ser.Deserialize(new XmlNodeReader(resultsEl)) as ResultListType;
foreach(ResultType result in resultList.result)
{
if (result.isError && result.error != null)
{
System.Console.Error.WriteLine("\nError: {0}\n {1}", result.error.code, result.error.message);
if (result.error.cause != null)
{
foreach(CSharpException cause in result.error.cause)
{
System.Console.WriteLine(" Cause: {0}", cause.message);
}
}
if (result.error.action != null)
{
foreach(Action action in result.error.action)
{
System.Console.Error.WriteLine(" Corrective Action: {0}", action.Value);
}
}
}
}
}
else
{
// Just display the contents of the SOAP fault details element.
System.Console.Error.WriteLine("Error detail:\r\n" + ex.Detail.OuterXml);
}
}
}
}The following code shows a method that invokes the
GetTopicsByName operation on the Topic Maps
Web Service and processes the response. The sample code shown here
uses the utilities provided by the serviceclient.dll assembly. The
full code for this example can be found in
examples/VB/WebServices/TopicsByNameSOAP. As
the code below shows, the response from the web service can be
deserialized into the appropriate class from the
NetworkedPlanet.WebServiceClient.Tmws namespace (for TMWS
operations) or NetworkedPlanet.WebServiceClient.Npcl namespace (for
NPCL Web Service operations) - there are also a set of common
structures for reporting lists of results and/or errors in the
NetworkedPlanet.WebServiceClient.Common namespace.
Example 6. Calling SOAP Web Services from VB
Imports System.Xml
Imports System.Web.Services.Protocols
Imports NetworkedPlanet.WebServiceClient
Imports NetworkedPlanet.WebServiceClient.Tmws
Imports NetworkedPlanet.WebServiceClient.Common
...
Sub DoRequest(ByVal endpointUrl As String, ByVal tmName As String, ByVal queryString As String)
Dim tmwsClient As New TMSClient(endpointUrl)
Try
Dim responseXml As XmlNode
responseXml = tmwsClient.GetTopicsByName(tmName, queryString)
Dim ser As System.Xml.Serialization.XmlSerializer
ser = New System.Xml.Serialization.XmlSerializer(GetType(TopicMapFragment))
Dim results As TopicMapFragment
results = ser.Deserialize(New XmlNodeReader(responseXml))
Dim t As Topic
For Each t In results.topiclist
If (Not t.stub) Then
System.Console.WriteLine("Topic {0} : {1}", t.oid, t.names(0).namestring)
End If
Next
Catch ex As SoapException
If Not (ex.Detail Is Nothing) Then
Dim nsmgr As XmlNamespaceManager = New XmlNamespaceManager(ex.Detail.OwnerDocument.NameTable)
nsmgr.AddNamespace("res", "http://www.networkedplanet.com/schema/ws-results")
Dim resultsEl As XmlElement = ex.Detail.SelectSingleNode("res:results", nsmgr)
If Not (resultsEl Is Nothing) Then
Dim ser As System.Xml.Serialization.XmlSerializer = New System.Xml.Serialization.XmlSerializer(GetType(ResultListType))
Dim results As ResultListType = ser.Deserialize(New XmlNodeReader(resultsEl))
Dim result As ResultType
For Each result In results.result
If result.isError Then
System.Console.Error.WriteLine("ERROR: {0}", result.error.code)
System.Console.Error.WriteLine(" {0}", result.error.message)
If Not (result.error.cause Is Nothing) Then
Dim cause As CSharpException
For Each cause In result.error.cause
System.Console.Error.WriteLine(" Cause: {0}", cause.message)
Next
End If
If Not (result.error.action Is Nothing) Then
Dim action As Action
For Each action In result.error.action
System.Console.Error.WriteLine(" Corrective Action: {0}", action.Value)
Next
End If
End If
Next
Return
End If
End If
System.Console.Error.WriteLine("Error Detail: {0}", ex.Detail.OuterXml)
End Try
End SubThis section provides an overview of the NetworkedPlanet Topic Map Web Service. This service can be accessed both via a SOAP web service and by using HTTP GET/POST interfaces which allow connectivity from AJAX applications. This section starts with an overview of the operations that the Web Service provide, described in terms of their input parameters, processing and output.
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.
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>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.
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.
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.
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.
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.
Specifies the name of the attribute. The name must conform to standard SQL parameter name syntax. This attribute is REQUIRED.
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>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>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.
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".
This attribute specifies the short-code for the subject identifier URI. This attribute is REQUIRED.
This attribute specifies the subject identifier URI that the short-code is mapped to. This attribute is REQUIRED.
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.
This attribute specifies the short-code for the identifier prefix. This attribute is REQUIRED.
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".
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.
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>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.
In the following service description a number of different XML schema are used. The table below lists the namespace prefixes used in the descriptions, the namespace they map to and a reference to the schema description. Other namespace and namespace prefix mappings are defined where they occur in the service description.
Table 1. Namespaces Used In This Document
| Prefix | Namespace URI | Reference |
|---|---|---|
| frag | http://www.networkedplanet.com/2005/01/topicmap/data/ | the section called “Topic Map Fragment XML Schema” |
| res | http://www.networkedplanet.com/schema/ws-results | the section called “Results Description Document Schema” |
| tmh | http://www.networkedplanet.com/2005/01/topicmap/patterns/hierarchy/ | the section called “Hierarchy XML Schema” |
| tmws | http://www.networkedplanet.com/2005/01/webservices/tmservice/ | Described as required under the service operations contained in this section. |
Any of the service operations described in the following section may raise one of the following errors in addition to any operation-specific errors.
| Error Code | Condition |
|---|---|
| UNEXPECTED_EXCEPTION | An unexpected error occurred whilst processing the request against a specific topic map. The error message will identify the topicmap being accessed. The message and nested action elements will help you identify the cause of the error. |
| INTERNAL_ERROR | An unexpected internal error prevent has occurred on the server. The error message and nested action elements will help you (or your systems administrator) identify the cause of the error. |
This section describes the methods supported by the Topic Map Web Service.
Removes one or more associations from the specified topic map. The associations to be deleted are identified by their unique object identifiers.
The name of the topic map to delete the associations from. This parameter is a single string.
The unique object identifiers of the associations to be deleted. This parameter is an array of strings.
This method returns an XML document conforming to the Web
Service Results schema with a root element of type
res:results which contains one
res:result element for each association OID
specified in the request. The key attribute of
each res:result element specifies the OID of the
association that was deleted.
This structure is returned as long as the
topicmap parameter is valid. Any error that
occurs on the deletion of an individual association will be
reported in the res:result element for that
association.
Each res:result element that reports an
error may contain a res:error element that uses
one of the following codes:
| Error Code | Condition |
|---|---|
| INVALID_OID | The object identifier provided for the association is
not valid or is not an OID of an association contained in
the topic map identified by the
topicmap parameter. |
| DELETE_ASSOCIATION_FAILED | One of the associations specified for deletion could not be removed from the topic map. The error key will specify the OID of the association which could not be deleted. The message and nested action elements will help you identify the cause of the failure. |
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
Example 9. HTTP Interface Request XML for DeleteAssociations Operation
The following example shows an XML request that can be sent using an HTTP POST to the DeleteAssociations.aspx operation page.
<request> <param name="topicmap">mytopicmap</param> <param name="oids">1234</param> <param name="oids">5678</param> </request>
Example 10. C# Code Using the Web Services Client Library to Invoke the DeleteAssociations Operation
The following example shows how to delete associations using the Web Services Client library.
TMSClient client = new TMSClient("http://topicmap.mycorp.com/tmws/TMService.asmx");
XmlNode results = client.DeleteAssociations("mytopicmap", new string[] {"1234", "5678"});Removes one or more topics from the specified topic map. The topics to be deleted are identified by their unique object identifiers.
The name of the topic map to delete topics from.
The unique object identifiers of the topics to be deleted. This parameter is an array of strings.
Returns an XML document conforming to the Web Service Results
schema with a root element of type res:results
which contains one res:result element for each
topic OID specified in the request. The key attribute of each
res:result element specifies the OID of the topic
to be deleted.
This structure is returned as long as the
topicmap parameter is valid. Any error that
occurs on the deletion of an individual topic will be reported in
the res:result element for that topic.
Each res:result element that reports an
error may contain a res:error element that uses
one of the following codes:
| Error Code | Condition |
|---|---|
| INVALID_OID | The object identifier provided for the topic is not
valid or is not an OID of a topic contained in the topic map
identified by the topicmap
parameter. |
| DELETE_TOPIC_FAILED | One of the topics specified for deletion could not be removed from the topic map. The error key will specify the OID of the topic which could not be deleted. The message and nested action elements will help you identify the cause of the failure. |
| TOPIC_IN_USE | The topic could not be deleted because it is referenced from elsewhere in the topic map as a type, a scoping topic or plays a role in one or more associations. The error key specifies the OID of the topic that could not be deleted. |
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
Example 11. HTTP Interface Request XML for DeleteTopics Operation
The following request XML can be POSTed to the DeleteTopics.aspx page to request the deletion of two topics from the topic map.
<request> <param name="topicmap">mytopicmap</param> <param name="oids">1234</param> <param name="oids">5678</param> </request>
Example 12. C# Code Using the Web Services Client to Invoke the DeleteTopics Operation
The following code snippet shows how to delete two topics from a topic map using the Web Services Client library:
TMSClient client = new TMSClient("http://topicmap.mycorp.com/tmws/TMService.asmx");
XmlNode results = client.DeleteTopics("mytopicmap", new string[] {"1234", "5678"});Retrieves an XML document describing a single hierarchy present in the topic map. The hierarchy to be retrieved is identified by the unique object identifier of the topic that defines the hierarchy.
The name of the topic map to retrieve the specified hierarchy from.
The object identifier of the topic that defines the hierarchy to be retrieved.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
| INVALID_OID | The value of the
hierarchydefid parameter was not a
valid object identifier or was not the identifier of a topic
contained in the topic map identified by the
topicmap parameter. |
| NOT_A_HIERARCHY | The topic identified by
hierarchydefid does not define a
hierarchy in the topic map. |
Example 13. HTTP POST Body to Invoke the GetHierarchy Operation
<request> <param name="topicmap">mytopicmap</param> <param name="hierarchydefid">1234</param> </request>
Returns an XML document describing all of the hierarchies present in the topic map. For each hierarchy, the returned document provides the unique object identifier of the topic that defines the hierarchy and the topic that is the root topic of the hierarchy.
An XML document describing each of the hierarchies contained
in the specified topic map. The document conforms to the
NetworkedPlanet Hierarchy XML Schema with the
tmh:treelist element as its root element.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
Returns a topic map fragment that includes the topic map object
with the specified source locator. If the object is a topic,
occurrence, topic name, or variant name then the returned fragment
will contain at least a topiclist element
containing the topic that contains that object. If the object is an
association or association role, then the returned fragment will
contain at least an associationlist element that
contains the object.
The name of the topic map to search.
The source locator URI of the object to be returned.
An XML document conforming to the NetworkedPlanet Topic Map
Fragment XML Schema. The object found by the query will be contained
in the topic map fragment. If the object requested was a topic, it
will be present as a frag:topic element inside
the frag:topiclist element. If the object was an
occurrence, topic name or variant name, the entire topic that
contains that object will be present as a
frag:topic element inside the
frag:topiclist element. If the object was an
association, it will be present as a
frag:association element inside the
frag:associationlist element. If the object was
an association role, the entire association that contains the object
will be present as a frag:association element
inside the frag:associationlist element. If the
result requires the generation of a frag:topic
element, that topic will be fully serialized and any topics that it
references will be serialized as stubs.
If no object was found in the topic map with the specified
source locator, this method will return an empty
frag:topicmap element.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
Example 19. HTTP POST Body to Invoke the GetObjectBySourceLocator Operation
The following example could be used in the body of an HTTP POST request to the GetObjectBySourceLocator.aspx request page.
<request> <param name="topicmap">mytopicmap</param> <param name="sourcelocator">http://www.example.com/topicmaps/foo.xtm#bar</param> </request>
Example 20. HTTP GET URL to Invoke the GetObjectBySourceLocator Operation
The following example shows how to invoke the GetObjectBySourceLocator operation using an HTTP GET. Note that the source locator value should be properly escaped within the URL string.
http://topicmap.mycorp.com/tmws/GetObjectBySourceLocator.aspx?topicmap=mytopicmap&sourcelocator=http%3a%2f%2f...
Example 21. C# Code to Invoke the GetObjectBySourceLocator Operation using the Web Services Client Library
TMSClient client = new TMSClient("http://topicmap.mycorp.com/tmws/TMService.asmx");
XmlNode tmFragment = client.GetObjectBySourceLocator("mytopicmap", "http://www.example.com/topicmaps/foo.xtm#bar");Returns a topic map fragment that includes the specified topic. The topic is identified by its unique object identifier.
The name of the topic map to be searched for the requested topic.
The OID of the topic to be returned.
An XML document conforming to the NetworkedPlanet Topic Map
Fragment XML Schema. The root element will be the
frag:topicmap element. This fragment will contain
a frag:topiclist which contains the requested
topic fully serialized and any topics that it references serialized
as stub topics. If no topic is found with the specified OID in the
specified topic map, then this method will return an empty
frag:topicmap element.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
| INVALID_OID | The value of the topicid
parameter could not be parsed as a valid topic object
identifier. |
Example 22. HTTP POST Body to Invoke the GetTopic Operation
The following example could be used in the body of an HTTP POST request to the GetTopic.aspx request page.
<request> <param name="topicmap">mytopicmap</param> <param name="topicid">1234</param> </request>
Returns a topic map fragment that includes the topic with the specified subject identifier.
The name of the topic map to be searched.
The subject identifier of the topic to be returned.
An XML document conforming to the NetworkedPlanet Topic Map
Fragment XML Schema. This fragment will contain a
frag:topiclist which contains the requested topic
fully serialized and any topics that it references serialized as
stub topics. If no topics have the specified subject identifier, an
empty frag:topicmap element will be
returned.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
Example 25. HTTP POST Body to Invoke the GetTopicBySubjectIdentifier Operation
The following example could be used in the body of an HTTP POST request to the GetTopicBySubjectIdentifier.aspx request page.
<request> <param name="topicmap">mytopicmap</param> <param name="locator">http://psi.example.com/companies/MSFT</param> </request>
Example 26. HTTP GET URL to Invoke the GetTopicBySubjectIdentifier Operation
The following example shows how to invoke the GetTopicBySubjectIdentifier operation using an HTTP GET. Note that the subject identifier value should be properly escaped within the URL string.
http://topicmap.mycorp.com/tmws/GetTopicBySubjectIdentifier?topicmap=mytopicmap&locator=http%3a%2f%2f...
Example 27. C# Code to Invoke the GetTopicBySubjectIdentifier Operation using the Web Services Client Library
TMSClient client = new TMSClient("http://topicmap.mycorp.com/tmws/TMService.asmx");
XmlNode tmFragment = client.GetTopicBySubjectIdentifier("mytopicmap", "http://psi.example.com/companies/MSFT");Returns an XML document that describes all of the topic maps managed by the TMCore server.
An XML document conforming to the NetworkedPlanet Topic Map
Fragment XML Schema. The root element of this document will be the
frag:topicmapsystem element.
Example 28. HTTP POST Body to Invoke the GetTopicMaps Operation
The following example could be used in the body of an HTTP POST request to the GetTopicMaps request page.
<request />
Returns a topic map fragment that includes every topic with a specified name.
An XML document conforming to the NetworkedPlanet Topic Map
Fragment XML Schema. This fragment will contain a
frag:topiclist which contains each of the topics
that have at least one name that matches the name parameter. These
topics will all be fully serialized. All of the topics referenced by
the fully serialized topics which are not themselves full serialized
will be included in the frag:topiclist returned
as stub topics. If no topics are found with a name that matches the
name parameter, then an empty frag:topicmap
element will be returned.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
Example 31. HTTP POST Body to Invoke the GetTopicsByName Operation
The following example could be used in the body of an HTTP POST request to the GetTopicsByName.aspx request page.
<request> <param name="topicmap">mytopicmap</param> <param name="name">NetworkedPlanet</param> </request>
Example 32. HTTP GET URL to Invoke the GetObjectBySourceLocator Operation
The following example shows how to invoke the GetObjectBySourceLocator operation using an HTTP GET. Note that the name value should be properly escaped within the URL string if it contains reserved or non-ASCII characters.
http://topicmap.mycorp.com/tmws/GetTopicsByName?topicmap=mytopicmap&name=NetworkedPlanet
Returns a topic map fragment that includes all topics of a specified type. The topic type is identified by its unique object identifier.
The name of the topic map to search
The object identifier of the topic type to return all instances for.
An XML document conforming to the NetworkedPlanet Topic Map
Fragment XML Schema. The root element of this document will be a
frag:topicmap element and will contain a
frag:topiclist element which in turn contains a
frag:topic element for each topic that is typed
by the topic identified by the typeid
parameter. The instance topics will all be serialized as stub
topics. If no topics are typed by the specified type, then the
frag:topicmap element returned will be
empty.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
| INVALID_OID | The value of the typeid
parameter could not be converted to a valid object
identifier. |
| NO_SUCH_OBJECT | The value of the typeid
parameter was converted to a valid object identifier, but
that identifier does not refer to a topic contained in the
topic map identified by the topicmap
parameter. |
Example 34. HTTP POST Body to Invoke the GetTopicsByType Operation
The following example could be used in the body of an HTTP POST request to the GetTopicsByType.aspx request page.
<request> <param name="topicmap">mytopicmap</param> <param name="typeid">1234</param> </request>
Returns a topic map fragment that includes all topics which are used as the type of one or more other topics in the specified topic map.
This operation returns a list of all topics which are currently used to type other topics in the topic map and is thus based on actual usage rather than on a pre-defined topic map schema. This list may therefore differ from the list of types returned by the NPCL Schema Web Service.
An XML document conforming to the NetworkedPlanet Topic Map
Fragment XML Schema. The root element of this document will be a
frag:topicmap element and will contain a
frag:topiclist element which in turn contains a
frag:topic element for each topic that is used as
the type of one or more topics in then topic map. All of these
topics will be fully serialized. Any topics which are referred to by
the type topics will also be included in the
frag:topiclist element but will be serialized as
stubs.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
Example 37. HTTP POST Body to Invoke the GetTopicTypes Operation
The following example could be used in the body of an HTTP POST request to the GetTopicTypes.aspx request page.
<request> <param name="topicmap">mytopicmap</param> </request>
Executes a named query, optionally with one or more parameters. The query string is configured on the server. The results are returned as an XML document describing a results table.
The name of the topic map to execute the query against.
The string identifier of the query to be executed.
The arguments to be passed in to the query before it is executed. Arguments are specified using the following XML structure:
<tmws:args>
<tmws:string>
ARG
</tmws:string>
</tmws:args>The wrapper for the arguments to be passed in to the query.
Contains a single argument value to pass in to the query. Arguments are passed by position and are bound to the parameters in the named query configuration in the order that the parameters are declared, so the ordering of tmws:string elements is important. This element is OPTIONAL and REPEATABLE.
An XML representation of the data set returned by executing
the query. This data set uses the normal XML syntax for ADO.NET data
sets and the XML namespace
http://www.networkedplanet.com/2005/01/topicmap/querydata/
.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
| INVALID_QUERY_ID | There is no query on the server with the identifier
specified in the queryid
parameter. |
| MISSING_ARGUMENTS | At least one argument was required but missing from
the args parameter. |
| SQL_ERROR | An error was encountered exceuting the SQL query. The error message will also contain the error reported by the database. |
Example 40. HTTP POST Body to Invoke the Query Operation
The following example could be used in the body of an HTTP POST request to the Query.aspx request page.
<request> <param name="topicmap">mytopicmap</param> <param name="queryid">MyQuery</param> <param name="args">ARG1</param> <param name="args">ARG2</param> </request>
Example 41. HTTP GET URL to Invoke the Query Operation
The following example shows how to invoke the Query operation using an HTTP GET. Note that this interface can be only used if the query takes one argument or no arguments.
http://topicmap.mycorp.com/tmws/Query.aspx?topicmap=mytopicmap&queryid=MyQuery&args=ARG1
Example 42. C# Code to Invoke the Query Operation using the Web Services Client Library
TMSClient client = new TMSClient("http://topicmap.mycorp.com/tmws/TMService.asmx");
XmlNode results = client.Query("mytopicmap", "MyQuery", new string[] { "ARG1", "ARG2" });
// The results can be deserialized as a DataSet which will always contain a single table:
DataSet dsResults = new DataSet();
dsResults.ReadXml(new XmlNodeReader(results));
// Now you can access the results table as:
DataTable dt = dsResults.Tables[0];Saves one or more topics and associations to the topic map. This method can be used to create new topics and associations, to modify existing topics and associations, and to delete objects from topics and associations (to delete entire topics or associations, use the Delete Topics or Delete Associations methods).
The topic map to be updated.
The updates to be made to the topic map expressed as an XML document conforming to the NetworkedPlanet Topic Map Fragment XML Schema and with the frag:topicmap element as the root element.
An XML document conforming to the NetworkedPlanet Web Service
Results XML schema with a res:results element as
the root element of the document. The res:resultrs element will
contain one res:result element for each
frag:topic and each frag:association element
contained in the tmfragment parameter
indicating the success status for the update of that object). The
key attribute of the
res:result element will contain the value of the
oid attribute of the
frag:topic or frag:association
that was processed. The following error codes may appear inside
res:result/res:error elements where an error occurs updating an
individual object:
| Error Code | Condition |
|---|---|
| INVALID_OID | The value of the oid attribute of
the object to be updated was not a valid object identifier.
For existing objects, the value of the
oid attribute must match the object
identifier of at least one existing object. For newly
created objects, the oid attribute must
start with the prefix 'new:' followed by one or more ASCII
letters or digits. |
| INVALID_VERSION | The value of the version attribute
of the object to be updated was not a valid version number.
A valid version number must be an integer value greater than
0. |
| INVALID_TOPIC_REFERENCE | A topic reference contained in the
frag:topic or
frag:association could not be properly
resolved. To properly resolve, the reference must be either
the object identifier of an existing topic in the topic map,
or it must match the value of the oid attribute for a newly
created topic defined in the current
tmfragment parameter. |
| NO_SUCH_TOPIC | The fragment contains a reference to a topic
that does not exist in the topic map or which does not exist
in the context specified in the
|
| UPDATE_ERROR | The fragment was syntactically valid but one of the operations described caused an error. The res:cause element will contain details about the error. |
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
Example 43. HTTP POST Body to Invoke the Save Operation
The following example could be used in the body of an HTTP POST request to the Save.aspx request page. The updated topic will have one name and one occurence after the operation completes.
<request>
<param name="topicmap">mytopicmap</param>
<param name="tmfragment">
<tmf:topicmap xmlns:tmf="http://www.networkedplanet.com/2005/01/topicmap/data/">
<tmf:topiclist>
<tmf:topic oid="1234">
<tmf:names>
<tmf:name>
<tmf:namestring>Mega Corp Limited</tmf:namestring>
</tmf:name>
</tmf:names>
<tmf:occurrences>
<tmf:occurrence>
<tmf:type psi="http://psi.example.com/organizations/stock-ticker"/>
<tmf:resourcedata>MGCP</tmf:resourcedata>
</tmf:occurrence>
</tmf:occurrences>
</tmf:topic>
</tmf:topiclist>
</tmf:topicmap>
</param>
</request>Example 44. C# Code to Invoke the Save Operation using the Web Services Client Library
TMSClient client = new TMSClient("http://topicmap.mycorp.com/tmws/TMService.asmx");
// NOTE: This example shows building the request using CreateElement calls.
// You could also use XmlDocument.Load() to read from an external source
// or an internal string.
string tmfNS = "http://www.networkedplanet.com/2005/01/topicmap/data/";
XmlDocument requestDoc = new XmlDocument();
XmlElement topicmap = requestDoc.CreateElement("topicmap", tmfNS);
XmlElement topiclist = requestDoc.CreateElement("topiclist", tmfNS);
XmlElement topic = requestDoc.CreateElement("topic", tmfNS);
topic.SetAttribute("oid", "1234");
XmlElement names = requestDoc.CreateElement("names", tmfNS);
XmlElement name= requestDoc.CreateElement("name", tmfNS);
XmlElement namestring = requestDoc.CreateElement("namestring", tmfNS);
namestring.InnerText="Mega Corp Limited";
name.AppendChild(namestring);
names.AppendChild(name);
topic.AppendChild(names);
topiclist.AppendChild(topic);
topicmap.AppendChild(topiclist);
requestDoc.AppendChild(topicmap);
client.Save("mytopicmap", requestDoc);Processes a Topic Map Transaction to update a named topic map. Whereas the Save method updates a single topic or association and completely overwrites all existing information for that topic or association, this method provides the ability to update or create several topics or associations in a single batch and also to add or update parts of a topic without modifying the rest of it. For example, you can add a new occurrence to a topic without having to also specify all of the other names and occurrences that you don't want to be changed.
The description of the Topic Map Transaction Schema contained in the appendix of this document provides more detail about all of the different operations that can be specified in a single request.
The name of the topic map to update.
A XML representation of the transaction to perform. The transaction must adhere to the Topic Map Transaction XML Schema.
A document conforming to the Results XML Schema that lists the results of each individual operation in the transaction.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
| UPDATE_EXCEPTION | There was an error processing the transaction provided. Detailed information is provided as part of the error report. |
This section only shows examples of the wrapper XML required to pass a transaction in to the ProcessTransaction method. For a detailed description of the transaction document and its processing, please refer to the Topic Map Transaction XML Schema description in the Appendix.
Example 45. Invoking the ProcessTransaction Method using an HTTP POST
<request>
<param name="topicmap">mytopicmap</param>
<param name="transaction">
<txn:TopicMapTransaction xmlns:txn="http://www.networkedplanet.com/schema/transaction">
<!-- Operation descriptions go here -->
</txn:TopicMapTransaction>
</param>
</request>Example 46. Invoking The ProcessTransaction Method using C# and the Web Services Client Library
The method interface for the ProcessTransaction proxy simply takes an XmlNode as the transaction parameter value and so can be invoked as follows:
TMSClient client = new TMSClient("http://topicmap.mycorp.com/tmws/TMService.asmx");
XmlDocument txnDoc = new XmlDocument();
// Code to populate the txnDoc goes here
client.ProcessTransaction("mytopicmap", txnDoc);The transaction XML can be constructed in a number of ways. It can be read from a local file or from an internal string using the XmlDocument.Load() method, or you can construct the document element by element using the XmlDocument.CreateElement() and other related methods.
This section provides an overview of the NetworkedPlanet Constraint Language (NPCL) Web Services. These services are implemented both as SOAP web services and as simple HTTP GET/POST interfaces which allow connectivity from AJAX applications. This section starts with an overview of the operations that the NPCL Web Services provide, described in terms of their input parameters, processing and output. There then follows a description of how these are mapped to a SOAP web service interface and to an HTTP interface.
In the following service descriptions, elements with the namespace prefix 'npcl' come from the NPCL XML Schema and the prefix is assumed to be mapped to the namespace URI 'http://www.networkedplanet.com/schema/npcl'. Elements with the prefix 'nf' come from the NPCL Forms XML Schema and the prefix is assumed to be mapped to the namespace URI 'http://www.networkedplanet.com/schema/npcl-forms'.
This section describes the methods supported by the NPCL Web Services.
Returns the full set of NPCL types and constraints contained in a single identified topic map.
All of the NPCL types and constraints read from the named topic map will be returned as a document conforming to the NPCL XML Schema.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
| INVALID_SCHEMA | There was an error processing the schema information contained in the topic map. This error condition cannot be fixed without first modifying the topic map to correct the schema information it contains. |
Example 47. Invoking the GetSchema Operation using HTTP GET
To get the schema for a topic map you can simply use a HTTP GET with a URL like the following:
http://topicmaps.mycorp.com/npclws/GetSchema.aspx?topicmap=mytopicmap
Example 48. Invoking the GetSchema Operation using HTTP POST
As an alternative the the GET method, you can POST an XML document containing the request parameters to the GetSchema.aspx request page. The XML document should look like this:
<request> <param name="topicmap">mytopicmap</param> </request>
Example 49. Invoking the GetSchema Operation over SOAP using the Web Client library
The following C# snippet shows how to get the NPCL schema for a topic map using the Web Client library.
NpclClient client = new NpclClient("http://topicmaps.mycorp.com/npclws/NpclSchemaService.asmx");
XmlNode npclSchema = client.GetSchema("mytopicmap");Returns an XML document conforming to the NPCL Forms XML Schema which describes the occurrence and association constraints for each topic type in the specified topic map.
On success, returns an XML document conforming to the NPCL
Forms XML Schema containing one nf:topicType
element for each topic type defined in the NPCL schema for the
specified topic map.
Example 50. Invoking the GetFormsSchema Operation using HTTP GET
To get the schema for a topic map you can simply use a HTTP GET with a URL like the following:
http://topicmaps.mycorp.com/npclws/GetFormsSchema.aspx?topicmap=mytopicmap
Example 51. Invoking the GetFormsSchema Operation using HTTP POST
As an alternative the the GET method, you can POST an XML document containing the request parameters to the GetSchema.aspx request page. The XML document should look like this:
<request> <param name="topicmap">mytopicmap</param> </request>
Example 52. Invoking the GetFormsSchema Operation over SOAP using the Web Client library
The following C# snippet shows how to get the NPCL schema for a topic map using the Web Client library.
NpclClient client = new NpclClient("http://topicmaps.mycorp.com/npclws/NpclSchemaService.asmx");
XmlNode npclSchema = client.GetFormsSchema("mytopicmap");Returns an XML document conforming to the NPCL Forms XML Schema which describes the occurrence and association constraints for the topic type in the specified topic map with the specified subject identifier.
The name of the topic map to be searched for the topic type.
The subject identifier of the topic type whose constraints are to be returned.
On success, returns an NPCL Forms XML Schema containing on
nf:topicType element which describes all of the
applicable constraints for the topic type identified by the request
parameters.
If the topic identified by the type parameter is not an NPCL
topic type, then the NPCL Forms XML Schema document returned will
consist of only an empty nf:schema
element.
| Error Code | Condition |
|---|---|
| INVALID_TOPICMAP | The name provided in the
topicmap parameter does not match the
name of any topic map known to the server. The client should
retry, specifying the correct topic map name. |
| INVALID_SCHEMA | There was an error processing the schema information contained in the topic map. This error condition cannot be fixed without first modifying the topic map to correct the schema information it contains. |
| NO_SUCH_TOPIC | No topic was found in the specified topic map that has the requested type subject identifier. |
Example 53. Invoking the GetFormsSchemaForType Operation using HTTP GET
To get the schema for a topic map you can simply use a HTTP GET, passing the parameters in the URL. Note that the subject identifier in the type parameter will require URL escaping.
http://topicmaps.mycorp.com/npclws/GetFormsSchemaForType.aspx?topicmap=mytopicmap&type=http%3A%2F%2Fpsi.example.com%2f...
Example 54. Invoking the GetFormsSchemaForType Operation using HTTP POST
As an alternative the the GET method, you can POST an XML document containing the request parameters to the GetFormsSchemaForType.aspx request page. The XML document should look like this:
<request> <param name="topicmap">mytopicmap</param> <param name="type">http://psi.example.com/organization/company</param> </request>
Example 55. Invoking the GetFormsSchemaForType Operation over SOAP using the Web Client library
The following C# snippet shows how to get the NPCL schema for a topic map using the Web Client library.
NpclClient client = new NpclClient("http://topicmaps.mycorp.com/npclws/NpclSchemaService.asmx");
XmlNode npclSchema = client.GetFormsSchemaForType("mytopicmap", "http://psi.example.com/organization/company");The following sections describe the detailed structure of the
various XML schemas used by the web services. These schemas can also be
found in the schemas directory of your TMCore
installation.
The NetworkedPlanet Topic Map Fragment XML Schema provides a way for web service applications to transmit a small subset of a topic map as a list of topics. Compared to XTM, the Topic Map Fragment schema is easier to process both for reading and for updating topic data as all of the information relating to a single topic is contained inside one element instead of being spread out across multiple separate elements in the same document. This schema is used by several of the methods of the NetworkedPlanet Topic Map Web Service.
The W3C XML Schema representation for this namespace is also in the TMCore distribution and can also be downloaded from the NetworkedPlanet website.
The namespace for the Topic Map Fragment XML Schema is
http://www.networkedplanet.com/2005/01/topicmap/data/. In
the remainder of this section, this URI is assumed to be mapped to the
namespace prefix 'tm'.
The topicmapsystem element is used to convey
a list of topic maps that are all managed by the same TMCore instance.
This element has the following syntax:
<tm:topicmapsystem> <tm:topicmap ... > ... </tm:topicmap> </tm:topicmapsystem>
The container for the list of topic maps managed by a TMCore instance.
Contains information about one of the topic maps managed by the TMCore instance. This element is OPTIONAL and REPEATABLE.
The topicmap element is used to convey all or
(more usually) a subset of the data in a single topic map. This
element has the following syntax:
<tm:topicmap
oid="OID"
topicmapname="NAME">
<tm:topiclist>
<tm:topic ... > ... </tm:topic>
</tm:topiclist>
<tm:assoclist>
<tm:association ... > ... </tm:association>
</tm:assoclist>
</tm:topicmap>The container for information relating to a single topic map.
TMCore's unique object identifier for the topic map. This OID is unique across all topic map objects (topic maps, topics, associations, occurrences etc) managed by the same TMCore instance. This attribute is OPTIONAL.
The name assigned to the topic map. This name is unique across all topic maps managed by the same TMCore instance. This attribute is OPTIONAL.
Contains information relating to one or more topics from
the topic map as a list of tm:topic elements.
This element is OPTIONAL and NON-REPEATABLE.
Contains information relating to a single topic from the topic map. This element is REQUIRED and REPEATABLE.
Contains information relating to one or more associations from the topic map as list of tm:association elements. This element is OPTIONAL and NON-REPEATABLE.
Contains information relating to a single association from the topic map. This element is REQUIRED and REPEATABLE.
The topic element conveys all of the information that relates to a single topic, including the associations that the topic participates in.
<tm:topic
oid="OID"
version="VERSION"
psi="VERSION"
stub="true|false">
<tm:subjectIdentifiers>
<tm:locator href="URI"/>
</tm:subjectIdentifiers>
<tm:subjectLocators>
<tm:locator href="URI"/>
</tm:subjectLocators>
<tm:sourceLocators>
<tm:locator href="URI"/>
</tm:sourceLocators>
<tm:topicTypes>
<tm:topicref ... />
</tm:topicTypes>
<tm:names>
<tm:name ... > ... </tm:name>
</tm:names>
<tm:occurrences>
<tm:occurrence ... > ... </tm:occurrence>
</tm:occurrences>
<tm:associations>
<tm:association ... > ... </tm:association>
</tm:associations>
</tm:topic>The container for information relating to a single topic.
TMCore's unique object identifier for this topic. This identifier is unique across all topic map objects managed by the same TMCore instance. This attribute is OPTIONAL.
Specifies the version number for a topic. When received from the web serivce, this attribute specifies the current version number of the topic. When passed in to a web service operation, this attribute specifies the version of the topic that the operation is to be applied to. This attribute is OPTIONAL.
Identifies the a topic by its subject identifier. This
attribute is OPTIONAL and is used on the input into web service
operations only. The subject identifiers of a topic received
from the web service will only be specified by the
tm:locator elements in the
tm:subjectIdentifiers child element.
Indicates if this element contains all of the information about the topic. This attribute is OPTIONAL.
If this attribute is present with the value 'true', then the element contains only stub information about the topic. Stub information is limited to just the topic's identifiers (OID, subject identifiers, source locators and subject locators) and any unscoped names.
If this attribute is not present or it is present with the value 'false', then the topic element contains all of the information about the topic.
Contains a list of the subject identifiers for this topic. This element is OPTIONAL.
Contains a single subject identifier URI that is assigned to this topic. This attribute is REQUIRED.
Contains a list of the subject locators for this topic. This element is OPTIONAL.
Contains a single subject locator URI assigned to this topic. This attribute is REQUIRED.
Contains a list of the source locators for this topic. This element is OPTIONAL.
Contains a single source locator URI assigned to this topic. This attribute is REQUIRED.
Contains a list of tm:topicref elements
that reference the topics that define the type(s) for this
topic. This element is OPTIONAL.
References a single topic that is a type for this topic. This element is REQUIRED and REPEATABLE.
Contains a list of tm:name elements
that define the names assigned to this topic. This element is
OPTIONAL.
Contains a list of tm:occurrence
elements that define the occurrences assigned to this topic.
This element is OPTIONAL.
Contains a list of tm:association
elements that define the associations in which this topic plays
a role. This element is OPTIONAL.
This element conveys all of the information relating to a single topic name. The element has the following syntax:
<tm:name oid="OID">
<tm:sourceLocators>
<tm:locator href="URI"/>
</tm:sourceLocators>
<tm:namestring> STRING </tm:namestring>
<tm:type ... />
<tm:variants>
<tm:variant ... > ... </tm:variant>
</tm:variants>
<tm:scope> ... </tm:scope>
</tm:name>Contains the unique object identifier of the name. This attribute is OPTIONAL.
Contains a list of the source locators for this name.
Contains a single source locator URI for this name.
Contains the string value for this name. This element is REQUIRED.
Contains type information for this name. This element is OPTIONAL and is currently NOT SUPPORTED by the web service implementation.
Contains a list of tm:variant elements
that define the variant names for this name. This element is
OPTIONAL.
Specifies the scope for this name. This element is OPTIONAL.
This element conveys all of the information relating to a single topic variant name. The element has the following syntax:
<tm:variant oid="OID">
<tm:sourceLocators>
<tm:locator href="URI"/>
</tm:sourceLocators>
<tm:namestring> STRING </tm:namestring>
<tm:resource href="URI"/>
<tm:scope> ... </tm:scope>
</tm:variant>Contains the unique object identifier of the variant name. This attribute is OPTIONAL. It may be omitted when creating a new variant name on a topic.
Contains a list of the source locators for this variant name.
Contains a single source locator URI for this variant name.
Contains the string value for this variant name. This element is OPTIONAL.
Specifies the resource locator for this variant name. This element is OPTIONAL.
Contains the resource locator URI for this variant name. This attribute is REQUIRED.
Specifies the scope for this variant name. This element is OPTIONAL.
This element contains all of the information relating to a single occurrence. The element has the following syntax:
<tm:occurrence oid="OID">
<tm:sourceLocators>
<tm:locator href="URI"/>
</tm:sourceLocators>
<tm:type displayname="NAME" tref="OID" psi="PSI" />
<tm:resourcedata> STRING </tm:resourcedata>
<tm:resource href="URI"/>
<tm:scope> ... </tm:scope>
</tm:occurrence>Contains the unique object identifier of the occurrence. This attribute is OPTIONAL. It may be omitted when creating a new occurrence on a topic.
Contains a list of the source locators for this occurrence. This element is OPTIONAL.
Contains a single source locator URI for this occurrence. This attribute is REQUIRED.
Contains a display label for the topic which defines the type of this occurrence. This attribute is OPTIONAL.
Contains the unique object identifier of the topic which defines the type of this occurrence. This attribute is REQUIRED.
References the topic which defines the type of this occurrence by a subject identifier of that topic. This attribute is OPTIONAL.
Contains the resource data value for the occurrence. This element is OPTIONAL.
Specifies the resource locator for the occurrence. This element is OPTIONAL.
Contains the resource locator URI for this occurrence. This attribute is REQUIRED.
Specifies the scope for this occurrence. This element is OPTIONAL.
This element contains all of the information about a single association. The element has the following syntax:
<tm:association oid="OID" version="VERSION">
<tm:sourceLocators>
<tm:locator href="URI"/>
</tm:sourceLocators>
<tm:type displayname="NAME" tref="OID" psi="PSI"/>
<tm:playsrole displayname="NAME" tref="OID" psi="PSI">
<tm:label> STRING </tm:label>
<tm:role>
<tm:sourceLocators>
<tm:locator href="URI"/>
</tm:sourceLocators>
<tm:type displayname="NAME" tref="OID" psi="PSI"/>
<tm:player displayname="NAME" tref="OID" psi="PSI"/>
</tm:role>
<tm:scope> ... </tm:scope>
</tm:association>Contains the unique object identifier of the association. This attribute is OPTIONAL - it may be omitted when specifying a new association to add to the topic map.
Specifies the version number of the association. This
attribute is OPTIONAL. This attribute will always be present on
tm:association elements received from web
service operations and will show the latest version number of
the association. If present on tm:association
elements passed in to web service operations, this attribute
identifies the version of the association to be
used/updated.
Contains a list of the source locators for this association. This element is OPTIONAL.
Contain a single source locator URI for this association. This attribute is REQUIRED.
References the topic that defines the type of this association. This element is OPTIONAL. If not present, the association is untyped.
Contains a display label for the topic that defines the type of this association. This attribute is OPTIONAL.
Contains the object identifier of the topic that defines the type of this association. This attribute is OPTIONAL.
References the topic that defines the type of this association by a subject identifier for that topic. This attribute is OPTIONAL.
References the topic that defines the type of the role
played by the topic described by the ancestor
tm:topic element of this element. This
element is OPTIONAL and MUST be omitted when this element is not
a descendant of a tm:topic element.
Contains the display label for the topic that defines the role type played by the topic described by the ancestor tm:topic element.
Contains the object identifier of the topic that defines
the role type played by the topic described by the ancestor
tm:topic element.
References the topic that defines the role type played by
the topic described by the ancestor tm:topic
element. This attribute contains a subject identifier for the
referenced topic. This attribute is OPTIONAL.
Contains the "arc label" for the association. The arc
label is a name assigned to the association type that is scoped
by the topic that types the role identified by the
tm:playsrole element. This element is
OPTIONAL and MUST be omitted when this element is not a
descendant of a tm:topic element.
Contains information about a single role in the association. This element is OPTIONAL and REPEATABLE. If the tm:association element is contained in a tm:topic element, then there will be one tm:role element for each topic that participates in the association other than the topic described by the ancestor tm:topic element (whose role is instead described by the tm:playsrole element). If the tm:association element is not contained inside a tm:topic element, there will be one tm:role element for each topic that participates in the association.
Contains a list of the source locators for this role. This element is OPTIONAL.
Contains a single source locator URI for this role. This attribute is REQUIRED.
Contains a reference to the topic that defines the type of this role. This element is OPTIONAL. If omitted, then the role is untyped.
Contains a display label for the topic that defines the type of this role. This attribute is OPTIONAL.
Contains the unique object identifier of the topic that defines the type of this role. This attribute is OPTIONAL.
References the topic that defines the type of this role by a subject identifier. This attribute is OPTIONAL.
Contains a reference to the topic that participates in the association via this role. This element is OPTIONAL. If omitted, then the role is present in the association but is currently not fulfilled by any role-playing topic.
Contains a display label for the topic that participates in the association via this role. This attribute is OPTIONAL.
Contains the unique object identifier of the topic that participates in the association via this role. This attribute is OPTIONAL.
References the topic that participates in the association via this role by a subject identifier of that topic. This attribute is OPTIONAL.
Specifies the scope of this association. This element is OPTIONAL.
This element defines the scope of an occurrence, name, variant name or association. The element has the following syntax:
<tm:scope> <tm:topicref ... /> </tm:scope>
References a single topic in the scope (also called a 'scoping topic'). This element is REQUIRED and REPEATABLE.
This element is used wherever a refernce to a topic is required. It provides two different methods of identifying a topic when passed in to a web service operation and additionally provides a displayable label for a topic when received from a web service operation.
This element has the following structure:
<tm:topicref
tref="OID"
psi="PSI"
displayname="NAME" />Identifies the referenced topic by its database object
identifier. The schema declares this attribute as OPTIONAL. The
attribute will always be present on
tm:topicref elements received from web
service operations, but is optional on
tm:topicref elements passed in to web service
operations (as long as the psi attribute is
used to identify the topic by a subject identifier
instead).
Identifies the referenced topic by a subject identifier
for that topic. The schema declares this attribute as OPTIONAL.
The attribute will never be present on
tm:topicref elements received from web
service operations, but may optionally be present on
tm:topicref elements passed in to web service
operations.
Provides a displayable label for the referenced topic. The
schema declares this attribute as OPTIONAL. However, this
attribute is only used on tm:topicref
elements received from web service operations. This attribute
allows a client application to display a link to the topic
without the need to retrieve the topic to get a display name for
it.
The Hierarchy XML Schema is used to convey one or more hierarchical orderings of topics.
The namespace for the Hierarchy XML Schema is
http://www.networkedplanet.com/2005/01/topicmap/patterns/hierarchy/.
The rest of this document assumes that the namespace is mapped to the
prefix tmh, declared as shown here:
<hierarchy xmlns:tmh="http://www.networkedplanet.com/2005/01/topicmap/patterns/hierarchy"/>
This element is used to contain a list of the trees in a single topic map. The element has the following syntax:
<tmh:treelist>
<tmh:tree topicid="OID" displayname="NAME">
<tmh:root tref="OID" displayname="NAME" />
</tmh:tree>
</tmh:treelist>tmh:treelist/tmh:treeContains the definition of a single hierarchy. This element is OPTIONAL and REPEATABLE.
tmh:treelist/tmh:tree/@topicidContains the unique object identifier of the topic that defines the hierarchy. This attribute is REQUIRED.
tmh:treelist/tmh:tree/@displaynameContains a display label for the topic that defines the hierarchy. This attribute is OPTIONAL.
tmh:treelist/tmh:tree/tmh:rootA reference to the topic that is at the root of the hierarchy. This element is REQUIRED.
tmh:treelist/tmh:tree/tmh:root/@trefContains the unique object identifier of the topic that is at the root of the hierarchy. This attribute is REQUIRED.
tmh:treelist/tmh:tree/tmh:root/@displaynameContains a display label for the topic that is at the root of the hierarchy. This attribute is OPTIONAL.
This element contains the description of a single hierarchical ordering of topics. The hierarchy is represented as a nested set of lists of nodes, each node consists of a reference to the topic that is at that position in the hierarchy followed by a list of the child nodes. The element has the following syntax:
<tmh:nodelist>
<tmh:node>
<tmh:topic tref="OID" displayname="NAME" />
<tmh:children>
<tmh:node> ... </tmh:node>
</tmh:children>
</tmh:node>
</tmh:tree>tmh:nodelist/tmh:nodeContains the specification of a single node in the hierarchy. This element is REQUIRED and REPEATABLE.
tmh:nodelist/tmh:node/tmh:topicA reference to the topic that occupies this node in the hierarchy. This element is REQUIRED.
tmh:nodelist/tmh:node/tmh:topic/@trefThe unique object identifier of the topic that occupies this node in the hierarchy. This attribute is REQUIRED.
tmh:nodelist/tmh:node/tmh:topic/@displaynameA display label for the topic that occupies this node in the hierarchy. This attribute is OPTIONAL.
tmh:nodelist/tmh:node/tmh:childrenA list of the child nodes of this node in the hierarchy. This element is OPTIONAL.
tmh:nodelist/tmh:node/tmh:children/tmh:nodeContains the specification of a single node in the
hierarchy. This element is REQUIRED and REPEATABLE and has the
same structure as the tmh:nodelist/tmh:node
element.
Example A.1. A List of Trees using tmh:treelist
The following example shows the use of
tmh:treelist to list the trees in a topic map (in
this case, two trees). This is the format of the returned document
from the GetHierarchyRoots method of the
Topic Map Web Service.
<tmh:treelist>
<tmh:tree topicid="302728" displayname="Tree 1">
<tmh:root displayname="My Root Node" tref="302740"/>
</tmh:tree>
<tmh:tree topicid="316060" displayname="Tree 2">
<tmh:root displayname="Root" tref="316071" />
</tmh:tree>
</tmh:treelist>Example A.2. A Simple Tree Using tmh:nodelist
The following example shows the use of
tmh:nodelist to describe a tree. This is the
format of the returned document from the
GetHierarchy method of the Topic Map Web
Service.
<tmh:nodelist>
<tmh:node>
<tmh:topic displayname="Root" tref="316071"/>
<tmh:children>
<tmh:node>
<tmh:topic displayname="Child1" tref="316075"/>
<tmh:children>
<tmh:node>
<tmh:topic displayname="Child1.Child1" tref="316077"/>
<tmh:children/>
</tmh:node>
<tmh:node>
<tmh:topic displayname="Child1.Child2" tref="316079"/>
<tmh:children/>
</tmh:node>
</tmh:children>
</tmh:node>
<tmh:node>
<tmh:topic displayname="Child2" tref="316081"/>
<tmh:children/>
</tmh:node>
</tmh:children>
</tmh:node>
</tmh:nodelist>This document presents the XML schema used to describe transactional updates to a topic map in the ProcessTransaction method of the Topic Map Web Service. The update structure is designed to allow a collection of low level topic map operations to be grouped together and executed as a single atomic operation.
The advantage of this over the Save method of the Topic Map Web Service is that this transactional update method allows partial information to be added to a topic and so it does not require the whole of the topic to be available on the client, changed and then posted back. The Process Transaction method has the notion of, "Here are a set of changes to make to the topic map". The Save has the notion that says: "This is the defitive version of the topic - replace whatever is there". Both approaches are useful in different situations.
The W3C XML Schema representation for this namespace is also in the TMCore distribution and can also be downloaded from the NetworkedPlanet website.
The namespace used for Topic Map Transaction schema is http://www.networkedplanet.com/schema/transaction. In the examples in the rest of this section, this namespace is assumed to be mapped to the namespace prefix "txn".
The Topic Map Transaction Schema allows elements from the Topic Map Fragment Schema to be included as part of the description of actions to take place inside a transaction. The schema is described in detail in the section called “Topic Map Fragment XML Schema”. The namespace for this schema is http://www.networkedplanet.com/2005/01/topicmap/data/. In the examples in the rest of this section, this namespace is assumed to be mapped to the namespace prefix "tmd".
In all of the following operations, the elements
tmd:topicref, tmd:type,
tmd:roletype and tmd:player
allow a reference to a topic by either is unique object identifier
(using the oid attribute) or using a subject
identifier reference (using the psi attribute).
When the psi attribute is used, if no topic is
found that matches the specified subject identifer, a new, untyped
topic will be created and assigned that value as a subject identifier.
When the oid attribute is used, if no topic is
found in the topic map with the specified object identifier, an error
is raised.
Developers should be aware of the implicit topic creation by
using the psi attribute as described above. This
is a powerful tool for quick update of a topic map, but can create a
lot of unwanted topics if not used carefully.
The TopicMapTransaction element is the root
element for a transaction document. Each transaction consists of an
ordered list of actions. Actions and transactions
are executed in the order that they are specified in the XML document,
but the results of these actions are not committed to the database
until all actions are successfully completed. If one action within a
TopicMapTransaction element is not processed successfully, all
modifications to the topic map made by preceding actions are revoked
and the processing will stop and an error returned in the results
document.
The TopicMapTransaction element has the
following syntax:
<txn:TopicMapTransaction> <txn:CreateTopic ... > ... </txn:CreateTopic> <txn:UpdateTopic ... > ... </txn:UpdateTopic> <txn:DeleteTopic ... > ... </txn:DeleteTopic> <txn:CreateTopicProperty ... > ... </txn:CreateTopicProperty> <txn:DeleteTopicProperty ... > ... </txn:DeleteTopicProperty> <txn:CreateAssociation ... > ... </txn:CreateAssociation> <txn:DeleteAssociation ... > .... </txn:DeleteAssociation> <txn:TopicMapTransaction ... > ... </txn:TopicMapTransaction> </txn:transaction>
This element describes a single transaction. The elements
shown as children of this element may occur any number of times
and in any order. Nested transactions are supported and are
represented using nested
txn:TopicMapTransaction elements.
The other child elements allowed inside the
txn:TopicMapTransaction element are described
below.
The CreateTopic element specifies that a new
topic should be created in the topic map. The CreateTopic element has
the following structure:
<txn:CreateTopic id="...">
<tmd:topic oid="...">
...
</tmd:topic>
</txn:CreateTopic>
The wrapper element for the CreateTopic action.
The identifier for this operation. This identifier is used to correlate any error messages to the operation that caused the error.
This REQUIRED element from the Topic Map Fragment XML
Schema provides the details of the topic to be created. If the
oid attribute is provided, it may be used to
reference the newly created topic in later operations (for
example to create associations to the new topic, or to create
further topics that are typed by the new topic).
This operation can only be used to create a topic, its
names and occurrences. The optional
tmd:associations element allowed inside the
tmd:topic element will be ignored. To
create associations that involve the new topic, it is
necessary to use a separate
txn:CreateAssociation action.
txn:CreateAssociation actions may be
included in the same transaction as the one that creates the
topic(s) to participate in the association.
This operations specifies a new set of names, occurrences and
identifiers to be assigned to an existing topic in the topic map. The
new data completely replaces all existing names, occurrences and
identifiers, but the roles played by the topic in associations are not
modified by this action. The txn:UpdateTopic
element has the following structure:
It is important to note that this action completely overwrites any existing identiiers, names or occurrences on the target topic. If you just wish to add new identifiers, names or occurrences use the CreateTopicProperty method. If you wish to remove some identifiers, names or occurrences but leave others intact, use DeleteTopicProperty. A combination of DeleteTopicProperty and CreateTopicProperty can be used to modify a specific item (by deleting it and creating it with a new value in a single TopicMapTransaction).
<txn:UpdateTopic id="..." create="true|false">
<tmd:topic oid="..." subjectIdentifier="..." subjectLocator="..." sourceLocator="...">
...
</tmd:topic>
</txn:UpdateTopic>
The wrapper element for the UpdateTopic action.
The identifier for this operation. This identifier is used to correlate any error messages to the operation that caused the error.
A boolean flag indicating if the topic should be created if it does not already exist.
This REQUIRED element from the Topic Map Fragment XML Schema provides the new details to be applied to the topic. The topic that the update is applied to is identified by one of the two optional attributes on this element.
This OPTIONAL attribute directly identifies the topic to
be updated. The value of this attribute may be either an integer
database object identifier, or the string identifier of a topic
created in this a previous action contained in the current
request document. If the topic cannot be found in the database
and the create attribute of the
UpdateTopic element is set to true, then a
new topic will be created and will be accessible in the current
transaction either using its actual object identifier, or using
the oid value specified by this attribute.
The system will always attempt to process an integer oid
attribute value as a database object identifier, so it is
important when creating new topics using this interface that
you only assign non-integer values to the
oid attribute of topics and associations
created using the CreateTopic or CreateAssociation
actions.
This optional attribute identifies the topic to be updated
by its subject identifier. This attribute will be processed ONLY
IF the oid attribute is not present. If the
topic cannot be found in the database and the
create attribute of the
UpdateTopic element is set to true, then a
new topic will be created in the topic map.
This optional attribute identifies the topic to be updated
by its subject locator. This attribute will be processed ONLY IF
the oid and
subjectIdentifier attributes are not present.
If the topic cannot be found in the database and the
create attribute of the
UpdateTopic element is set to true, then a
new topic will be created in the topic map.
This optional attribute identifies the topic to be updated
by its source locator. This attribute will be processed ONLY IF
the oid, subjectIdentifier and
sourceLocator attributes are not present. If
the topic cannot be found in the database and the
create attribute of the
UpdateTopic element is set to true, then a
new topic will be created in the topic map.
This OPTIONAL attribute identifies the version of the topic to be updated. The topic will only be updated if its current version number matches the value of this attribute. If the topic's current version number does not match the value specified here, then an error will be returned.
If this attribute is ommitted, the update will be applied to the latest version of the topic.
Although the Topic Map Fragment XML Schema allows the
oid, subjectIdentifier,
subjectLocator and
sourceLocator attributes to be ommitted, this
action requires that at least one of these attributes has a
value.
This action will update the names, occurrences and identifiers
of the topic only. The contents of a
tmd:associations element inside the
tmd:topic element will be ignored by this
operation.
This action element specifies that a single topic should be
deleted. The topic to be deleted may be identified either by its
database object identifier or by a subject identifier assigned to the
topic. The DeleteTopic element has the following
structure:
<txn:DeleteTopic id="...">
<tmd:topic oid="..." subjectIdentifier="..." subjectLocator="..." sourceLocator="..." version="...">
...
</tmd:topic>
</txn:DeleteTopic> The wrapper element for the DeleteTopic action.
The identifier for this operation. This identifier is used to correlate any error messages to the operation that caused the error.
This REQUIRED element from the Topic Map Fragment XML Schema identifies the topic to be deleted. Only the oid and psi attributes of this element are processed - all other attributes and content are ignored.
OPTIONAL attribute. Identiifes the topic to be deleted by its database object identifier.
OPTIONAL attribute. Identifies the topic to be deleted by
its subject identifier. This attribute will be used only if no
value is provided for the oid
attribute.
OPTIONAL attribute. Identifies the topic to be deleted by
its subject locator. This attribute will be used only if no
value is provided for the oid and
subjectIdentifier attributes.
OPTIONAL attribute. Identifies the topic to be deleted by
its source locator. This attribute will be used only if no value
is provided for the oid
subjectIdentifier, and
subjectLocator attributes.
This OPTIONAL attribute identifies the version of the topic to be deleted. The topic will only be deleted if its current version number matches the value of this attribute. If the topic's current version number does not match the value specified here, then an error will be returned.
If this attribute is ommitted, the topic will be deleted regardless of the current version number.
Although the Topic Map Fragment XML Schema allows the
oid, subjectIdentifier,
subjectLocator and
sourceLocator attributes to be ommitted, this
action requires that at least one of these attributes has a
value.
This action adds names, occurrences and identifiers to a topic already in the database (or a topic created in a preceding action in the same request). The element has the following structure:
<txn:CreateTopicProperty id="...">
<tmd:topic oid="..." subjectIdentifier="..." subjectLocator="..." sourceLocator="..." version="...">
...
</tmd:topic>
</txn:CreateTopicProperty> The wrapper element for this action.
The identifier for this operation. This identifier is used to correlate any error messages to the operation that caused the error.
REQUIRED. Identifies the topic to be updated and contains the names, occurrences and identifiers to be added to the topic.
Identifies the topic to be updated by either its database object identifier (if the topic already exists in the database), or by the object identifier assigned to the topic when it was created in a preceding action. A string which can be parsed as a valid database object identifier (an integer) will be treated as such.
Identifies the topic to be updated by its subject
identifier. This attribute will be used only if no value is
provided for the oid attribute.
OPTIONAL attribute. Identifies the topic to be updated by
its subject locator. This attribute will be used only if no
value is provided for the oid and
subjectIdentifier attributes.
OPTIONAL attribute. Identifies the topic to be updated by
its source locator. This attribute will be used only if no value
is provided for the oid
subjectIdentifier, and
subjectLocator attributes.
This OPTIONAL attribute identifies the version of the topic to be updated. The topic will only be updated if its current version number matches the value of this attribute. If the topic's current version number does not match the value specified here, then an error will be returned.
If this attribute is ommitted, the update will be applied to the latest version of the topic.
This method will fail if the topic to be updated cannot be found.
Although the Topic Map Fragment XML Schema allows the
oid, subjectIdentifier,
subjectLocator and
sourceLocator attributes to be ommitted, this
action requires that at least one of these attributes has a
value.
This action removes names, occurrences and/or identifiers from a specified topic. The content of this element specifies the topic to be updated, and lists the names, occurrences and identifiers to be removed.
This method allows two ways of specifying the items to be removed from a topic:
Deletion By Reference - names and
occurrences can be specified with the database object identifier
of the name or occurrence to be deleted in the
oid attribute of the
tmd:name, tmd:variant or
tmd:occurrence elements. The name, variant name
or occurrence with that OID will be deleted ONLY IF it is
contained within the topic specified by the request.
Deletion By Value - names, occurrences and identifiers can be specified for deletion by defining the complete value of the item to be matched. The value must match in all respects. For names, this means that the name string and scope must match; for variants, the name string or resource and scope must match; for occurrences, the data string or resource and the scope must match; and for identifiers just the identifier string must match. String values can be matched using the SQLServer wildcard operators _ and % to match a single character or a sequence of characters respectively.
In either case if a match is not found for an item to be deleted, this method WILL NOT fail, however if that the deletions are to be performed on cannot be found, the method WILL fail.
The DeleteTopicProperty element has the following structure
<txn:DeleteTopicProperty id="...">
<tmd:topic oid="..." subjectIdentifier="..." subjectLocator="..." sourceLocator="..." version="...">
...
</tmd:topic>
</txn:DeleteTopicProperty>The wrapper element for this action.
The identifier for this operation. This identifier is used to correlate any error messages to the operation that caused the error.
REQUIRED. Identifies the topic that deletions are to be performed on and contains the items to be deleted.
Identifies the topic to be updated by its database object identifier or the identifier assigned to the topic in a preceding CreateTopic action.
Identifies the topic to be updated by its subject
identifier. This attribute will be used only if no value is
provided for the oid attribute.
OPTIONAL attribute. Identifies the topic to be updated by
its subject locator. This attribute will be used only if no
value is provided for the oid and
subjectIdentifier attributes.
OPTIONAL attribute. Identifies the topic to be updated by
its source locator. This attribute will be used only if no value
is provided for the oid
subjectIdentifier, and
subjectLocator attributes.
This OPTIONAL attribute identifies the version of the topic to be updated. The topic will only be updated if its current version number matches the value of this attribute. If the topic's current version number does not match the value specified here, then an error will be returned.
If this attribute is ommitted, the update will be applied to the latest version of the topic.
Although the Topic Map Fragment XML Schema allows the
oid, subjectIdentifier,
subjectLocator and
sourceLocator attributes to be ommitted, this
action requires that at least one of these attributes has a
value.
This action creates a new association structure between topics. The CreateAssociation element has the following structure:
<txn:CreateAssociation id="...">
<tmd:association> ... </tmd:association>
</txn:CreateAssociation>
The wrapper element for this action.
The identifier for this operation. This identifier is used to correlate any error messages to the operation that caused the error.
Specifies the structure of the association to be created.
This action element deletes an association from the database.
The association to be deleted can be identified either by its database
object identifier or by specifying the structure of the association to
be deleted. The DeleteAssociation element has the
following structure:
<txn:DeleteAssociation id="...">
<tmd:association oid="..." sourceLocator="..." version="...">
...
</tmd:association>
</txn:DeleteAssociation> The wrapper element for this action.
The identifier for this operation. This identifier is used to correlate any error messages to the operation that caused the error.
Specifies the association to be deleted. If the
oid attribute is present with a value, then
the association whose database object identifier matches the
attribute value will be deleted. Otherwise the association which
matches the structure defined by the content of this element
will be deleted.
OPTIONAL. Specifies the database object identifier of the association to be deleted. If this attribute is present, then the association whose database object identifier matches the attribute value will be deleted.
OPTIONAL. Specifies the source locator of the association
to be deleted. This attribute will be processed only if the
oid attribute is not present.
This OPTIONAL attribute identifies the version of the association to be deleted. The association will only be updated if its current version number matches the value of this attribute. If the association's current version number does not match the value specified here, then an error will be returned.
If this attribute is ommitted, the association will be deleted regardless of the current version number.
If both the oid and
sourceLocator attributes are omitted, then the
association which matches the structure defined by the content of this
element will be deleted. When matching the association by its
structure, the association type, the scope of the association, the
number of association roles and the role type and role player of each
role are all considered and must all match. Some degree of wildcarding
is allowed in specifying the match structure - the association type
and the role type and role player of each role can be specified as a
wildcard using "-1" (without the double quotes) as the value of the
oid attribute of the type,
roletype or player
elements.
Example A.3. Creating a Topic
The following example shows how a topic can be created and populated with identifiers, names and occurrences. Note that you can refer to typing topics either by their database object identifier or by their PSI.
<txn:TopicMapTransaction>
<txn:CreateTopic id="ctop1">
<tmd:topic>
<tmd:subjectIdentifiers>
<tmd:locator href="http://www.networkedplanet.com/psi/employees/1234"/>
</tmd:subjectIdentifiers>
<tmd:topicTypes>
<tmd:type psi="http://www.networkedplanet.com/psi/employee"/>
</tmd:topicTypes>
<tmd:names>
<tmd:name>
<tmd:namestring>John Smith</tmd:namestring>
<tmd:variants>
<tmd:variant>
<tmd:namestring>SMITH, JOHN</tmd:namestring>
<tmd:scope>
<tmd:topicref psi="http://www.topicmaps.org/xtm/1.0/core.xtm#sort"/>
</tmd:scope>
</tmd:variant>
</tmd:variants>
</tmd:name>
</tmd:names>
<tmd:occurrences>
<tmd:occurrence>
<tmd:type psi="http://www.networkedplanet.com/psi/date-of-birth"/>
<tmd:resourcedata>1963-01-28</tmd:resourcedata>
</tmd:occurrence>
</tmd:occurrences>
</tmd:topic>
</txn:CreateTopic>
</txn:TopicMapTransaction>Example A.4. Deleting a Topic
To delete a topic you only need to know its database object identifier or one of its subject identifiers. The following example shows how to delete a topic by specifying its subject identifier.
<txn:TopicMapTransaction>
<txn:DeleteTopic id="deltop1">
<tmd:topic subjectIdentifier="http://www.networkedplanet.com/psi/employees/1234"/>
</txn:DeleteTopic>
</txn:TopicMapTransaction>Example A.5. Adding an Name, Occurrence or Identifier to a Topic
To add a name, occurrence or identifier to a topic, you need to specify the topic's database object identifier or one of its subject identifiers. You do not need to know the rest of the content of the topic. The example below adds a contact telephone number as an occurrence to a previously created topic using the topic's subject identifier to locate it.
<txn:TopicMapTransaction>
<txn:CreateTopicProperty id="delprop1">
<tmd:topic subjectIdentifier="http://www.networkedplanet.com/psi/employees/1234">
<tmd:occurrences>
<tmd:occurrence>
<tmd:type psi="http://www.networkedplanet.com/psi/contact-tel"/>
<tmd:resourcedata>0123 456 7890</tmd:resourcedata>
</tmd:occurrence>
</tmd:occurrences>
</tmd:topic>
</txn:CreateTopicProperty>
</txn:TopicMapTransaction>Example A.6. A Simple CreateAssociation Example
In this example, the database object identifiers of the topics that participate in the association and of the topics that define the association type and roles are all known in advance:
<txn:TopicMapTransaction>
<txn:CreateAssociation id="ca1">
<tmd:association>
<tmd:type oid="123"/>
<tmd:role>
<tmd:roleType oid="124"/>
<tmd:player oid="2001"/>
</tmd:role>
<tmd:role>
<tmd:roleType oid="125"/>
<tmd:player oid="2002"/>
</tmd:role>
</tmd:association>
</txn:CreateAssociation>
</txn:TopicMapTransaction> Example A.7. Using PSI References
The following example shows how database object identifier references and PSI references can be easily mixed together in the creation of an association. PSI references are often most useful for identifying topic types and fixed category lists in a topic map.
<txn:TopicMapTransaction>
<txn:CreateAssociation id="ca2">
<tmd:association>
<tmd:type psi="http://psi.example.com/event-has-location"/>
<tmd:role>
<tmd:roleType oid="http://psi.example.com/event-has-location-target"/>
<tmd:player oid="http://psi.example.com/cities/london"/>
</tmd:role>
<tmd:role>
<tmd:roleType oid="http://psi.example.com/event-has-location-source"/>
<tmd:player oid="2002"/>
</tmd:role>
</tmd:association>
</txn:CreateAssociation>
</txn:TopicMapTransaction> Example A.8. Combining Actions
Multiple actions can be combined into a single transactional update. New topics can be assigned an internal object identifier that is valid only for references made from other actions in the same transaction. This allows a new topic to be included in new associations or used as a topic type or scope without having to make two separate transactions.
The following example shows how two topics are created and connected together in an association all as part of a single transaction.
<txn:TopicMapTransaction>
<!-- Create a topic for Bart -->
<txn:CreateTopic id="create-bart">
<tmd:topic oid="bart">
<tmd:names>
<tmd:name>
<tmd:namestring>Bart Simpson</tmd:namestring>
</tmd:name>
</tmd:names>
</tmd:topic>
</txn:CreateTopic>
<!-- Create a topic for Homer -->
<txn:CreateTopic id="create-homer">
<tmd:topic oid="homer">
<tmd:names>
<tmd:name>
<tmd:namestring>Homer Simpson</tmd:namestring>
</tmd:name>
</tmd:names>
</tmd:topic>
</txn:CreateTopic>
<!-- Create a parent-child association between them -->
<txn:CreateAssociation id="create-assoc-1">
<tmd:association>
<tmd:type psi="http://psi.example.com/parent-child"/>
<tmd:role>
<tmd:roletype psi="http://psi.example.com/parent"/>
<tmd:player tref="homer"/>
</tmd:role>
<tmd:role>
<tmd:roletype psi="http://psi.example.com/child"/>
<tmd:player tref="bart"/>
</tmd:role>
</tmd:association>
</txn:CreateAssociation>
</txn:TopicMapTransaction>There is one restriction on the OIDs used for newly
created topics. The processor will check any
tref attribute value to see if it is a valid
database object identifier, before looking for internal
references assigned by CreateTopic actions. Therefore the object
identifier assigned to new topics must not be in a form that can
be recognised as a database object identifier. A database object
identifier is an integer string, so any string that contains at
least one non-numeric character can be used as an internal
identifier for a new topic.
Example A.9. Changing an Name, Occurrence or Identifier
Changing a single name, occurrence or identifier without modifying the other properties of a topic can be done by deleting the value to be changed and specifying a new value as part of a single transaction. If you know the database object identifier of the item to be deleted, you can use that to reference the item to be deleted. Otherwise you can specify the value of the item to be deleted (including its type and any scoping topics). The example below shows changing the contact telephone number created in the previous example, and deleting a name with the database object identifier "9987".
<txn:TopicMapTransaction>
<txn:DeleteTopicProperty id="op01">
<tmd:topic psi="http://www.networkedplanet.com/psi/employees/1234">
<tmd:names>
<!-- delete a name by specifying its object identifier -->
<tmd:name oid="9987"/>
</tmd:names>
<tmd:occurrences>
<!-- delete an occurrence by specifying its value -->
<tmd:occurrence>
<tmd:type psi="http://www.networkedplanet.com/psi/contact-tel"/>
<tmd:resourcedata>0123 456 7890</tmd:resourcedata>
</tmd:occurrence>
</tmd:occurrences>
</tmd:topic>
</txn:DeleteTopicProperty>
<txn:CreateTopicProperty id="op02">
<tmd:topic psi="http://www.networkedplanet.com/psi/employees/1234">
<tmd:occurrences>
<!-- Add a new occurrence -->
<tmd:occurrence>
<tmd:type psi="http://www.networkedplanet.com/psi/contact-tel"/>
<tmd:resourcedata>0123 554 5555</tmd:resourcedata>
</tmd:occurrence>
</tmd:occurrences>
</tmd:topic>
</txn:CreateTopicProperty>
</txn:TopicMapTransaction> Example A.10. Replacing an Occurrence
By using the wildcard string matching operators, you can also maintain a single occurrence of a given type (or a single name or variant in a given scope) by issuing a DeleteTopicProperty specifying the string match using the % wildcard, followed by a CreateTopicProperty operation. The example below shows this in operation - first, all occurrences of the type "http://www.networkedplanet.com/psi/contact-tel" are deleted from the topic, and then a single new occurrence is created.
<txn:TopicMapTransaction>
<txn:DeleteTopicProperty id="op01">
<tmd:topic psi="http://www.networkedplanet.com/psi/employees/1234">
<tmd:names>
<!-- delete a name by specifying its object identifier -->
<tmd:name oid="9987"/>
</tmd:names>
<tmd:occurrences>
<!-- delete all occurrences of a given type by specifying a wildcard value match -->
<tmd:occurrence>
<tmd:type psi="http://www.networkedplanet.com/psi/contact-tel"/>
<tmd:resourcedata>%</tmd:resourcedata>
</tmd:occurrence>
</tmd:occurrences>
</tmd:topic>
</txn:DeleteTopicProperty>
<txn:CreateTopicProperty id="op02">
<tmd:topic psi="http://www.networkedplanet.com/psi/employees/1234">
<tmd:occurrences>
<!-- Add a new occurrence -->
<tmd:occurrence>
<tmd:type psi="http://www.networkedplanet.com/psi/contact-tel"/>
<tmd:resourcedata>0123 554 5555</tmd:resourcedata>
</tmd:occurrence>
</tmd:occurrences>
</tmd:topic>
</txn:CreateTopicProperty>
</txn:TopicMapTransaction> A set of NPCL constraints can be specified using an XML document conforming to the NPCL XML Schema. This representation of the NPCL constraints is separate from the representation of the constraints in a topic map and so does not simply use the XTM syntax. NPCL XML Schema is also a more compact representation of a set of NPCL constraints than the topic map representation and is more easily processed using standard XML tools such as XSLT. This section describes the NPCL XML Schema in detail. The W3C XML Schema representation is also included in the TMCore distribution and can be downloaded from the NetworkedPlanet website.
The namespace used for NPCL XML Schema is http://www.networkedplanet.com/schema/npcl. In the examples in the rest of this section, this namespace is assumed to be mapped to the namespace prefix "npcl".
This is the root element of the NPCL XML synax. It contains a single types element which in turn contains the various type definition elements.
<npcl:schema>
<npcl:types>
<npcl:abstractType ...> ... </npcl:abstractType>
<npcl:topicType ... > ... </npcl:topicType>
<npcl:occurrenceType ... > ... </npcl:occurrenceType>
<npcl:associationType ... > ... </npcl:associationType>
<npcl:roleType ... > ... </npcl:roleType>
<npcl:scopingTopic ... > ... </npcl:scopingTopic>
</npcl:types>
</npcl:schema>
The root of an NPCL schema definition.
The wrapper for all type definitions contained in the schema. This element is OPTIONAL. The children of this element are allowed to appear in any order.
An OPTIONAL, REPEATABLE element describing a single Abstract Type in the schema.
An OPTIONAL, REPEATABLE element describing a single Topic Type in the schema.
An OPTIONAL, REPEATABLE element describing a single Occurrence Type in the schema.
An OPTIONAL, REPEATABLE element describing a single Assoiation Type in the schema.
An OPTIONAL, REPEATABLE element describing a single Role Type in the schema.
An OPTIONAL, REPEATABLE element describing a single Scoping Topic in the schema.
This element describes a single Abstract Type in the schema.
<npcl:abstractType id="...">
<npcl:subjectIdentifier>
SUBJECT IDENTIFIER
</npcl:subjectIdentifier>
<npcl:displayName> NAME </npcl:displayName>
<npcl:extension type="EXTENSION TYPE">
EXTENSION VALUE
</npcl:extension>
<npcl:subclasses> ... </npcl:subclasses>
</npcl:abstractType>
REQUIRED. An internal identifier for the type. This is used only for reference purposes inside the NPCL XML document.
REQUIRED, REPEATABLE. Contains a subject identifier URI for the type.
Contains a human-readable display label for the type.
Contains a single typed extension value for the type. The
value is the string content of this element. The type is
specified as a URI in the type attribute of
this elment.
Contains a list of the subclasses of this type. This element structure is described in detail below.
This element describes a single Topic Type in the schema. It contains the Occurrence and Role Player Constraints that apply to this Topic Type.
<npcl:topicType id="..." abstract="true|false">
<npcl:subjectIdentifier>
...
</npcl:subjectIdentifier>
<npcl:displayName>...</npcl:displayName>
<npcl:rolePlayerConstraint
roleTypeRef="..."
associationTypeRef="..."
minCardinality="..."
maxCardinality="..."/>
<npcl:occurrenceConstraint
occurrenceTypeRef="..."
minCardinality="..."
maxCardinality="..."/>
<npcl:extension type="...">
...
</npcl:extension>
<npcl:subclasses> ... </npcl:subclasses>
</topicType>
REQUIRED. An internal identifier for the type. This is used only for reference purposes inside the NPCL XML document.
OPTIONAL. A boolean value that indicates if this type is abstract. If not specified, this attribute value defaults to "false".
REQUIRED, REPEATABLE. Contains a subject identifier URI for the type.
Contains a human-readable display label for the type.
This element specifies a single Role Player Constraint that applies to this Topic Type.
The roleTypeRef attribute is REQUIRED
and contains the internal identifier of the Role Type that is
allowed by the Role Player Constraint. This must match the value
of the id attribute on a roleType element in the NPCL XML
document.
The associationTypeRef attribute is
OPTIONAL and contains the internal identifier of the Association
Type that is allowed by the Role Player Constraint. This must
match the value of the id attribute on an associationType
element in the NPCL XML document. If this attribute is ommitted,
then the Role Player Constraint applies to all roles of the
specified Role Type, regardless of the type of association they
are in.
The minCardinality attribute specifies
the Minimum Cardinality Facet for the constraint. This attribute
is REQUIRED and its value must be a non-negative integer.
The maxCardinality attribute specifies
the Maximum Cardinality Facet for the constraint. This attribute
is REQUIRED and its value must be either a non-negative integer
or the string value "unbounded" (indicating that there is no
upper limit on this constraint.
This element specifies a single Occurrence Cosntraint that applies to this Topic Type.
The occurrenceTypeRef attribute is
REQUIRED and contains the internal identifier of the Occurrence
Type that is allowed by the Occurrence Constraint. This must
match the value of the id attribute on an occurrenceType element
in the NPCL XML document.
The minCardinality attribute specifies
the Minimum Cardinality Facet for the constraint. This attribute
is REQUIRED and its value must be a non-negative integer.
The maxCardinality attribute specifies
the Maximum Cardinality Facet for the constraint. This attribute
is REQUIRED and its value must be either a non-negative integer
or the string value "unbounded" (indicating that there is no
upper limit on this constraint.
Contains a single typed extension value for the type. The
value is the string content of this element. The type is
specified as a URI in the type attribute of
this elment.
Contains a list of the subclasses of this type. This element structure is described in detail below.
This element describes a single Occurrence Type in the schema. It contains the Datatype, Minimum Value, Maximum Value and Value Pattern Facets that apply to this Occurrence Type.
<npcl:occurrenceType id="..." abstract="true|false"
datatype="..."
minValue="..."
maxValue="..."
valuePattern="...">
<npcl:subjectIdentifier>
SUBJECT IDENTIFIER
</subjectIdentifier>
<npcl:displayName> NAME </npcl:displayName>
<npcl:extension type="...">
...
</npcl:extension>
<npcl:subclasses> ... </npcl:subclasses>
</occurrenceType>
REQUIRED. An internal identifier for the type. This is used only for reference purposes inside the NPCL XML document.
OPTIONAL. A boolean value that indicates if this type is abstract. If not specified, this attribute value defaults to "false".
OPTIONAL. The Datatype Facet value. This attribute specifies the datatype for values of occurences of this type.
OPTIONAL. The Minimum Value Facet value. Specifies the minimum allowed value for occurrences of this type.
OPTIONAL. The Maximum Value Facet value. Specifies the maximum allowed value for occurrences of this type.
OPTIONAL. The Value Pattern Facet value. Specifies a regular expressiong that values of occurrences of this type must match.
REQUIRED, REPEATABLE. Contains a subject identifier URI for the type.
Contains a human-readable display label for the type.
Contains a single typed extension value for the type. The
value is the string content of this element. The type is
specified as a URI in the type attribute of
this elment.
Contains a list of the subclasses of this type. This element structure is described in detail below.
This element describes a single Association Type in the schema. It contains the Association Role Constraints that apply to this Association Type.
<npcl:associationType id="..." abstract="true|false">
<npcl:subjectIdentifier>
...
</npcl:subjectIdentifier>
<npcl:displayName> ... </npcl:displayName>
<associationRoleConstraint
roleTypeRef="..."
minCardinality="..."
maxCardinality="..."
arcLabel="..."/>
<npcl:extension type="...">
...
</npcl:extension>
<npcl:subclasses> ... </npcl:subclasses>
</associationType>
REQUIRED. An internal identifier for the type. This is used only for reference purposes inside the NPCL XML document.
OPTIONAL. A boolean value that indicates if this type is abstract. If not specified, this attribute value defaults to "false".
REQUIRED, REPEATABLE. Contains a subject identifier URI for the type.
Contains a human-readable display label for the type.
Defines a single Association Role Constraint that applies to this Association Type.
The roleTypeRef attribute is REQUIRED
and contains the internal identifier of the Role Type that is
allowed by the Association Role Constraint. This must match the
value of the id attribute on a roleType element in the NPCL XML
document.
The minCardinality attribute specifies
the Minimum Cardinality Facet for the constraint. This attribute
is REQUIRED and its value must be a non-negative integer.
The maxCardinality attribute specifies
the Maximum Cardinality Facet for the constraint. This attribute
is REQUIRED and its value must be either a non-negative integer
or the string value "unbounded" (indicating that there is no
upper limit on this constraint.
The arcLabel attribute specifies the
Arc Label Facet for the constraint. This attribute is OPTIONAL
and its value should be a human-readable label for the
association, when displayed in the context of the player of the
role identified by the roleTypeRef
attribute.
Contains a single typed extension value for the type. The
value is the string content of this element. The type is
specified as a URI in the type attribute of
this elment.
Contains a list of the subclasses of this type. This element structure is described in detail below.
This element describes a single Role Type in the schema.
<npcl:roleType id="..." abstract="true|false">
<npcl:subjectIdentifier>
...
</subjectIdentifier>
<npcl:displayName> ... </npcl:displayName>
<npcl:extension type="...">
...
</npcl:extension>
<npcl:subclasses> ... </npcl:subclasses>
</roleType>
REQUIRED. An internal identifier for the type. This is used only for reference purposes inside the NPCL XML document.
OPTIONAL. A boolean value that indicates if this type is abstract. If not specified, this attribute value defaults to "false".
REQUIRED, REPEATABLE. Contains a subject identifier URI for the type.
REQUIRED. Contains a human-readable display label for the type.
OPTIONAL, REPEATABLE. Contains a single typed extension
value for the type. The value is the string content of this
element. The type is specified as a URI in the
type attribute of this elment.
Contains a list of the subclasses of this type. This element structure is described in detail below.
This element describes a single Scoping Topic in the schema.
<npcl:scopingTopic>
<npcl:subjectIdentifier>
...
</subjectIdentifier>
<npcl:displayName> ... </npcl:displayName>
<npcl:extension type="...">
...
</npcl:extension>
</roleType>
REQUIRED, REPEATABLE. Contains a subject identifier URI for the type.
REQUIRED. Contains a human-readable display label for the type.
OPTIONAL, REPEATABLE. Contains a single typed extension
value for the type. The value is the string content of this
element. The type is specified as a URI in the
type attribute of this elment.
This element is allowed as a direct child of the abstractType, topicType, occurrenceType, associationType and roleType elements. It contains a list of all of the subclasses of the type defined by the parent element.
<npcl:subclasses>
<subclass direct="true|false" classRef="..."/>
</subclasses>
References a single subclass of the type.
The direct is OPTIONAL and indicates
whether the referenced type is a direct subclass of this type or
if it is an indirect subclass (a subclass of a direct subclass
of the type). For importing and schema parsing, only direct
subclasses are considered - indirect subclasses are optionally
provided when exporting an NPCL schema for processing
convenience. If omitted, the value defaults to 'true'.
The classRef attribute is REQUIRED and
references the type that is a subclass of this type. The value
of this attribute must be the value of the id attribute of an
abstractType, topicType, occurrenceType, associationType or
roleType element in the NPCL XML document.
The NPCL Forms XML Schema provides an alternate XML representation of a set of NPCL types and constraints. This representation has been optimised for generating topic-oriented user interfaces such as forms interfaces for topic editing. The focus of this schema is on the topic types and the information that can be added to a topic of a particular type. A more generalized XML representation is provided by the NPCL XML Schema. This section describes the NPCL Forms XML Schema in detail. The W3C XML Schema representation is also included in the TMCore distribution and can be downloaded from the NetworkedPlanet website.
The namespace used for NPCL XML Schema is http://www.networkedplanet.com/schema/npcl-forms. In the examples in the rest of this section, this namespace is assumed to be mapped to the namespace prefix "nf".
The schema element is the root element for an
NPCL Forms XML document. The element has the following syntax:
<nf:schema> <nf:topicType ... > ... </nf:topicType> ... </nf:schema>
The root element of an NPCL Forms XML instance.
Contains the schema information required to build a forms interface for a single topic type in the NPCL schema. This element is OPTIONAL and REPEATABLE.
An extension point in the NPCL Forms XML Schema which
allows any number of elements from any namespace other than the
NPCL Forms XML Schema namespace to appear after all
topicType elements.
The topicType element contains the schema
information relating to a single topic type in the NPCL schema. This
element has the following syntax:
<nf:topicType id="..." isAbstract="true|false"> <nf:subjectIdentifier> PSI </nf:subjectIdentifier> <nf:displayName> NAME </nf:displayName> <nf:extension ... > ... </nf:extension> <nf:occurrenceField ... > ... </nf:occurrenceField> <nf:associationField ... > ... </nf:associationField> ... </topicType>
Contains the ID value for the topic type described by this element. If the forms schema is being retrieved from a topic map stored inside a TMCore database, then the value of this attribute will be the database OID of the topic that defines the topic type.
A boolean value that indicates if the topic type described by this element is marked in the schemas a being abstract. Typically a GUI should not allow end-users to create instances of topic types that are marked as abstract.
Contains a single subject identifier for this topic type. This element is OPTIONAL and REPEATABLE.
Contains a displayable name for the topic type. This element is OPTIONAL and NON-REPEATABLE.
Contains a single schema extension value for the topic type. Extension values allow additional constraint or display information to be communicated to applications using the NPCL schema extension mechanism. This element is OPTIONAL and REPEATABLE.
Contains schema information that constrains creation of occurrences of a specific type on topics of this type. This element is OPTIONAL and REPEATABLE.
Contains schema information that constrains the creation
of associations between topics of this type and other topics in
the topic map. Each associationField element
describes the constraints applying to a particular type of role
that can be played by topics of this type, or a particular role
type and parent association type combination. This element is
OPTIONAL and REPEATABLE
An extension point in the NPCL Forms XML Schema which
allows any number of elements from any namespace other than the
NPCL Forms XML Schema namespace to appear as the last child
elements of a topicType element.
The extension element provides extension
values from the NPCL schema. Each extension value is typed using a URI
type identifier. The extension element has the following
syntax:
<nf:extension type="URI" > VALUE </nf:extension>
Contains the URI identifier for the extension type. The value of this attribute is any URI.
The text content of the extension
element is the extension value expressed as a string.
The occurrenceField element contains the schema information
required to create a form field for adding new occurrence value of a
specific type to a topic. The topic type is defined by the parent
topicType element. The element has the following
syntax:
<nf:occurrenceField id="..."
minCardinality="MINCARD"
maxCardinality="MAXCARD"
datatype="DATATYPE"
minValue="MIN"
maxValue="MAX"
valuePattern="PATTERN"
>
<nf:subjectIdentifier> PSI </nf:subjectIdentifier>
<nf:displayName> NAME </nf:displayName>
<nf:extension ... > ... </nf:extension>
...
</nf:occurrenceField>Contains the ID of the occurrence type that gives rise to this occurrence field. If the schema is stored in a topic map in a TMCore database, then the value of this attribute is the OID of the topic that defines the occurrence type.
Specifies the lower limit to the number of times an occurrence of this type should appear on an instance of the topic type. This attribute is REQUIRED and its value must be a non-negative integer.
Specifies the upper limit to the number of occurrences of this type that should appear on an instance of the topic type. This attribute is REQUIRED and its value must be either a non-negative integer or the string "unbounded" to indicate that there is no upper limit.
Specifies the datatype that the occurrence value must conform to. This attribute is OPTIONAL. The attribute value can be any string, but it is RECOMMENDED that only W3C XML Schema data types should be referenced, using the full URI for the datatype as defined by the W3C XML Schema specification.
Specifies the minimum value that the occurrence value must
match or exceed. This attribute is OPTIONAL and is only used
when the datatype attribute has been defined
and the data type referenced by the datatype
attribute is a scalar attribute. The value of this attribute
must conform to the lexical form of the data type specified by
the datatype attribute.
Specifies the maximum value that the occurrence value must
be less than or equal to. This attribute is OPTIONAL and is only
used when the datatype attribute has been
defined and the data type referenced by the
datatype attribute is a scalar attribute. The
value of this attribute must conform to the lexical form of the
data type specified by the datatype
attribute.
Specifies the regular expression that the occurrence value must match. This attribute is OPTIONAL.
Contains a single subject identifier for the occurrence type. This element is OPTIONAL and REPEATABLE.
Contains the human-readable display name for the occurrence type. This element is OPTIONAL and NON-REPEATABLE.
Contains a single NPCL schema extension value for the topic occurrence constraint that binds the occurrence type to this topic type or for the occurrence type itself. This element is OPTIONAL and REPEATABLE.
An extension point in the NPCL Forms XML Schema which
allows any number of elements from any namespace other than the
NPCL Forms XML Schema namespace to appear as the last child
elements of an occurrenceField
element.
The associationField element contains the
schema information required to create a form field for specifying a
relationship between an instance of the topic type defined by the
parent topicType element and other topics in the
topic map. The associationField element has the
following syntax:
<nf:associationField>
<nf:associationType id="...">
<nf:subjectIdentifier> PSI </nf:subjectIdentifier>
<nf:displayName> NAME </nf:displayName>
<nf:extension ... > ... </nf:extension>
</nf:associationType>
<nf:thisRole id="..."
minCardinality="MINCARD"
maxCardinality="MAXCARD">
<nf:subjectIdentifier> PSI </nf:subjectIdentifier>
<nf:displayName> NAME </nf:displayName>
<nf:extension ... > ... </nf:extension>
<nf:rolePlayerType id="..."
isAbstract="true|false"
minCardinality="MINCARD"
maxCardinality="MAXCARD"
associationSpecificCardinality="true|false">
<nf:subjectIdentifier> PSI </nf:subjectIdentifier>
<nf:displayName> NAME </nf:displayName>
<nf:extension ... > ... </nf:extension>
</nf:rolePlayerType>
</nf:thisRole>
<nf:otherRole id="..."
minCardinality="MINCARD"
maxCardinality="MAXCARD">
<nf:subjectIdentifier> PSI </nf:subjectIdentifier>
<nf:displayName> NAME </nf:displayName>
<nf:extension ... > ... </nf:extension>
<nf:rolePlayerType id="..."
isAbstract="true|false"
minCardinality="MINCARD"
maxCardinality="MAXCARD"
associationSpecificCardinality="true|false">
<nf:subjectIdentifier> PSI </nf:subjectIdentifier>
<nf:displayName> NAME </nf:displayName>
<nf:extension ... > ... </nf:extension>
</nf:rolePlayerType>
</nf:otherRole>
...
</nf:associationField>Contains information about the association type for the relationship. This element is REQUIRED and NON-REPEATABLE
Each associationField element
specifies the roles and role players for one association type
/ role type binding for the topic type. NPCL allows a topic to
be constrained to be a role player in a specific role type
without specifying which association type that role must be in
- in such cases, a complete NPCL Forms document will list all
possible combinations of that role type and association types
that allow that role type to occur as separate
associationField elements.
Contains the ID of the association type that gives rise to this field. If the schema is stored in a topic map in a TMCore database, then the value of this attribute will be the OID of the topic that defines the association type.
Contains a single subject identifier URI for the association type. This element is OPTIONAL and REPEATABLE.
Contains a display label for the association type. This element is OPTIONAL and NON-REPEATABLE.
Contains a single NPCL schema extension value for the association type. This element is OPTIONAL and REPEATABLE.
Contains the schema information for the type of role that can be played by this topic type. This element is REQUIRED and NON-REPEATABLE.
Contains the ID of the role type that is played by this topic type. If the schema is stored in a topic map in a TMCore database, the value of this attribute will be the database OID of the topic that defines the role type.
Specifies the lower bound on the number of times an
instance of the topic type must play the role defined by the
parent thisRole element. This attribute is
REQUIRED and its value must be a non-negative integer.
Specifies the upper bound on the number of times an
instance of the topic type must play the role defined by the
parent thisRole element. This attribute is
REQUIRED and its value must be either a non-negative integer or
the string "unbounded" to indicate that there is no upper
bound.
A boolean field that indicates if the cardinality values
specified by the minCardinality and
maxCardinality attribute apply to any
association in which the topic plays the type of role defined by
the thisRole element (when the attribute
value is 'false'), or only to the associations of the type
defined by the associationType element in
which the topic plays the type of role defined by the
thisRole element (when the attribute value is
'true'). This attribute is OPTIONAL and if not present defaults
to the value 'false'.
Contains a single URI subject identifier for this role type. This element is OPTIONAL and REPEATABLE.
Contains a display label for the role type. This element is OPTIONAL and NON-REPEATABLE.
Contains a single NPCL schema extension value for this role type. This element is OPTIONAL and REPEATABLE.
Contains the schema information for one of the types of
topic that can play the role type defined by the parent
thisRole element. This element is REQUIRED
and REPEATABLE.
Contains the ID of the topic type that is described by
this rolePlayerType element. If the schema is
stored in a topic map in a TMCore database then the value of
this attribute will be the database OID of the topic that
defines the topic type.
Contains a boolean value indicating if the topic type
described by this rolePlayerType element is
marked as abstract in the schema.
Specifies the lower bound on the number of times an
instance of this role player topic type must play the role
defined by the parent thisRole element. This
attribute is REQUIRED and its value must be a non-negative
integer.
Specifies the upper bound on the number of times an
instance of this role player topic type must play the role
defined by the parent thisRole element. This
attribute is REQUIRED and its value must be either a
non-negative integer or the string "unbounded" to indicate that
there is no upper bound.
A boolean field that indicates if the cardinality values
specified by the minCardinality and
maxCardinality attribute apply to any
association in which the topic plays the type of role defined by
the parent thisRole element (when the
attribute value is 'false'), or only to the associations of the
type defined by the ancestor associationType
element in which the topic plays the type of role defined by the
parent thisRole element (when the attribute
value is 'true'). This attribute is OPTIONAL and if not present
defaults to the value 'false'.
Contains a single URI subject identifier for this role player topic type. This element is OPTIONAL and REPEATABLE.
Contains a single displayable label for this role player topic type. This element is OPTIONAL and NON-REPEATABLE.
Contains a single NPCL schema extension value for the role player topic type. This element is OPTIONAL and REPEATABLE.
Contains the schema information for one of the other types of role allowed on the association. This element is OPTIONAL and REPEATABLE.
Specifies the lower bound on the number of times a role of this type may appear in the association. This attribute is REQUIRED and its value must be a non-negative integer.
Specifies the upper bound on the number of times a role of this type may appear in the association. This attribute is REQUIRED and its value must be either a non-negative integer or the string "unbounded" indicating that there is no upper bound.
Contains a single URI subject identifier for this role type. This element is OPTIONAL and REPEATABLE.
Contains a display label for the role type. This element is OPTIONAL and NON-REPEATABLE.
Contains a single NPCL schema extension value for this role type. This element is OPTIONAL and REPEATABLE.
Contains the schema information for one of the types of
topic that can play the role type defined by the parent
otherRole element. This element is REQUIRED
and REPEATABLE.
Contains the ID of the topic type that is described by
this rolePlayerType element. If the schema is
stored in a topic map in a TMCore database then the value of
this attribute will be the database OID of the topic that
defines the topic type.
Contains a boolean value indicating if the topic type
described by this rolePlayerType element is
marked as abstract in the schema.
Specifies the lower bound on the number of times an
instance of this role player topic type must play the role
defined by the parent otherRole element. This
attribute is REQUIRED and its value must be a non-negative
integer.
Specifies the upper bound on the number of times an
instance of this role player topic type must play the role
defined by the parent otherRole element. This
attribute is REQUIRED and its value must be either a
non-negative integer or the string "unbounded" to indicate that
there is no upper bound.
A boolean field that indicates if the cardinality values
specified by the minCardinality and
maxCardinality attribute apply to any
association in which the topic plays the type of role defined by
the parent otherRole element (when the
attribute value is 'false'), or only to the associations of the
type defined by the ancestor associationType
element in which the topic plays the type of role defined by the
parent otherRole element (when the attribute
value is 'true'). This attribute is OPTIONAL and if not present
defaults to the value 'false'.
Contains a single URI subject identifier for this role player topic type. This element is OPTIONAL and REPEATABLE.
Contains a single displayable label for this role player topic type. This element is OPTIONAL and NON-REPEATABLE.
Contains a single NPCL schema extension value for the role player topic type. This element is OPTIONAL and REPEATABLE.
An extension point in the NPCL Forms XML Schema that
allows any number of elements from other namespaces to appear as
the last children of an associationField
element.
This schema is used to return results from operations which perform a single transactional update or a set of transactional updates on one or more topic maps. For operations invoked over SOAP, the results description document will be returned in the body of the SOAP response message. For operations invoked against ASP.NET pages directly, the result document will be contained in the body of the HTTP response.
The structure of the results document is as follows.
<res:results containsError="true|false">
<res:result ... >
...
</res:result>
</res:results>A boolean flag that is set to true if at least one of the transactions failed, and true if and only if every transaction succeeded. This attribute is REQUIRED.
Contains the detailed result information for a single transaction. The syntax of this element is as described below.
Each res:result element reports the status of a
single transaction performed during the request processing. The optional
key attribute on this element allows the result
description to be correlated to one of the transactions in the request.
Each res:result element has has the following
structure:
<res:result isError="true|false">
<res:error code="CODE" key="KEY">
<res:message> ERROR MESSAGE </res:message>
<res:action role="ROLE"> ACTION MESSAGE </res:action>
<res:cause>
<res:message> EXCEPTION MESSAGE </res:message>
<res:type> EXCEPTION TYPE </res:type>
<res:stacktrace> EXCEPTION STACK </res:stacktrace>
</res:cause>
...
</res:error>
...
</res:result>Contains a string value that can be used to correlate the result report to part of the operation request. The precise way in which this is achieved is operation-specific and described in the operation definition. This attribute is OPTIONAL, and may be omitted if the result is for a single transaction.
Contains a boolean flag that is set to true if the operation is reporting an error. This attribute is OPTIONAL and defaults to false.
Wrapper element for reporting detail on an error that
occurred in the processing of the operation. This element is
OPTIONAL. It SHOULD be present if the isError
attribute of the parent res:result element is
set to true, it SHOULD NOT be present if the
isError attribute of the parent res:result
element is set to false.
Contains the error code for the error being reported. Error codes are service-specific and defined as part of the service description. The error code is specified in this attribute as a string value. This attribute is REQUIRED.
Contains an error message for the error being reported. This element is OPTIONAL.
The text contained in this element describes the action(s) that can be taken to resolve the reported error.
This attribute identifies which user role can perform the corrective action described in the content of the element. This attribute has two allowed value. If the value is 'user', then the action can be performed by the user who issued the request. If the value is 'admin' then the corrective action requires administrative intervention on the server.
This OPTIONAL element describes the underlying exception that caused the process to fail. This element provides additional detail which can be helpful in determining the cause of certain errors.
Contains the message reported by the exception that caused the process to fail.
Specifies the type of exception that caused the process to fail.
Contains the stack trace of the exception that caused the process to fail.
Any number of elements from any other namespace may appear
after the res:message element. This may be used
by services to convey additional detailed error information (such
as a stack trace or debug output) to the caller.
Any number of elements from any other namespace may appear
as the last children of the res:result element.
This may be used by services to convey additional detailed
response information (such as performance statistics). This
extension point SHOULD NOT be used to convey detailed error
information - instead the extension point inside the
res:error element should be used.