Getting Started writing k42 Applications

This documents contains a quick guide to writing k42 applications in Java. It demonstrates the use of the com.empolis.topicmaps.helper.Builder class, which abstracts the k42 API to provide simple methods for creating topicmaps.

This document should be read prior to the developer guide which contains a description of using the k42 API.

Getting Started writing k42 Applications

Writing a k42 client application has been specifically designed to be as painless as possible. A single application, if written correctly, will not require recompilation for running on remote or local k42 servers, and will work with future versions of k42.

All the code shown in this document may be found in the %K42_HOME%\docs\files folder.

Program Template

The following template may be re-used for writing k42 client programs.

import com.empolis.topicmaps.client.K42Client;
import com.empolis.topicmaps.helper.Builder;
import com.empolis.topicmaps.ik42.*;

public class K42Template {

  public static void main(String[] args) {

    if (args.length<1) {
      System.err.println("Please supply the name of a properties " +
        "file as a command line argument.");
      System.exit(0);
    }

    K42Client client = new K42Client(args[0]);

    try {
      ITopicMap tm = client.getTopicMap();
      Builder builder = new Builder(tm);

      // k42 client code goes here
      System.out.println("K42 ready to go!");

      } finally {
        client.shutdown();
      }
    }
}

This code may be found in the K42Template.java file.

Compiling and Executing the Template Program

Compiling

This code will compile using the javac standard Java compiler, as provided in the JDK. To compile, execute:

javac K42Template.java

ensuring that the k42 jars are on the classpath.

These jars may found in the %K42_HOME%\lib directory. To quickly add all of these jars to your classpath, execute:

k42 env

Starting the k42 Application Server

Before executing the example, you must first start a k42 Application Server. For full instructions on how to do this, please refer to the installation guide. If k42 is configured correctly, then executing:

k42 start

should start k42.

Executing the program template

To execute the K42Template program run:

java K42Template k42client.props

where k42client.props is the filename of a property file found in the current directory which contains properties for connecting to k42. A sample k42client.props file has been provided in the %K42_HOME%\docs\files directory which connects to a k42 Application Server running on the same machine. The contents of this property file are shown here:

empolis.rmiserver=rmi://127.0.0.1:1099/TopicMapServer

If all is correct, then the following output will appear:

[c:\k42\docs\files]java K42Template k42client.props
K42 ready to go!

What can go wrong?

If you didn't receive the "K42 ready to go!" message and an exception was thrown, then here are some of the common causes:

Error	Cause	Solution
java.rmi.ConnectException: Connection refused to host: 127.0.0.1	The k42 Application Server is not active, or is not available.	Ensure that k42 is running and initialised correctly. Consult the installation guide for troubleshooting the k42 application server.
Exception in thread "main" java.lang.NoClassDefFoundError: com/empolis/gdo/client/OMClient	Your classpath is not set correctly.	Execute `k42 env` to set up your classpath environment variable to include all the k42 jars.
java.io.FileNotFoundException: propfile (The system cannot find the file specified)	You may have misspelled the property file name on the java command line, or the property file doesn't exist.	Correct the name, or create the property file.

Available Methods in the Builder

Method	Purpose
`createTopic`	Creates a new topic in the topicmap.
`assertTopic`	Asserts that a topic is in the topicmap. If the topic does not exist in the map, it is created.
`createAssociationTemplate`	Creates a new topic association template.
`createAssociationInstance`	Creates a new instance of a topic association template.
`addOccurrenceToTopic`	Adds an occurrence to a topic.

Each of these methods has been overloaded to allow the developer the most flexibility in creating a topicmap. Each method will now be described in detail.

createTopic

The following prototypes are provided:

public ITopic createTopic(String name);
public ITopic createTopic(String name, Object superclass, Object p_instanceof);
public ITopic createTopic(String name, Object[] superclasses, Object[] instancesof);

This method creates a new topic in the topicmap. The most simple form of topic is a topic with no superclasses and that is not an instance of any other topic. To create such a topic use: createTopic(String). The other two methods allow the user to specify either single or multiple (arrays) of topics to use as superclasses or topics to become aninstanceof.

If a topic with this name already exists in the map, then a com.empolis.topicmaps.k42.K42Exception will be thrown.

Note that the ITopic interface allows the addition of superclasses and instanceof relationships after creation time.

assertTopic

The signatures for assertTopic are the same as those for createTopic, except that the semantics of assertTopic are such that the builder will not attempt to call createTopic if the topic already exists in the map.

createAssociationTemplate

The following prototypes are provided:

public ITopicAssociation createAssociationTemplate(String templateName,
      String role1, String type1, String relationship1,
      String role2, String type2, String relationship2);

public ITopicAssociation createAssociationTemplate(String templateName,
      ITopic role, ITopic type);

public ITopicAssociation createAssociationTemplate(String templateName,
      Object roles[], Object types[], String relationships[]);

public ITopicAssociation createAssociationTemplate(String templateName, 
      ITopic role1, ITopic type1, String relationship1, 
      ITopic role2, ITopic type2, String relationship2);

This method is the most complex in the builder. It allows the user to create association templates with 1 or more ends. The simplest type of association is where the association template only has one end. To create this, use:

public ITopicAssociation createAssociationTemplate(String templateName,
      ITopic role, ITopic type);

where the role parameter is the name of the role defining topic and the type parameter is the class of role playing topic (as described in the k42 concepts document).

To create a association template that has 2 ends (this is the most common form of template), use the

public ITopicAssociation createAssociationTemplate(String templateName,
      String role1, String type1, String relationship1,
      String role2, String type2, String relationship2);

method. This method allows the user to specify arc labels in addition to the role and type parameters. To best clarify this method, here is an example using the topics, described in the concepts document.

ITopicAssocation ass = createAssociationTemplate("Computer has Owner",
    "owner", "person", "owns",
	 "owned", "computer", "is owned by");

This describes the association template that a computer has an owner. This template may then be instantiated to link an instance of a person topic with an instance of a computer topic. Note that this method is identical in semantics to the method that takes ITopic instances for roles and types, but is more efficient if those topics are available in the code.

The final method:

public ITopicAssociation createAssociationTemplate(String templateName,
      Object roles[], Object types[], String relationships[]);

is complex. This allows the creation of association templates with arbitrary numbers of ends. As this method is rarely required, it is not described here. For a complete description of how to populate the array parameters for this method, please refer to the API documentation for this method.

createAssociationInstance

The following prototypes are provided:

public ITopicAssociation createAssociationInstance(Object template, Object player1, Object player2);
public ITopicAssociation createAssociationInstance(Object template, Object[] players);

The first, most commonly used method, is to create association template instances that have two ends. A simple example call would be:

builder.createAssociationInstance("Computer has Owner", "Andy", "Spectrum");

If invalid parameters are specified then a K42Exception will be thrown. Note that the prototype of this method allows any object to be passed as a role playing topic. If the object passed is an ITopic instance, then that topic will be used, otherwise the method calls the toString() method on the object to obtain a name to look up in the topicmap to use as that role playing topic.

The other method simply allows arrays of role playing topics be used. Note that a mixture of ITopic and other types of object may be passed in the array.

addOccurrenceToTopic

This method only has a single prototype:

public ITopic addOccurrenceToTopic(Object topic, String resource, Object resourceType);

which allows the user to add an occurrence to a topic. The occurrence itself is typed by a topic, passed as the resourceType parameter. The resource parameter is a string that can be resolved by an application to obtain the resource. This is most commonly a URI, but it may be any string which an application that uses the topicmap will be able to resolve.

Summary

For complete documentation on all these methods, please refer to the API documentation. The builder provides an easy way to start creating topicmaps, and is not a complete API for manipulating topicmaps. All the objects returned by the builder are part of the k42 model and can be directly manipulated by the k42 API.