[Tm4j-developers] TopicMapUtils.getTopicByIdentity

[Conal T. <Con...@vu...>]

I'm implementing the getTopicsByIdentity method of TopicMapUtils, and
I'm puzzled about the "identity" parameter.

From the interface:

/**
 * getTopicsByIdentity
 * Gets the Topic objects which have the specified identity.
 * Note that a Topic Map implementation may return only one Topic or a
number
 * of Topics, depending on whether Topics are early-merged or
late-merged.
 * @param identity The topic identity to be searched for
 * @return The collection of all Topics which have the specified
identity.
 */
public Collection getTopicsByIdentity(String identity);

The method returns a Collection rather than a single Topic because of
the possibility of dynamic merging. In that sense this method should be
roughly equivalent to
TopicMap.getTopicBySubjectIndicator(identity).getMergedTopics() I think.

Fair enough, but what puzzles me is the "identity" parameter. It's a
string, and it appears to be intended as a representation of a subject
indicator (rather than a topic ID). It ought to be converted into a
Locator I think, but according to what notation? Is it intended to be
always interpreted as a URI?=20

I consulted the source of the memory.TopicMapUtilsImpl class and found
that the implementation used a linear search over all the topics in the
map (ouch!), checking each Topic to see if getSubjectIndicators()
contained the identity String. This seems odd to me since the Collection
returned by getSubjectIndicators should contain Locator objects, none of
which could equal the String. I also checked the Ozone implementation,
but I couldn't understand it :-)

So my (draft) implementation assumes that the "identity" parameter is a
subjectIndicator in URI notation:

public Collection getTopicsByIdentity(String identity) {
	try {
		Locator subjectIndicator =3D topicMap.getLocatorFactory().
			createLocator("URI", identity);
		Topic topic =3D
topicMap.getTopicBySubjectIndicator(subjectIndicator);
		if (topic =3D=3D null)
			return Collections.EMPTY_SET;
		else
			return Collections.singleton(topic);
	} catch (LocatorFactoryException lfe) {
		throw new TopicMapRuntimeException(lfe);
	}
}

NB "topicMap" is a member variable of my TopicMapUtilsImpl. Also since
our implementation doesn't support dynamic merging we always return a
Collection with 0 or 1 members.

What do you think?

Cheers!

Con