Examples

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>

Warning

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>