Matchmaker User Guide

Author: Dimitris Andreou

Contact: jim.andreou <at> gmail.com Table of contents:
1. Introduction
1.1. Installation
2. Bootstrapping and registration of services
3. Matching
4. Ranking / Preferences
5. Adaptive matchmaking
5.1. General framework for adaptations
5.2. Invokable adaptations supported out of the box
6. Deployment as Web Service
Appendix - Simple generation of test data

1. Intoduction

The matchmaker library is designed as an advanced OWL-S service registry. In this introduction, we briefly go through the major parts of the library and leave details for the relevant sections following.

Services are primarily modelled as function signatures, i.e., a set of inputs and a set of outputs, but they can have arbitrary metadata too. Each input and output is associated with an OWL class that defines its semantics, or the set of allowable values for it.

The primary function of the matchmaker is to answer matching queries. The matchmaker is given a signature, for example: Inputs: {CreditCard}, Outputs: {Book}, and asked about available services "matching" it in some sense. (Of course, a service must be registered with a matchmaker before it can appear as part of the matchmaker's answers). The outputs of the query signature are interpreted as requirements (all of them must be satisfied by the outputs of a matching service), while its inputs are interpreted as capabilities (all inputs of a matching service must be satisfiable by using only the declared inputs of the query). After performing a matching query, the matchmaker returns an unordered collection of matches. Then, the user may rank the results with the supplied preferences framework: the user creates a preference expression and uses it to the results to select the best elements.

Services are registered and queried using OWL-S, handled in Java using the OWL-S API.

A matchmaker can be used directly in an application or it can be deployed as a web service, either on an application server or stand-alone.

1.1. Installation

You can find the latest bundle of the matchmaker at the ICT-ALIVE project at sourceforge, located under the folder alive-matchmaker. Source files and documentation is included.

To use the matchmaker, you need the matchmaker's jar, as well as its dependencies jars. The first can be located at dist/alive-matchmaker.jar, while the dependencies are all the jars found under lib (note that jars in lib/optional are not necessary for the typical user).

Building the project from the source

You can checkout the project from the svn repository:

https://ict-alive.svn.sourceforge.net/svnroot/ict-alive/ServiceLevel/alive-matchmaking/trunk

import edu.bath.matchmaker.*;
...
MatchMaker matchMaker = new MatchMaker();

URI existingService = URI.create("http://on.cs.unibas.ch/owl-s/1.2/AmazonBookPrice.owl");

URI existingService = new File("services/AmazonBookPrice.owl").toURI();

matchMaker.registerService(OwlsUtils.parseURI(existingService));

Collection<URI> services = ...;

ExecutorService threadPool = Executors.newFixedThreadPool(4 * Runtime.getRuntime().availableProcessors());
try {
    MatchMakers.bulkRegister(matchMaker, services, threadPool);
} finally {
    threadPool.shutdown();
}

More services can be registered at any point, and they can be deregistered too.

3. Matching

OWLOntology desiredService = OwlsUtils.parseURI(desiredServiceURI);
Collection<Match> matches = matchMaker.match(
    desiredService,
    InputMatcher.SUPERCLASSES,
    OutputMatcher.SUBCLASSES);

for (Match match : matches) {
   ServiceDescriptor service = match.getService();
   System.out.println("Matched service: " + service.getURI());
   System.out.println("  Inputs: " + service.getInputs());
   System.out.println("  Outputs: " + service.getOutputs());
}

Conceptually, the process is very simple: define a preference (possibly beforehand), and use it to find the best matches. A preference is a binary relation, closely resembling a partial order. In particular, it is the union of a partial order and an equivalence relation, i.e., a preorder -- a reflexive, transitive relation, denoted by ⪰ (hopefully your browser displays UNICODE characters correctly - if not, the last symbol was the ">=" operator, i.e., "greater or equal").

This notation: a ⪰ b, means that "a" is at least as preferable to "b". Transitivety requires that if a ⪰ b and b ⪰ c, then a ⪰ c too. Reflexivity requires that a ⪰ a always. We make no other assumption on the preference relation.

Given a preference relation, we can find the (5) best elements of a collection. For example:

Preference<Match> preference = ...;
Collection<Match> matches = matchMaker.match(...);

List<List<Match>> blocks = preference.topElements(matches, 5);
for (List<Match> block : blocks) {
   System.out.println("Matches of the next best block: " + block);
}

Iterable<Match> flatResults = Iterables.concat(blocks); //com.google.common.collect.Iterables

The problem then, of course, is how to construct a Preference<Match> object that expresses our actual preferences.

To illustrate of what is possible with the provided preferences framework, we will go through a substantial example. In this example, our aim is to express three preferences:

• pS: We prefer service whose the textual description (remember: OWL-S services can include a natural language description of the service) matches more closely the textual description of the query (the query is still OWL-S, so the user can add a natural language description of the desired service).
• pR: We prefer services with higher reliability (a typical quality of service notion)
• pI: We prefer services with inputs that as specific as possible (i.e. we prefer a subclass from a superclass for an input parameter type)

• Our pI preference is as important as pR, and
• pS is less important than the others

We will work backwards. We will first assume that we already specified pI, pR, pS, and combine them, and only then we will show how to actually specify them.

Preference<Match> pI = ...;
Preference<Match> pR = ...;
Preference<Match> pS = ...;

Preference<Match> pref = Preference.consensus(pI, pR).preferredTo(pS);

Now, lets work through defining each of the pI, pR, pS preferences. pI is easy to get, since it is offered out of the box.

//assuming: MatchMaker matchMaker = ...;
Preference<Match> pI = Preferences.ParamSpecialization.inputs(matchMaker.getSubsumption());

For the reliability preference, pR (preference on higher reliability) we have more work to do. The framework is completely agnostic of such a "reliability" concept. There are many ways to model it, and many ways to store it (e.g. in a database, in the file system, or simply in memory) -- you are the one who chooses your architecture. For our purposes, we assume we maintain such a map:

final Map<URI, Integer> reliabilityScores = ...;

In effect, for pR, we prefer services which are associated (via reliabilityScores) with larger integers. Lets try to model that. This expression simply says we prefer smaller integers:

Preference<Integer> p = Preference.natural();

Preference<Integer> p = Preference.natural().reverse();

Preference<Match> pR = Preference.natural().reverse().onResultOf(new Function<Match, Integer>() {
   public Integer apply(Match match) {
       return reliabilityScores.get(match.getService().getURI());
   }
});

For the textual similarity preference, pS, we do have support from the matchmaker. To answer textual similarity queries, we have to maintain extra data structures, for example to store how many times a term (word) appeared in a particular service description (recall that the matchmaker does not retain the OWL-S representation of the service after its registration, only its signature, and the textual similarity is just a part of the OWL-S representation). So we can't suddenly decide to answer such queries to do ranking, we have to anticipate them and prepare accordingly. Apart from textual similarities, there are many other scenarios that the user would like to process the OWL-S description of a service and retain extra information, to be used later (for ranking, in our case).

In such scenarios, MatchDecorators come into play. A MatchDecorator is an interface that can be implemented by the user and registered with a MatchMaker instance upon instantiation of the latter. Then, the MatchDecorator watches every registered/deregistered service, and it is free to maintain any data structure it wants. Furthermore (and that is the MatchDecorator key ability), it can decorate each produced Match with additional key-value entries.

In our example, we need to construct our matchmaker as following:

MatchMaker matchMaker = new MatchMaker(new Preferences.DescriptionSimilarityDecorator());

DescriptionSimilarityDecorator in particular creates decorations with TextualSimilarity keys. So, we could append such a predicate to our match() queries:

Predicates.instanceOf(TextualSimilarity.class)

While this rather complicated walk-through touched lots of aspects of the matchmaker design, using textual similarities is not complicated. To summarise, this is all we have to do:

1. Make sure we instantiate our matchmaker by adding new Preferences.DescriptionSimilarityDecorator() in its constructor.
2. Either use the plain match() method, or provide a predicate that accepts decoration keys of type Preferences.TextualSimilarity.

Preference<Match> pS = new TextualSimilarity(TextType.DESCRIPTION, Similarity.COSINE).preference();

final TextualSimilarity key = new TextualSimilarity(TextType.DESCRIPTION, Similarity.COSINE);
Preference<Match> pS = Preference.<Double>natural().reverse().onResultOf(new Function<Match, Double>() {
    public Double apply(Match match) {
        return match.getDecoration(key);
    }
});

This concludes our walkthrough in ranking via preferences. For further information, please see the javadocs of Preferences class, which contain several MatchDecorator implementations. Each implementation describes, apart from the semantics of the produced decorations, under which keys are the decorations added, which can be used to define preferences.

A final remark: while preferences can express things which scoring functions cannot, you should note that it is very easy to use a scoring function if so you wish. The framework offers no specific support for that, because it already very easy to implement. For example, one could start by match decorations and aggregate them into a single score, and perform a simple ranking (sorting) based on that score. Or use such a score to define a preference on it, and combine it with other preferences, or whatever.

5. Adaptive matchmaking

I.e., B extends (is a subclass of) A, C extends B and so on. The matchmaker uses these edges/relations as explained in the Matching section. For example, if a query requests an output of B or any subclass, a matched service may be producing outputs of C instead. Now, how can we blend such "is-a" edges, together with adaptations, hopefully yielding a cohesive result? A starting point is observing that we can interpret "is-a" edges as adaptations themselves. For example, that fact that B is a subclass of A is the same as saying "we have a function that, given an instance of B, yields an instance of A". In fact, this function is simply equivalent to an upcast (as for example happens implicitly in Java code: Object o = new Person("John Smith");). This observation gives a natural way of incorporating adaptations: for a function f: A => B, simply add an edge from A to B - which is structurally the same to A being a subclass of B.

Lets augment the above graph with a couple of adaptations: f: A => C and g: D => E.

That's all it takes! Matchmaking can proceed as usual. For example, a query issued with code such as:
MatchMaker mm = ...;
Collection<Match> results = mm.match(query, InputMatcher.SUPERCLASSES, OutputMatcher.SUBCLASSES);
means that we want the matched services to have inputs where each one can be reached from some query input (without the adaptations, only superclasses of the query inputs can be reached by them), and outputs that collectively reach all query outputs (without the adaptations, only subclasses of the query outputs can reach them in the graph). Thus, the incorporation of adaptations could hardly be any simpler: we only have more edges in the subsumption graph, with the same matching semantics and algorithm.

The following picture shows a query (IN1 x IN2 => OUT1 x OUT2) and a matching (through adaptations) service. A service is matched when it covers all query outputs with each own outputs (with appropriate paths to the query outputs), and all its inputs are covered by query inputs (with appropriate paths to the service inputs). Without adaptations, the paths would only comprise of is-a edges, while with adaptations, arbitrary user-specified edges are allowed. So whereas without adaptations, the inputs/outputs are applicable/usable with only a series of upcasts (e.g. InputMatcher.SUPERCLASSES, OutputMatcher.SUBCLASSES) or downcasts (e.g. InputMatcher.SUBCLASSES, OutputMatcher.SUPERCLASSES),

This matched service (of signature A x C => D x OUT2) was matched because at least one appropriate path for each required case (for each service input and query output) was found. For example, the service's input C is provided by an input IN2 which is transformed to B via adaptation A2, and then that B is transformed to C via adaptation A3.

There is still a gap to be filled though: how to create an invokable adapted service based on such a diagram? This is addressed in the following subsection.

5.1 General framework for adaptations

MatchMaker mm = ...;
Object adaptationKey = "a user-provided arbitrary key to associate with the adaptation";
URI inputType = URI.create("http://example/sourceClass");
URI outputType = URI.create("http://example/targetClass");
double reliability = 0.9;

mm.registerAdaptation(adaptationKey, reliability, inputType, Collections.singleton(outputType));

Collection<Match> results = mm.match(query, InputMatcher.(...), OutputMatcher.(...) );

Match match = ...;
for (URI serviceInput : match.getService().getInputTypes()) {
    Iterator<CompositeAdaptation> pathIterator = match.adaptationsForServiceInput(serviceInput));
    //choose a path from the iterator, and use it somehow
}

Match match = ...;
for (URI queryOutput : match.getQuery().getOutputTypes()) {
    Iterator<CompositeAdaptation> pathIterator = match.adaptationsForQueryOutput(queryOutput));
    //choose a path from the iterator, etc
}

5.2. Invokable adaptations supported out of the box

• Implement an adaptation via an existing OWL-S service

That is, the adaptation is backed by a single-input, single-output OWL-S service. The user must be able to provide a Supplier of an (OWL-S) Process object, which can be directly used to invoke the adaptation. Thus, the user needs to be able to locate the service and access the relevant Process object. Note that this has to be a Supplier<Process> instead of a Process directly, because Process objects are not shareable, so we need to create a different one per thread, to avoid thread-safety issues.

Sample code:

MatchMaker mm = ...;
Supplier<Process> processSupplier = new Supplier<Process>() {
    public Process get() {
        ...; //find the appropriate service and return its Process
    }
};
URI inputType = URI.create("http://example/sourceClass");
URI outputType = URI.create("http://example/targetClass");
double reliability = 0.85;

SimpleAdaptationBuilder.registerProcessAdaptation(mm, inputType, outputType, processSupplier, reliability);

Note that we don't get to specify a user-defined adaptation key - SimpleAdaptationBuilder defines one for us.

• Implement an adaptation via Java code

Another way to implement an adaptation is through a Java-based service. This could look like the following:

public class MyAdaptor implements JavaServiceProvider {
        public void execute(ValueMap<Input, OWLValue> inputs, ValueMap<, OWLValue> outputs, AtomicProcess process) throws Exception {
              ...; //implement adaptation service
        }
}
MatchMaker mm = ...;
URI inputType = URI.create("http://example/sourceClass");
URI outputType = URI.create("http://example/targetClass");
double reliability = 0.85;

SimpleAdaptationBuilder.registerJavaAdaptation(mm, inputType, outputType, MyService.class, reliability);

Of course, if the resulting adapted service (shown later) is to be executed in another JVM, MyService class must also be available in the classpath of that.

• Implement an adaptation via a functional property
Finally, if a functional property is defined on a class A, i.e. all instances of a particular class are guaranteed to have a particular (uniquely-valued) property with a range of class B, that property can be used as an adaptation of the form A => B in the obvious way. To register such a property as an adaptation, the following code can be used:

MatchMaker mm = ...;
URI inputType = URI.create("http://example/sourceClass");
URI outputType = URI.create("http://example/targetClass");
URI myFunctionalProperty = ...;
double reliability = 0.99;

SimpleAdaptationBuilder.registerJavaAdaptation(mm, inputType, outputType, myFunctionalProperty, reliability);

Registering the adaptation via SimpleAdaptationBuilder instead of directly to the MatchMaker has the important advantage that we can make assumptions on what metadata the adaptations contain (e.g. information on how they are supposed to be invoked), so we can offer automatic translation of a matched service to an adapted OWL-S service - i.e. a matched service can be translated to an OWL-S definition which implements the interface of the query, is backed by the matched service, and uses the chosen adaptations upon its invocation.

Doing so is very simple. We need to specify the match itself, the Service object that corresponds to it (the user must be able to locate the service definition and construct this, otherwise he would not be able to invoke the matched service anyway), and a URI with the designated name for the generated process (can be null, to make it anonymous).

Match match = ...; //perform a query, get some matches, chose some Match to create an adapted service
Service matchedService = ...; //locate the Service corresponding to the URI of match.getService().getURI()

Process process = SimpleAdaptationBuilder.buildAdaptedProcess(match, matchedService, URI.create("http://example/myAdaptedProcess"));

This process object can be executed, or be serialized to RDF/XML, sent to another machine, and executed there.

Currently, to simplify the API, a big simplification takes places: by calling SimpleAdaptationBuilder.buildAdaptedProcess(...), the user does not get to choose which path, from all possibilities, is used for each service input or query output, but the best path is used by default.

6. Deployment as Web Service

MatchMaker matchMaker = ...;
int port = 80;

MatchMakerWSEndpoint.Proxy proxy = MatchMakerWSEndpoint.deploy(port, matchMaker);

proxy.getEndpoint().stop();

MatchMaker mm = proxy.getMatchMaker();
String serviceLocation = proxy.getServiceLocation();

MatchMakerWS wsClient = MatchMakerWSEndpoint.createClient(serviceLocation);

import com.google.common.collect.ImmutableMap;
import com.google.common.collect.ImmutableSet;

import edu.bath.matchmaker.OwlsUtils;
import edu.bath.matchmaker.ServiceDescriptor;

import org.mindswap.owl.OWLOntology;
import org.mindswap.owls.service.Service;

ServiceDescriptor serviceDescriptor = ServiceDescriptor.fromInputsOutputs(
        URI.create("http://myService"),
        ImmutableMap.of(URI.create("in"), URI.create("http://inputType")),
        ImmutableMap.of(URI.create("out"), URI.create("http://outputType")));

Service service = serviceDescriptor.toOwls("some textual description of the service");

OWLOntology onto = service.getOntology();
String owlsText = OwlsUtils.toString(onto, URI.create("http://baseURI/for/the/generated/rdfxml/string"));

System.out.println(owlsText);

ServiceDescriptor query = ServiceDescriptor.query(
     ImmutableSet.of(org.mindswap.owl.vocabulary.OWL.Nothing.getURI()),
     Collections.<URI>emptySet());