org.dllearner.server

Class DLLearnerWS

java.lang.Object

org.dllearner.server.DLLearnerWS

public class DLLearnerWS
extends Object

DL-Learner web service interface. The web service makes use of the component architecture of DL-Learner (see architecture wiki page), i.e. it allows to create, configure and run components. In addition, it provides access to some reasoning and querying methods.

Author:

Jens Lehmann

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DLLearnerWS.Datastructures Conversion between different data structures.

Constructor Summary

Constructors

Constructor and Description
DLLearnerWS()

Method Summary

Modifier and Type	Method and Description
int	addKnowledgeSource(int id, String component, String url) Adds a knowledge source.
void	applyConfigEntryBoolean(int sessionID, int componentID, String optionName, Boolean value)
void	applyConfigEntryInt(int sessionID, int componentID, String optionName, Integer value)
void	applyConfigEntryString(int sessionID, int componentID, String optionName, String value)
void	applyConfigEntryStringArray(int sessionID, int componentID, String optionName, String[] value)
void	applyConfigEntryStringTupleList(int sessionID, int componentID, String optionName, String[] keys, String[] values)
void	applyConfigEntryURL(int sessionID, int componentID, String optionName, String value)
int	generateID() Generates a unique ID for the client and initialises a session.
String	getAsJSON(int sessionID, int queryID)
String	getAsXMLString(int sessionID, int queryID)
String[]	getAtomicConcepts(int id)
String[]	getAtomicRoles(int id)
String[]	getComponents() Gets a list of all DL-Learner components accessible via this web service.
int[]	getConceptArity(int id, int nrOfConcepts)
int[]	getConceptDepth(int id, int nrOfConcepts)
int	getConceptLength(String conceptString)
String[]	getConfigOptions(String component, boolean allInfo) Gets the configuration options supported by the component.
Boolean	getConfigOptionValueBoolean(int sessionID, int componentID, String optionName)
Double	getConfigOptionValueDouble(int sessionID, int componentID, String optionName)
Integer	getConfigOptionValueInt(int sessionID, int componentID, String optionName)
String	getConfigOptionValueString(int sessionID, int componentID, String optionName)
String[]	getConfigOptionValueStringArray(int sessionID, int componentID, String optionName)
String	getConfigOptionValueURL(int sessionID, int componentID, String optionName)
String	getCurrentlyBestConcept(int id)
String[]	getCurrentlyBestConcepts(int id, int nrOfConcepts, String format)
String	getCurrentlyBestEvaluatedDescriptions(int id, int limit)
String	getCurrentlyBestEvaluatedDescriptionsFiltered(int id, int nrOfDescriptions, double accuracyThreshold, boolean filterNonMinimalDescriptions)
String[]	getIndividualsForARole(int id, String role)
String[]	getInstances(int id)
String[]	getKnowledgeSources() Gets a list of all DL-Learner knowledge source components accessible via this web service.
String[]	getLearningAlgorithms() Gets a list of all DL-Learner learning algorithm components accessible via this web service.
String[]	getLearningProblems() Gets a list of all DL-Learner learning problem components accessible via this web service.
String[]	getNegativeExamples(int sessionID, int componentID, String[] positives, int results, String namespace, String[] filterClasses)
String[]	getReasoners() Gets a list of all DL-Learner reasoner components accessible via this web service.
String	getSubsumptionHierarchy(int id)
void	init(int id, int componentID) Initialise the specified component.
void	initAll(int id) Initialise all components.
boolean	isAlgorithmRunning(int id)
boolean	isSparqlQueryRunning(int sessionID, int queryID)
String	learn(int id, String format) Starts the learning algorithm and returns the best concept found.
String	learnDescriptionsEvaluated(int id) Returns a list of JSON encoded description including extra information (which partially depends on the learning problem) such as the accuracy of the learned description.
String	learnDescriptionsEvaluatedLimit(int id, int limit) Returns a list of JSON encoded description including extra information (which partially depends on the learning problem) such as the accuracy of the learned description.
void	learnThreaded(int id) Starts the learning algorithm and returns immediately.
boolean	ping() Method to check whether web service is online and how fast it responses.
void	removeKnowledgeSource(int id, int componentID) Removes a knowledge source.
String[]	retrieval(int id, String conceptString)
int	setLearningAlgorithm(int id, String component) Sets the learning algorithm to use.
int	setLearningProblem(int id, String component) Sets the learning problem to use.
void	setNegativeExamples(int id, String[] negativeExamples)
void	setPositiveExamples(int id, String[] positiveExamples)
int	setReasoner(int id, String component) Sets the reasoner to use.
String	sparqlQuery(int sessionID, int componentID, String query)
String	sparqlQueryPredefinedEndpoint(String predefinedEndpoint, String query, boolean useCache) Queries one of the standard endpoints defined in DL-Learner.
int	sparqlQueryThreaded(int sessionID, int componentID, String query)
String	SparqlRetrieval(String conceptString, int limit)
void	stop(int id) Stops the learning algorithm smoothly.
void	stopSparqlThread(int sessionID, int queryID)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DLLearnerWS

public DLLearnerWS()

Method Detail

ping

public boolean ping()

Method to check whether web service is online and how fast it responses. This method simply returns true.

Returns:

Always returns true.

generateID

public int generateID()

Generates a unique ID for the client and initialises a session. Using the ID the client can call the other web service methods. Two calls to this method are guaranteed to return different results.

Returns:

A session ID.

getComponents

public String[] getComponents()

Gets a list of all DL-Learner components accessible via this web service.

Returns:

All components accessible via this web service.

getKnowledgeSources

public String[] getKnowledgeSources()

Gets a list of all DL-Learner knowledge source components accessible via this web service.

Returns:

All knowledge source components accessible via this web service.

getReasoners

public String[] getReasoners()

Gets a list of all DL-Learner reasoner components accessible via this web service.

Returns:

All reasoner components accessible via this web service.

getLearningProblems

public String[] getLearningProblems()

Gets a list of all DL-Learner learning problem components accessible via this web service.

Returns:

All learning problem components accessible via this web service.

getLearningAlgorithms

public String[] getLearningAlgorithms()

Gets a list of all DL-Learner learning algorithm components accessible via this web service.

Returns:

All learning algorithm components accessible via this web service.

getConfigOptions

public String[] getConfigOptions(String component,
                                 boolean allInfo)

Gets the configuration options supported by the component. This allows e.g. to automatically build user interfaces for configuring components.

Parameters:

component - Name of the component.

allInfo - Whether or not complete information is desired (including option description, required, default value, example value).

Returns:

A list of configuration options supported by the component.

Throws:

UnknownComponentException - Thrown if component is not known (see getComponents()).

addKnowledgeSource

public int addKnowledgeSource(int id,
                              String component,
                              String url)
                       throws ClientNotKnownException,
                              UnknownComponentException,
                              MalformedURLException

Adds a knowledge source.

Parameters:

id - The session ID.

component - The name of the component.

url - The URL of the knowledge source.

Returns:

An identifier for the component.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException - Thrown if component is not known (see getComponents()).

MalformedURLException - Thrown if passed URL is malformed.

removeKnowledgeSource

public void removeKnowledgeSource(int id,
                                  int componentID)
                           throws ClientNotKnownException

Removes a knowledge source.

Parameters:

id - The session ID.

componentID - ID of knowledge source to remove.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

setReasoner

public int setReasoner(int id,
                       String component)
                throws ClientNotKnownException,
                       UnknownComponentException

Sets the reasoner to use.

Parameters:

id - The session ID.

component - The name of the component.

Returns:

An identifier for the component.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException - Thrown if component is not known (see getComponents()).

setLearningProblem

public int setLearningProblem(int id,
                              String component)
                       throws ClientNotKnownException,
                              UnknownComponentException

Sets the learning problem to use.

Parameters:

id - The session ID.

component - The name of the component.

Returns:

An identifier for the component.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException - Thrown if component is not known (see getComponents()).

setLearningAlgorithm

public int setLearningAlgorithm(int id,
                                String component)
                         throws ClientNotKnownException,
                                UnknownComponentException

Sets the learning algorithm to use.

Parameters:

id - The session ID.

component - The name of the component.

Returns:

An identifier for the component.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException - Thrown if component is not known (see getComponents()).

LearningProblemUnsupportedException - Thrown if the learning problem is not supported by the specified learning algorithm.

initAll

public void initAll(int id)
             throws ClientNotKnownException,
                    ComponentInitException

Initialise all components.

Parameters:

id - Session ID.

Throws:

ComponentInitException - Thrown if an error occurs during component initialisation.

ClientNotKnownException

init

public void init(int id,
                 int componentID)
          throws ClientNotKnownException,
                 ComponentInitException

Initialise the specified component.

Parameters:

id - Session-ID.

componentID - Component-ID.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException - Thrown if the component is unknown.

ComponentInitException

learn

public String learn(int id,
                    String format)
             throws ClientNotKnownException

Starts the learning algorithm and returns the best concept found. This method will block until learning is completed.

Parameters:

id - Session ID.

format - The format of the result string: "manchester", "kb", "dl".

Returns:

The best solution found.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

learnDescriptionsEvaluated

public String learnDescriptionsEvaluated(int id)
                                  throws ClientNotKnownException

Returns a list of JSON encoded description including extra information (which partially depends on the learning problem) such as the accuracy of the learned description.

Parameters:

id - The session ID.

Returns:

A JSON string encoding learned descriptions.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

learnDescriptionsEvaluatedLimit

public String learnDescriptionsEvaluatedLimit(int id,
                                              int limit)
                                       throws ClientNotKnownException

Returns a list of JSON encoded description including extra information (which partially depends on the learning problem) such as the accuracy of the learned description.

Parameters:

id - The session ID.

limit - Maximum number of results desired.

Returns:

A JSON string encoding learned descriptions.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

learnThreaded

public void learnThreaded(int id)
                   throws ClientNotKnownException

Starts the learning algorithm and returns immediately. The learning algorithm is executed in its own thread and can be queried and controlled using other Web Service methods.

Parameters:

id - Session ID.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

getCurrentlyBestConcept

public String getCurrentlyBestConcept(int id)
                               throws ClientNotKnownException

Parameters:

id - The session ID.

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

getCurrentlyBestConcepts

public String[] getCurrentlyBestConcepts(int id,
                                         int nrOfConcepts,
                                         String format)
                                  throws ClientNotKnownException

Parameters:

id - The session ID.

nrOfConcepts -

format -

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

getCurrentlyBestEvaluatedDescriptions

public String getCurrentlyBestEvaluatedDescriptions(int id,
                                                    int limit)
                                             throws ClientNotKnownException

Parameters:

id - The session ID.

limit -

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

getCurrentlyBestEvaluatedDescriptionsFiltered

public String getCurrentlyBestEvaluatedDescriptionsFiltered(int id,
                                                            int nrOfDescriptions,
                                                            double accuracyThreshold,
                                                            boolean filterNonMinimalDescriptions)
                                                     throws ClientNotKnownException

Parameters:

id - The session ID.

nrOfDescriptions -

accuracyThreshold -

filterNonMinimalDescriptions -

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

isAlgorithmRunning

public boolean isAlgorithmRunning(int id)
                           throws ClientNotKnownException

Parameters:

id - The session ID.

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

stop

public void stop(int id)
          throws ClientNotKnownException

Stops the learning algorithm smoothly.

Parameters:

id - The session ID.

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

setPositiveExamples

public void setPositiveExamples(int id,
                                String[] positiveExamples)
                         throws ClientNotKnownException

Parameters:

id - The session ID.

positiveExamples -

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

setNegativeExamples

public void setNegativeExamples(int id,
                                String[] negativeExamples)
                         throws ClientNotKnownException

Parameters:

id - The session ID.

negativeExamples -

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

applyConfigEntryInt

public void applyConfigEntryInt(int sessionID,
                                int componentID,
                                String optionName,
                                Integer value)
                         throws ClientNotKnownException,
                                UnknownComponentException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

value -

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

applyConfigEntryString

public void applyConfigEntryString(int sessionID,
                                   int componentID,
                                   String optionName,
                                   String value)
                            throws ClientNotKnownException,
                                   UnknownComponentException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

value -

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

applyConfigEntryURL

public void applyConfigEntryURL(int sessionID,
                                int componentID,
                                String optionName,
                                String value)
                         throws ClientNotKnownException,
                                UnknownComponentException,
                                MalformedURLException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

value -

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

MalformedURLException

applyConfigEntryStringArray

public void applyConfigEntryStringArray(int sessionID,
                                        int componentID,
                                        String optionName,
                                        String[] value)
                                 throws ClientNotKnownException,
                                        UnknownComponentException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

value -

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

applyConfigEntryStringTupleList

public void applyConfigEntryStringTupleList(int sessionID,
                                            int componentID,
                                            String optionName,
                                            String[] keys,
                                            String[] values)
                                     throws ClientNotKnownException,
                                            UnknownComponentException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

keys -

values -

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

applyConfigEntryBoolean

public void applyConfigEntryBoolean(int sessionID,
                                    int componentID,
                                    String optionName,
                                    Boolean value)
                             throws ClientNotKnownException,
                                    UnknownComponentException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

value -

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

getConfigOptionValueStringArray

public String[] getConfigOptionValueStringArray(int sessionID,
                                                int componentID,
                                                String optionName)
                                         throws ClientNotKnownException,
                                                UnknownComponentException,
                                                ConfigOptionTypeException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

ConfigOptionTypeException

getConfigOptionValueString

public String getConfigOptionValueString(int sessionID,
                                         int componentID,
                                         String optionName)
                                  throws ClientNotKnownException,
                                         UnknownComponentException,
                                         ConfigOptionTypeException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

ConfigOptionTypeException

getConfigOptionValueURL

public String getConfigOptionValueURL(int sessionID,
                                      int componentID,
                                      String optionName)
                               throws ClientNotKnownException,
                                      UnknownComponentException,
                                      ConfigOptionTypeException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

ConfigOptionTypeException

getConfigOptionValueDouble

public Double getConfigOptionValueDouble(int sessionID,
                                         int componentID,
                                         String optionName)
                                  throws ClientNotKnownException,
                                         UnknownComponentException,
                                         ConfigOptionTypeException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

ConfigOptionTypeException

getConfigOptionValueBoolean

public Boolean getConfigOptionValueBoolean(int sessionID,
                                           int componentID,
                                           String optionName)
                                    throws ClientNotKnownException,
                                           UnknownComponentException,
                                           ConfigOptionTypeException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

ConfigOptionTypeException

getConfigOptionValueInt

public Integer getConfigOptionValueInt(int sessionID,
                                       int componentID,
                                       String optionName)
                                throws ClientNotKnownException,
                                       UnknownComponentException,
                                       ConfigOptionTypeException

Parameters:

sessionID - The session ID.

componentID - The componentID.

optionName - The name of the configuration option.

Returns:

Throws:

ClientNotKnownException - Thrown if client (session ID) is not known.

UnknownComponentException

ConfigOptionTypeException

getAtomicConcepts

public String[] getAtomicConcepts(int id)
                           throws ClientNotKnownException

Throws:

ClientNotKnownException

getSubsumptionHierarchy

public String getSubsumptionHierarchy(int id)
                               throws ClientNotKnownException

Throws:

ClientNotKnownException

retrieval

public String[] retrieval(int id,
                          String conceptString)
                   throws ClientNotKnownException,
                          ParseException

Throws:

ClientNotKnownException

ParseException

getConceptLength

public int getConceptLength(String conceptString)
                     throws ParseException

Throws:

ParseException

getAtomicRoles

public String[] getAtomicRoles(int id)
                        throws ClientNotKnownException

Throws:

ClientNotKnownException

getInstances

public String[] getInstances(int id)
                      throws ClientNotKnownException

Throws:

ClientNotKnownException

getIndividualsForARole

public String[] getIndividualsForARole(int id,
                                       String role)
                                throws ClientNotKnownException

Throws:

ClientNotKnownException

getAsJSON

public String getAsJSON(int sessionID,
                        int queryID)
                 throws ClientNotKnownException,
                        SparqlQueryException

Throws:

ClientNotKnownException

SparqlQueryException

getAsXMLString

public String getAsXMLString(int sessionID,
                             int queryID)
                      throws ClientNotKnownException,
                             SparqlQueryException

Throws:

ClientNotKnownException

SparqlQueryException

sparqlQueryThreaded

public int sparqlQueryThreaded(int sessionID,
                               int componentID,
                               String query)
                        throws ClientNotKnownException

Throws:

ClientNotKnownException

sparqlQuery

public String sparqlQuery(int sessionID,
                          int componentID,
                          String query)
                   throws ClientNotKnownException

Throws:

ClientNotKnownException

sparqlQueryPredefinedEndpoint

public String sparqlQueryPredefinedEndpoint(String predefinedEndpoint,
                                            String query,
                                            boolean useCache)

Queries one of the standard endpoints defined in DL-Learner.

Parameters:

predefinedEndpoint - A string describing the endpoint e.g. DBpedia.

query - The SPARQL query.

useCache - Specify whether to use a cache for queries.

Returns:

The result of the SPARQL query in JSON format or null if the endpoint does not exist.

See Also:

SparqlEndpoint.getEndpointByName(String)

isSparqlQueryRunning

public boolean isSparqlQueryRunning(int sessionID,
                                    int queryID)
                             throws ClientNotKnownException

Throws:

ClientNotKnownException

stopSparqlThread

public void stopSparqlThread(int sessionID,
                             int queryID)
                      throws ClientNotKnownException

Throws:

ClientNotKnownException

getConceptDepth

public int[] getConceptDepth(int id,
                             int nrOfConcepts)
                      throws ClientNotKnownException

Throws:

ClientNotKnownException

getConceptArity

public int[] getConceptArity(int id,
                             int nrOfConcepts)
                      throws ClientNotKnownException

Throws:

ClientNotKnownException

SparqlRetrieval

public String SparqlRetrieval(String conceptString,
                              int limit)

getNegativeExamples

public String[] getNegativeExamples(int sessionID,
                                    int componentID,
                                    String[] positives,
                                    int results,
                                    String namespace,
                                    String[] filterClasses)
                             throws ClientNotKnownException

Throws:

ClientNotKnownException