de.dfki.lt.hogclient
Class HogXmlRpcClient

java.lang.Object
  extended by de.dfki.lt.hogclient.HogXmlRpcClient

public class HogXmlRpcClient
extends java.lang.Object

This class provides an object oriented XmlRpc-interface to the HOG server.

Each instance of this class is connected to a HOG XmlRpc-server and uses its own default values, settings and history of data and exceptions.

Instantiate this class by giving it the hostname and the port number of a running HOG server. Use the methods of this instance to create sessions, annotation collections, annotations and to retrieve analyses of the created annotations.

Instances of this class keep track of all caught exceptions, the currently used xmlrpc-connection, session-, collection- and annotation IDs, analysis depth, analysis language, session configuration and the default annotation encoding. Each of these values can be changed manually by using the respective setter methods.

For a sample of usage, see SampleApplication.


Constructor Summary
HogXmlRpcClient(java.lang.String serverName, int port)
          Creates a new HogXmlRpcClient connecting it to a given XML-RPC server.
 
Method Summary
 java.lang.String analyze()
          Analyzes the annotation with the current session ID, collection ID and annotation ID and returns the result.
 java.lang.String analyze(java.lang.String sessionID, java.lang.String collectionID, java.lang.String annotationID)
          Analyzes the annotation with given session ID, collection ID and annotation ID and returns the result.
 java.lang.String analyze(java.lang.String sessionID, java.lang.String collectionID, java.lang.String annotationID, int depth)
          Analyzes the annotation with given session ID, collection ID and annotation ID at the given depth and returns the result.
 void connect(java.lang.String serverName, int port)
          Connects this client to a given XML-RPC server.
 java.lang.String createAnnotation(java.lang.String rawtext)
          Creates initial annotations in the current session/collection using the currently set default language and encoding.
 java.lang.String createAnnotation(java.lang.String sessionID, java.lang.String collectionID, java.lang.String rawtext, java.lang.String language, java.lang.String encoding)
          Creates initial annotations in the given session/collection using the given settings.
 java.lang.String createAnnotation(java.lang.String sessionID, java.lang.String collectionID, java.lang.String rawtext, java.lang.String language, java.lang.String clientName, java.lang.String encoding)
          Creates initial annotations in the given session/collection using the given settings and a custom name for the creator of the annotation.
 java.lang.String createCollection()
          Creates a new anntotation collection in the current session and returns its ID.
 java.lang.String createCollection(java.lang.String sessionID)
          Creates a new anntotation collection in the given session and returns its ID.
 java.lang.String createSession()
          Creates a new Session and return its sessionID.
 java.lang.String createSession(java.lang.String language, java.lang.String config)
          Creates a new Session and return its sessionID.
 java.lang.String createSession(java.lang.String language, java.lang.String config, java.lang.String sessionID)
          Creates a new Session and return its sessionID.
 java.lang.String deleteSession()
          Deletes/closes the most recently created session.
 java.lang.String deleteSession(java.lang.String sessionID)
          Deletes/closes session with sessionID.
 java.util.Stack getAllExceptionCauses()
          Returns all caught exceptions as a stack.
 java.lang.String getAnnotation()
          Retrieves and returns the annotation with the current session ID, collection ID and annotation ID.
 java.lang.String getAnnotation(java.lang.String sessionID, java.lang.String collectionID, java.lang.String annotationID)
          Retrieves and returns the annotation with the given session ID, collection ID and annotation ID.
 java.lang.String getAnnotationAsHTML()
          Retrieves the annotation with the current session ID, collection ID and annotation ID and returns its HTML representation.
 java.lang.String getAnnotationAsHTML(java.lang.String sessionID, java.lang.String collectionID, java.lang.String annotationID)
          Retrieves the annotation with the given session ID, collection ID and annotation ID and returns its HTML representation.
 java.lang.String getConfiguration()
          Returns the name of the session configuation file to be used when creating the next session.
 java.lang.String getEncoding()
          Returns the currently set default encoding of annotations for this client.
 java.lang.String getLanguage()
          Returns the session language to be used when creating the next session.
 java.lang.String getLastAnnotationID()
          Returns the ID of the annotation most recently used or created.
 java.lang.String getLastCollectionID()
          Returns the ID of the collection most recently used or created.
 java.lang.Throwable getLastExceptionCause()
          Returns the last caught exception cause and pops it off the internal stack.
 java.lang.String getLastSessionID()
          Returns the ID of the session most recently used or created.
 java.lang.String getServerHostName()
          Return the host name of the server this client is connected to.
 int getServerPort()
          Returns the port number of the server this client is connected to.
 java.lang.String getServerStatusString()
          Retrieves and returns a String representation of the current status of the server of this client.
 java.lang.String getServerURL()
          Returns the URL of the server this client is connected to.
 boolean isConnected()
          Tests the connection between the client and the server.
 java.lang.String sayHello()
          Requests the server connected to this client to say "Hello".
 void setConfiguration(java.lang.String conf)
          Sets the name of the session configuation file to be used when creating the next session.
 void setEncoding(java.lang.String encoding)
          Sets the default encoding of annotations for this client.
 void setLanguage(java.lang.String lang)
          Sets the session language to be used when creating the next session.
 java.lang.String shutdown()
          Shuts down the server connected to this client.
 java.lang.String toString()
          Returns the String representation of this instance:
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

HogXmlRpcClient

public HogXmlRpcClient(java.lang.String serverName,
                       int port)
                throws java.lang.ExceptionInInitializerError
Creates a new HogXmlRpcClient connecting it to a given XML-RPC server.

Parameters:
serverName - String the hostname running the XML-RPC server
port - int the port number of the XML-RPC server
Throws:
java.lang.ExceptionInInitializerError - in case the connection to the given server fails
Method Detail

connect

public void connect(java.lang.String serverName,
                    int port)
Connects this client to a given XML-RPC server.

(Disconnecting it from the previous one.)

Note: ordinarily, this method does not have to be used, as the constructor of this class will automatically connect this instance to a given server. Nevertheless, this method can be used to reconnect this instance to the (or possibly another) server.

Also note that lastSID, lastCID and lastAID are reset to "" on using this method.

Parameters:
serverName - String the hostname of the machine running XML-RPC server
port - int the port number of the XML-RPC server

getLastExceptionCause

public java.lang.Throwable getLastExceptionCause()
Returns the last caught exception cause and pops it off the internal stack.

To be used for error diagnosis. Note that the only public method of this class throwing an exception is the constructor. All other exceptions are handled internally.

This method is therefore used to remedy the lack of information arising from this approach. This means, that the application using this API does not have to deal with Java exceptions - error checking can be done by validating the objects returned by the public methods (rsp. "" for failures) - but the caught and recorded exception causes can be retrieved for debugging purposes.

For retrieving all caught and recorded exception causes

Returns:
Throwable the last catched exception cause
See Also:
getAllExceptionCauses()

getAllExceptionCauses

public java.util.Stack getAllExceptionCauses()
Returns all caught exceptions as a stack.

Returns:
Stack all caught exceptions as a stack

getServerHostName

public java.lang.String getServerHostName()
Return the host name of the server this client is connected to.

Returns:
String the host name of the server this client is connected to.

getServerPort

public int getServerPort()
Returns the port number of the server this client is connected to.

Returns:
String the port number of the server this client is connected to

getServerURL

public java.lang.String getServerURL()
Returns the URL of the server this client is connected to.

Returns:
String the URL of the server this client is connected to

toString

public java.lang.String toString()
Returns the String representation of this instance:

The name of this class followed by a # and the hashcode of this instance.

Overrides:
toString in class java.lang.Object
Returns:
String the String representation of this instance

setConfiguration

public void setConfiguration(java.lang.String conf)
Sets the name of the session configuation file to be used when creating the next session.

Parameters:
conf - String the name of the configuration file

getConfiguration

public java.lang.String getConfiguration()
Returns the name of the session configuation file to be used when creating the next session.

Returns:
String the name of the session configuation file to be used when creating the next session

setLanguage

public void setLanguage(java.lang.String lang)
Sets the session language to be used when creating the next session. For example: "en".

Parameters:
lang - String the session language to be used when creating the next session

getLanguage

public java.lang.String getLanguage()
Returns the session language to be used when creating the next session.

Returns:
String the session language to be used when creating the next session

getEncoding

public java.lang.String getEncoding()
Returns the currently set default encoding of annotations for this client.

Returns:
String the currently set default encoding of annotations for this client

setEncoding

public void setEncoding(java.lang.String encoding)
Sets the default encoding of annotations for this client.

Parameters:
encoding - String the default encoding of annotations for this client

getLastSessionID

public java.lang.String getLastSessionID()
Returns the ID of the session most recently used or created.

Returns:
String the ID of the session most recently used or created

getLastCollectionID

public java.lang.String getLastCollectionID()
Returns the ID of the collection most recently used or created.

Returns:
String the ID of the collection most recently used or created

getLastAnnotationID

public java.lang.String getLastAnnotationID()
Returns the ID of the annotation most recently used or created.

Returns:
String the ID of the annotation most recently used or created

isConnected

public boolean isConnected()
Tests the connection between the client and the server.

Returns true if connected and ready, false otherwise.

Returns:
boolean true if connected and ready, false otherwise

sayHello

public java.lang.String sayHello()
Requests the server connected to this client to say "Hello".

Returns:
String "Hello" in case the server is running and this client is connected to it. String "" in case of failure.

getServerStatusString

public java.lang.String getServerStatusString()
Retrieves and returns a String representation of the current status of the server of this client.

Returns:
a String representation of the current status of the server of this client.

createSession

public java.lang.String createSession()
Creates a new Session and return its sessionID.

Returns:
String the sessionID of the new sentence in case of success, "" in case of failure

createSession

public java.lang.String createSession(java.lang.String language,
                                      java.lang.String config)
Creates a new Session and return its sessionID.

Note that this method updates language and configuration.

Parameters:
language - the session language (e.g. "en")
config - the session configuration file (e.g. "xmlrpcsession.cfg")
Returns:
String the sessionID of the new sentence in case of success, "" in case of failure

createSession

public java.lang.String createSession(java.lang.String language,
                                      java.lang.String config,
                                      java.lang.String sessionID)
Creates a new Session and return its sessionID.

Note that this method updates language and configuration.

Parameters:
language - the session language (e.g. "en")
config - the session configuration file (e.g. "xmlrpcsession.cfg")
sessionID - the session ID (e.g. "demosession1")
Returns:
String the sessionID of the new sentence in case of success, "" in case of failure

deleteSession

public java.lang.String deleteSession()
Deletes/closes the most recently created session.

Resets lastSID (see getLastSessionID()) to "".

Returns:
String "ok" in case of success, "" in case of failure

deleteSession

public java.lang.String deleteSession(java.lang.String sessionID)
Deletes/closes session with sessionID.

Note that lastSID (see getLastSessionID()) is reset to "" if the session to be deleted is the current one.

Parameters:
sessionID - String the ID of the session to be deleted/closed
Returns:
String "ok" in case of success, "" in case of failure

createCollection

public java.lang.String createCollection()
Creates a new anntotation collection in the current session and returns its ID. Returns "" in case of failure.

Returns:
String the ID of the new collection, "" in case of failure

createCollection

public java.lang.String createCollection(java.lang.String sessionID)
Creates a new anntotation collection in the given session and returns its ID. Returns "" in case of failure.

Note that the value of lastSID (see getLastSessionID()) is altered to the given value sessionID in case of success.

Parameters:
sessionID - String the ID of the session in which to create the new collection
Returns:
String the ID of the new collection, "" in case of failure

createAnnotation

public java.lang.String createAnnotation(java.lang.String rawtext)
Creates initial annotations in the current session/collection using the currently set default language and encoding.

Two annotations will be created when calling this method:

  1. The raw text. ID: rawtext
  2. The xmlfied text including metadata. ID: xmltext

Use this method to initially put text into a new session for later analysis.

Parameters:
rawtext - the raw input text
Returns:
String "xmltext" if the operation was successful, "" otherwise
See Also:
createAnnotation(String, String, String, String, String)

createAnnotation

public java.lang.String createAnnotation(java.lang.String sessionID,
                                         java.lang.String collectionID,
                                         java.lang.String rawtext,
                                         java.lang.String language,
                                         java.lang.String encoding)
Creates initial annotations in the given session/collection using the given settings.

Two annotations will be created when calling this method:

  1. The raw text. ID: rawtext
  2. The xmlfied text including metadata. ID: xmltext

Use this method to initially put text into a new session for later analysis.

Note that this method updates lastSID, lastCID and lastAID in case of success.

Parameters:
sessionID - String the ID of the session in which to create the annotation
collectionID - String the ID of the collection in which create the annotation
rawtext - String the raw input text
language - String the language of the input text
encoding - String the encoding of the input text
Returns:
String "xmltext" if the operation was successful, "" otherwise
See Also:
createAnnotation(String)

createAnnotation

public java.lang.String createAnnotation(java.lang.String sessionID,
                                         java.lang.String collectionID,
                                         java.lang.String rawtext,
                                         java.lang.String language,
                                         java.lang.String clientName,
                                         java.lang.String encoding)
Creates initial annotations in the given session/collection using the given settings and a custom name for the creator of the annotation. (The default name when using createAnnotation(String, String, String, String, String) or createAnnotation(String) is "javaXmlRpcClient".

Two annotations will be created when calling this method:

  1. The raw text. ID: rawtext
  2. The xmlfied text including metadata. ID: xmltext

Use this method to initially put text into a new session for later analysis.

Note that this method updates lastSID, lastCID and lastAID in case of success.

Parameters:
sessionID - String the ID of the session in which to create the annotation
collectionID - String the ID of the collection in which create the annotation
rawtext - String the raw input text
language - String the language of the input text
clientName - String a custom name to be used in the metadata field "component" of annotation to be created
encoding - String the encoding of the input text
Returns:
String "xmltext" if the operation was successful, "" otherwise
See Also:
createAnnotation(String, String, String, String, String)

getAnnotation

public java.lang.String getAnnotation()
Retrieves and returns the annotation with the current session ID, collection ID and annotation ID.

Note, that this method changes the value of lastAID (see getLastAnnotationID()).

Returns:
String the annotation to be retrieved, "" in case of failure

getAnnotation

public java.lang.String getAnnotation(java.lang.String sessionID,
                                      java.lang.String collectionID,
                                      java.lang.String annotationID)
Retrieves and returns the annotation with the given session ID, collection ID and annotation ID.

Note that this method updates lastSID, lastCID and lastAID in case of success.

Parameters:
sessionID - String the ID of the session of the annotation to be retrieved
collectionID - String the ID of the collection of the annotation to be retrieved
annotationID - String the ID of the annotation to be retrieved
Returns:
String the annotation to be retrieved, "" in case of failure

getAnnotationAsHTML

public java.lang.String getAnnotationAsHTML()
Retrieves the annotation with the current session ID, collection ID and annotation ID and returns its HTML representation.

Returns:
String the HTML representation of the annotation with the current session ID, collection ID and annotation ID

getAnnotationAsHTML

public java.lang.String getAnnotationAsHTML(java.lang.String sessionID,
                                            java.lang.String collectionID,
                                            java.lang.String annotationID)
Retrieves the annotation with the given session ID, collection ID and annotation ID and returns its HTML representation.

Note that this method updates lastSID, lastCID and lastAID in case of success

Parameters:
sessionID - String the ID of the session of the annotation to be retrieved
collectionID - String the ID of the collection of the annotation to be retrieved
annotationID - String the ID of the annotation to be retrieved
Returns:
String the annotation to be retrieved represented in HTML, "" in case of failure

analyze

public java.lang.String analyze()
Analyzes the annotation with the current session ID, collection ID and annotation ID and returns the result.

Returns:
String the result of the analysis, "" in case of failure

analyze

public java.lang.String analyze(java.lang.String sessionID,
                                java.lang.String collectionID,
                                java.lang.String annotationID)
Analyzes the annotation with given session ID, collection ID and annotation ID and returns the result.

Parameters:
sessionID - String the ID of the session of the annotation to be analyzed
collectionID - String the ID of the collection of the annotation to be analyzed
annotationID - String the ID of the annotation to be analyzed
Returns:
String the annotation to be analyzed represented in HTML, "" in case of failure

analyze

public java.lang.String analyze(java.lang.String sessionID,
                                java.lang.String collectionID,
                                java.lang.String annotationID,
                                int depth)
Analyzes the annotation with given session ID, collection ID and annotation ID at the given depth and returns the result.

Parameters:
sessionID - String the ID of the session of the annotation to be analyzed
collectionID - String the ID of the collection of the annotation to be analyzed
annotationID - String the ID of the annotation to be analyzed
depth - int the depth of the analysis
Returns:
String the annotation to be analyzed represented in HTML, "" in case of failure

shutdown

public java.lang.String shutdown()
Shuts down the server connected to this client.

Returns:
String "ok" in case of success, "" in case of failure