IndexAPI example

This is an example of how to work with the IndexAPI. This TMAPI program creates a topic map from a directory and all its subdirectories. For each file a "file" topic is being created. For each directory a "directory" topic is created and a "parent-child" association. This association contains two association roles, the directory topic with type "parent" and the file topic with type "child".

Every file with an extension (eg. Topic.java) is also typed by a topic that describes the extension. To assign the right extension type to a "file" topic, the org.tmapi.index.core.TopicsIndex is needed to look up, if a topic for this extension was already created.

After creating the filesystem topic map. The above mentioned index is also used to print out all filetypes and all files of type "java".

The directory to be parsed can be defined by an argument to this example. This example can be found in the file examples/example2.java

Example 2. Use the IndexAPI

    	[0]  import org.tmapi.index.core.TopicsIndex;
    	...
        [1]  tm 		=	tSystem.createTopicMap("http://www.tmapi.org/examples/filetm");        
        [2]  tIndex = (TopicsIndex) tm.getHelperObject(org.tmapi.index.core.TopicsIndex.class);
        
        [3]  directory = tm.createTopic();
        [4]  directory.createTopicName("Directory",null);
        [5]  directory.addSubjectIdentifier(tm.createLocator("http://www.tmapi.org/examples/directory"));
        
        [6]  file = tm.createTopic();
        [7]  file.createTopicName("File",null);
        [8]  file.addSubjectIdentifier(tm.createLocator("http://www.tmapi.org/examples/file"));
	...
	...
	

To use the IndexAPI, the org.tmapi.index.core.* package must to be imported. Line one is similiar to the last example, it just creates the topic map. In line 2 the org.tmapi.index.core.TopicsIndex is created. If you want to read more about how to work with an index, please have a look at the section the section called “The Index and IndexFlags Interfaces” Line 3-5 creates a topic with the topic name "Directory" and the SubjectIdentifier "ttp://www.tmapi.org/examples/directory" Line 6-8 also creates another topic, which is needed in this example.

Note

The better way to create all typing topics and all other topics, that are needed for a programs ontology, is to write a "seed" LTM or XTM file and use the tmapi-utils parser (see next chapter) to create them.

Note

For this example it is very important, that the feature "http://tmapi.org/features/merge/byTopicName" is switched off. That means, no merging is done by topic name. Please have a look at the default value of TMAPI implementation you are using. The best way to handle all TMAPI implementations is to set all features yourself. Please have a look at the section Step 2 for further information.

After creating all typing topics that are needed for this example, we have a look at the core method public Topic readDirectory(File d).

        [9]  public Topic readDirectory(File d){
	[10]   //recursion anchor
	[11]    if(d.isFile()==true){
	[12]        Topic fileT = tm.createTopic();
	[13]        fileT.createTopicName(d.getName(),null);
	[14]        Locator pathLoc = tm.createLocator(d.toURI().toString());
	[15]        fileT.addSubjectLocator(pathLoc);
	[16]        fileT.addType(file);

	[17]        int dotpos = d.getName().lastIndexOf('.');
	[18]        if(dotpos!=-1){
	[19]            String extension =d.getName().substring(++dotpos);
	[20]	        fileT.addType(getExtensionTopic(extension));
	[21]        }
	[22]        return(fileT);
	[23]    }	
	

This section of this method, deals with all files. For each file a topic is being created. On line 12 and line 13 the topic name is set to the filename. Line 14 creates a locator, which contains the whole path for this file for example "file:/home/tmapi/build.xml". This locator is used for the subject locator on line 15. The "file" topic created in the section above is needed in line 16 as typing topic for this file topic.

If the file has any extension (line 17-19) another type is added, which is determined by the method getExtensionTopic(String extension) in line 20.

	[24]    public Topic getExtensionTopic(String extension){
	[25]	Topic extT=null;
	[26]	try{
	[27]	    //search Topic with a SubjectIdentifier http://www.tmapi.org/examples/extensions#{extension}
	[28]	    if(tIndex.getFlags().isAutoUpdated()==false)
	[29]		tIndex.reindex();
	[30]	    Locator subjIdent = tm.createLocator("http://www.tmapi.org/examples/extensions#"+extension);
	[31]	    extT = tIndex.getTopicBySubjectIdentifier(subjIdent);
	[32]	    if(extT==null){
	[33]		extT = tm.createTopic();
	[34]		extT.addSubjectIdentifier(subjIdent);
	[35]		extT.createTopicName("Filetype : "+extension,null);
	[36]	    }
	[37]	}catch(TMAPIIndexException e){
	[38]	    e.printStackTrace();
	[39]	}
	[40]	return extT;
	[41]    }	
	

On this section we take a look at the method getExtensionTopic(String extension), which uses the org.tmapi.index.core.TopicsIndex to lookup whether a topic for a given extension (e.g "txt", "java", ...) was already created. If such a topic does not exists, a topic with a subject identifier http://www.tmapi.org/examples/extensions#{extension} is created.

In line 28 and 29 the index is updated, for further information please have a look at the section called “The Index and IndexFlags Interfaces”. A locator for the given extension is created on line 30. This locator is used with the method TopicsIndex.getTopicBySubjectIdentifier(Locator loc) to retrieve the topic with this subject identifier. If this topic does not exist (line 32), a topic is created (33), the subject identifier is set(34) and a topic name is added(35). In line 40 the extension topic is returned.

Now lets come back to the core method public Topic readDirectory(File d) 2 Sections above we discussed, what happens if a file comes in, now we have a look, what happens if a directory comes in.

	[42] if(d.isDirectory()==true){
        [43]    Topic dirT = tm.createTopic();
        [44]    dirT.createTopicName(d.getName(),null);
        [45]    dirT.addType(directory);
        [46]    Locator pathLoc = tm.createLocator(d.toURI().toString());
        [47]    dirT.addSubjectLocator(pathLoc);
        [48]    //recurse and create assocs
        [49]    File[] files = d.listFiles();
        [50]    if(files.length>0){
        [51]        Association dirA = tm.createAssociation();
        [52]        dirA.setType(parent_child);
        [53]        dirA.createAssociationRole(dirT, parent);
        [54]        for(int i=0;i<files.length;i++){
        [55]            Topic player = readDirectory(files[i]);
        [56]            if(player!=null)
        [57]                dirA.createAssociationRole(player,child);
        [58]        }
        [59]    }
        [60]    return(dirT);
        [61] }	
	

For each directory a topic is created (43) typed with the "directory" topic(45) created in the beginning. This topic gets a subject locator(47), which represents the path of this directory(46). If the directory contains any files (49,50) an association is being created (51) with type "parent-child"(52). The directory itself is added as a role player with the type "parent". In the lines 54-58 all files in this directory are added as role players to this association with the "child" type(57). In line 55 a recursive call to this method delivers a topic for this file.

After creating the topic map from the given directory, we want to use the org.tmapi.index.core.TopicsIndex to print out all used topic types. In our topic map all the extension topics are typing topics.

	[62]  public void printTypes(){
	[63]	Iterator it = tIndex.getTopicTypes().iterator();
	[64]	System.out.println("TopicTypes :");
	[65]	while(it.hasNext()){
	[66]	    Topic t = (Topic)it.next();
	[67]	    printTopicNames(t);
	[68]	    System.out.println();
	[69]	}
	[70]  }	
	

In line 63 the method TopicsIndex.getTopicTypes() is used to get all topics, that are used as typing topics. Lines 65-69 just print them out.

	[71]  public void printAllJavaFiles(){
	[72]	Locator javaLoc = tm.createLocator("http://www.tmapi.org/examples/extensions#java");
	[73]	Topic javatopic = tIndex.getTopicBySubjectIdentifier(javaLoc);
	[74]	if(javatopic==null){
	[75]	    System.out.println("Sorry, you don't have any Java files in your directory");
	[76]	    return;
	[77]	}
	[78]	Iterator it = tIndex.getTopicsByType(javatopic).iterator();
	[79]	System.out.println("All Java files :");
	[80]	while(it.hasNext()){
	[81]	    Topic t = (Topic)it.next();
	[82]	    printTopicNames(t);
	[83]	    System.out.println();
	[84]	}
	[85]  }
    

This method prints out all file topics, that are typed by a java extension topic. That means, all java files are printed.

Therefore in line 72 a locator is created with the style used in this topic map. line 73 uses the method TopicsIndex.getTopicBySubjectIdentifier(Locator) to retrieve the topic which has this subject identifier. If we do not get the java extension topic(74-77), than there was no java extension topic created. That means, there was no java file in the given directory.

Line 78 uses the method TopicsIndex.getTopicsByType(Topic typetopic) which gets all topics, that are typed by the given topic. Line 80-84 just print them.

Now a TMAPI implementation has to be choosen, to run this example. Cause of the Lookup Procedure for TopicMapSystemFactory Implementations, you just have to add the Jar of the TMAPI implementation to the Classpath.

Procedure 2. Compile and execute the example

  1. Compiling

    Go to the examples directory and enter the following command

    javac example2.java -classpath "..\tmapi-1_0.jar"

  2. Execution with tinyTIM

    java -classpath ".;..\tmapi-1_0.jar;{tinyTIM_Directory}\tinyTIM-1_0.jar" example2 ..

    The Classpath contains the actual directory "." where the example1.class is located. It also contains the "tmapi-1_0.jar" from the parent directory. The last jar in the Classpath is the jar of the TMAPI implementation, in this case it is the "tinyTIM-1_0.jar" from the {tinyTIM_Directory}.

    The parameter after example2 ".." defines the directory to be parsed and converted to a topic map. In this case it is the parent directory.

  3. Execution with TM4J

    java -classpath ".;..\tmapi-1_0.jar;{TM4J}\tm4j-tmapi-x.x.x.jar;{TM4J}\tm4j-x.x.x.jar;{TM4J}\resolver.jar;{TM4J}\commons-logging.jar;{TM4J}\mango.jar" example2

    The Classpath contains the actual directory "." where the example2.class is located. It also contains the "tmapi-1_0.jar" from the parent directory. The remaining jars are required for the TM4J implementation.

    The parameter after example2 ".." defines the directory to be parsed and converted to a topic map. In this case it is the parent directory.