Package org.tm4j.topicmap.utils.extractors

Provides reusable and composable functions for retrieving information from a variety of topic map constructs.

See:
Description

Class Summary

AssociatedTopicsExtractor	An extractor which returns a list of all topics associated with the input topic with an optionally specified association type and role specs for the the input topic and its associated topic.
AssociationExtractor	An unary function which takes a Member object as input and returns the parent Association object as output.
AssociationGroupsExtractor	An extractor which returns a Map of AssociationGroup objects which represent all the associations of a specific type in which the topic plays a specific role.
AssociationNameExtractor	This class implements both a BinaryFunction and a UnaryFunction that return a name string for an Association instance.
BaseNamesExtractor	An extractor which takes a Topic instance as input and returns the Collection of BaseNames of that Topic as output.
BaseTopicExtractor	Extractor that returns the base topic of the input object if and only if the input object implements the Topic interface.
ExtractorBase	Provides an abstract base class for extractors.
MembersExtractor	An extractor which takes an Association instance as input and returns the Collection of Members in that Association as output.
OccurrencesExtractor	This is a UnaryFunction that retrieves a Collection of Occurrence from a Topic.
PlayersExtractor	An extractor which takes a Member instance as input and returns a Collection of the Topics which are role players in that Member instance as Output.
RefiedObjectExtractor	An extractor which takes a Topic instance as input and returns the TopicMapObject which the Topic reifies or null if this Topic does not reify any object in the TM
ReifyingTopicExtractor	An extractor which takes a TopicMapObject instance as input and returns the Topic which reifies it or null
ScopeExtractor	An extractor function which takes a ScopedObject instance as input and returns the collection of Topic instances that define the scope of the object as output.
SizeExtractor	Extracts an integer representing the size of the input object If the input object is a collection, returns the count of the number of objects contained in the collection.
TopicNameExtractor	An extractor function which takes a Topic as input and returns a String as output.
TypeExtractor	An extractor which returns the topic(s) which type the object specified on the input.
VariantNameExtractor	An extractor function which takes a Topic as input and returns a Variant instance as output The Variant returned will be selected from all Variants of the BaseNames of the Topic as follows: First the BaseName which has the most preferred themes in its scope, and at least one Variant is selected.
VariantsExtractor	An extractor which takes a VariantContainer instance as input and returns a the Variant instances that it contains.

Package org.tm4j.topicmap.utils.extractors Description

Provides reusable and composable functions for retrieving information from a variety of topic map constructs.

An extractor is a general term for a function which takes an object as an input, performs some processing on the object and returns another object as the output. This processing function is encapsulated in a class (the extractor class) using a highly generic interface which allows functions to be easily composed or used in specialised iterator or collection functions.

The interface implemented by an extractor is defined by the functional programming library Mango and is usually either the uk.co.jezuk.mango.UnaryFunction interface (which defines a generic interface for a function which takes one parameter) or the uk.co.jezuk.mango.BinaryFunction interface (which defines a generic interface for a function which takes two parameters).

This class-based approach to defining utility functions has a number of advantages over the more traditional "one class with lots of methods" approach:

1. Function instances can be configured before use, reducing the parameter count passed for each transform and making configuration more straightforward.
2. Once configured a function instance can be reused in many places in your code, leading to a more consistent application of the function with less coding.
3. Functions can be composed. This is particularly useful when processing collections or iterators over collections (and there are a lot of collections in topic maps!).

As an example of these advantages, consider an application which uses the XTM-defined subject for "display" to scope the display-names of topics. The class TopicNameExtractor can be used to extract a name string from a topic. It has configuration method TopicNameExtractor.addPreferredTheme(Topic) which specifies the theme that the extractor should look for in the scope of a base name when selecting one of the base names for the return value. The function itself is a unary function so it takes one parameter (a Topic) and returns a String result (the inputs and outputs are documented in the class Javadoc). So, we initialise the function like this:

      // Topic Name Extractor initialisation
      Topic display = // Code to retrieve the display topic from the topic map;
      TopicNameExtractor tne = new TopicNameExtractor();
      tne.setPreferredVariant(display);
    

Of course, this code could go in a constructor or other class or application initialisation method.

To use the extractor to print a topic name is simple:

      Topic t = // Code that gets the topic to display;
      System.out.println(tne.fn(t));
    

The fn(Object) method is the method that invokes the function ( for binary functions, this method's signature is fn(Object, Object)).

This approach makes the code for printing out the names of every topic in a collection very compact:

      for(Iterator it = tm.getTopicsIterator();it.hasNext();) {
        System.out.println(tne.fn(t));
      }