com.apelon.modules.dts.editor.tql
Class TQL

java.lang.Object
  extended by java.lang.Thread
      extended by com.apelon.modules.dts.editor.tql.TQL
All Implemented Interfaces:
java.lang.Runnable

public class TQL
extends java.lang.Thread
implements java.lang.Runnable

The TQL class provides API access to TQL parsing and execution functions. Once the class has been instantiated, TQL queries can be executed from either passed strings or files. TQL extends Thread and implements the Runnable interface, to simplify its use by background processes.

Access to the array of DTSConcepts satisfying a query's collection set is also available.

Log messages are written to a log file, either the default TQL.log or one specified in the constructor, and fired to any attached ActionListeners. The log file is cleared by the constructor, but subsequent query processing messages are appended, potentially across multiple query executions.

TQL uses the static DTSAppManager.DTSQuery object for accessing the DTS knowledgebase. This object should either be set up by the calling program or by passing the server connection to the TQL constructor.

Copyright (c) 2008 Apelon, Inc. All rights reserved.


Nested Class Summary
static class TQL.StatementType
          Enum for TQL statement types.
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
static int COMPLETED
          ActionEvent Id code for completed event
static java.lang.String DEFAULT_DATE_FORMAT
          Default date format string
static java.lang.String DEFAULT_DELIMITER
          Deprecated.  
static java.lang.String DEFAULT_FIELD_DELIMITER
          Default field delimiter
static java.lang.String DEFAULT_GROUP_DELIMITER
          Default group delimiter
static java.lang.String DEFAULT_LOGFILE
          Name of default log file
static java.lang.String DEFAULT_THESAURUS_AXIS
          Name of default Thesaurus axis association
static java.lang.String DEFAULT_TIME_FORMAT
          Default time format string
static int ERROR
          ActionEvent Id code for error events
static int INTERRUPTED
          ActionEvent Id code for interrupted event
static int PROGRESS
          ActionEvent Id code for progress events
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
TQL()
          Create a TQL instance that uses existing connection parameters and the default log file.
TQL(ServerConnection sc)
          Deprecated. Use TQL(host, port, instance, user, psw)
TQL(ServerConnection sc, java.lang.String log)
          Deprecated. Use TQL(host, port, instance, user, psw, log)
TQL(java.lang.String log)
          Create a TQL instance that uses existing connection parameters and a specified log file.
TQL(java.lang.String host, int port, java.lang.String instance, java.lang.String user, java.lang.String psw)
          Create a TQL instance using connection parameters and the default log file.
TQL(java.lang.String host, int port, java.lang.String instance, java.lang.String user, java.lang.String psw, java.lang.String log)
          Create a TQL instance using connection parameters and a specified log file.
 
Method Summary
 void abort()
          Abort the export process.
 void addActionListener(java.awt.event.ActionListener al)
          Add an ActionListener for monitoring of log events.
 boolean getAppend()
          Get the value of the TQL APPEND variable that determines whether exports are unconditionally appended to the export file.
 java.lang.String getAxisName()
          Get the value of the TQL AXIS variable that names the AssociationType used as the parent-to-child link for Namespaces.
 QualifiedObject getAxisObject(int nsid)
          Get the qualified object representing the axis (hierarchy) relationship for a namespace The base direction is Parent to Child (parent_of).
static QualifiedObject getAxisObject(java.lang.String name, int nsid)
          Static entry to get the qualified object representing the axis (hierarchy) relationship for a namespace The base direction is Parent to Child (parent_of).
 DTSConcept[] getCollection()
          Deprecated. use getCollectionConcepts();
 DTSConcept[] getCollection(ConceptAttributeSetDescriptor casd)
          Deprecated. use getCollectionConcepts(casd)
 DTSConcept[] getCollectionConcepts()
          Get the array of selected DTSConcept objects from the last executed collection query.
 DTSConcept[] getCollectionConcepts(ConceptAttributeSetDescriptor casd)
          Get the array of selected concepts from the last executed collection query.
 DTSObject[] getCollectionObjects()
          Get the array of selected DTSObject ojectsfrom the last executed collection query.
 Term[] getCollectionTerms()
          Get the array of selected Term objects from the last executed collection query.
 Term[] getCollectionTerms(TermAttributeSetDescriptor tasd)
          Get the array of selected terms from the last executed collection query.
 java.lang.String getDateFormat()
          Get the value of the TQL DATE_FORMAT variable that specifies the format of exported dates (@D and version dates).
 java.lang.String getDefaultDelimiter()
          Get the default delimiter(s).
 java.lang.String getDelimiter()
          Get the value of the TQL DELIMITER variable used to separate fields in export lines.
 boolean getHeader()
          Get the value of the TQL HEADER variable that determines whether a header line should be placed in the export file.
 int getLimit()
          Get the value of the TQL LIMIT variable that limits the number of concept lines exported.
 boolean getPruneTerms()
          Get the value of the TQL PRUNE_TERMS variable that determines whether orphaned Terms are deleted.
 boolean getRetainHead()
          Get the value of the TQL RETAIN_HEAD variable that determines whether the DELETE_TREES command deletes its specified, head, Concepts.
 int getSize()
          Get the value of the TQL SIZE variable that gives the size (number of Concepts or Terms) of the last Collection.
 TQL.StatementType[] getStatementTypes()
          Get the query statement types.
 java.lang.String getTimeFormat()
          Get the value of the TQL TIME_FORMAT variable that specifies the format of exported times (@T).
 boolean getTypeDefs()
          Get the value of the TQL TYPEDEFS variable that determines whether Type definitions are included in EXPORT_CONCEPTS or EXPORT_SUBSET output.
 boolean getUnique()
          Get the value of the TQL UNIQUE variable that determines whether only unique lines are exported.
 boolean hasParameters()
          Test whether the query has parameters.
 boolean isAborted()
          Check for abort request.
 boolean isReadonly()
          Returns true if this query does not modify the DTS knowledgebase.
 void log(java.lang.String mess, int code)
          write log messages and fire associated events
static void main(java.lang.String[] args)
          Run TQL from the command line.
 boolean parse()
          Parse the query.
 void removeActionListener(java.awt.event.ActionListener al)
          Remove an ActionListener from the listener list.
 boolean replaceParametersAndParse(java.util.HashMap<java.lang.String,java.lang.String> parameterMap)
          Replace query parameters with string values.
 void run()
          Run (execute) the query.
 void setAppend(boolean b)
          Set the value of the TQL APPEND variable.
 void setAxisName(java.lang.String axis)
          Set the value of the TQL AXIS variable.
 void setDateFormat(java.lang.String str)
          Set the value of the TQL DATE_FORMAT variable.
 void setDelimiter(java.lang.String delim)
          Set the TQL export file delimiters.
 void setExportfile(java.lang.String name)
          Set the TQL export file.
 void setExportwriter(java.io.PrintWriter writer)
          Set the TQL export writer.
 void setHeader(boolean header)
          Set the value of the TQL HEADER variable.
 void setLimit(int n)
          Set the value of the TQL LIMIT variable.
 void setPruneTerms(boolean b)
          Set the value of the TQL PRUNE_TERMS variable.
 void setQueryfile(java.lang.String name)
          Set the TQL query file.
 void setQueryObject(java.util.List<StatementBean> array)
          Set the TQL query object.
 void setQuerystring(java.lang.String query)
          Set the TQL query string.
 void setRetainHead(boolean b)
          Set the value of the TQL RETAIN_HEAD variable.
 void setTimeFormat(java.lang.String str)
          Set the value of the TQL TIME_FORMAT variable.
 void setTypeDefs(boolean b)
          Set the value of the TQL TYPEDEFS variable.
 void setUnique(boolean b)
          Set the value of the TQL UNIQUE variable.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

PROGRESS

public static final int PROGRESS
ActionEvent Id code for progress events

See Also:
abort(), Constant Field Values

COMPLETED

public static final int COMPLETED
ActionEvent Id code for completed event

See Also:
abort(), Constant Field Values

INTERRUPTED

public static final int INTERRUPTED
ActionEvent Id code for interrupted event

See Also:
abort(), Constant Field Values

ERROR

public static final int ERROR
ActionEvent Id code for error events

See Also:
abort(), Constant Field Values

DEFAULT_FIELD_DELIMITER

public static final java.lang.String DEFAULT_FIELD_DELIMITER
Default field delimiter

See Also:
Constant Field Values

DEFAULT_DELIMITER

public static final java.lang.String DEFAULT_DELIMITER
Deprecated. 
Default field delimiter

See Also:
Constant Field Values

DEFAULT_GROUP_DELIMITER

public static final java.lang.String DEFAULT_GROUP_DELIMITER
Default group delimiter

See Also:
Constant Field Values

DEFAULT_THESAURUS_AXIS

public static final java.lang.String DEFAULT_THESAURUS_AXIS
Name of default Thesaurus axis association

See Also:
Constant Field Values

DEFAULT_LOGFILE

public static final java.lang.String DEFAULT_LOGFILE
Name of default log file

See Also:
Constant Field Values

DEFAULT_DATE_FORMAT

public static final java.lang.String DEFAULT_DATE_FORMAT
Default date format string

See Also:
Constant Field Values

DEFAULT_TIME_FORMAT

public static final java.lang.String DEFAULT_TIME_FORMAT
Default time format string

See Also:
Constant Field Values
Constructor Detail

TQL

public TQL()
Create a TQL instance that uses existing connection parameters and the default log file. Connection parameters must have been set in DTSAppManager for background thread to operate properly.


TQL

public TQL(java.lang.String log)
Create a TQL instance that uses existing connection parameters and a specified log file. Connection parameters must have been set in DTSAppManager for background thread to operate properly.


TQL

public TQL(ServerConnection sc)
Deprecated. Use TQL(host, port, instance, user, psw)

Create a TQL instance and set up the DTSQuery object. Uses the default log file.

Parameters:
sc - the ServerConnection to be set up

TQL

public TQL(ServerConnection sc,
           java.lang.String log)
Deprecated. Use TQL(host, port, instance, user, psw, log)

Create a TQL instance. Initializes the DTSQuery object and log file.

Parameters:
sc - the ServerConnection to be set up
log - the name of the log file to be used (can be null to prevent logging)

TQL

public TQL(java.lang.String host,
           int port,
           java.lang.String instance,
           java.lang.String user,
           java.lang.String psw)
Create a TQL instance using connection parameters and the default log file. Initializes the connection object.

Parameters:
host - the connection host name
port - the connection port number
instance - the connection instance name
user - the connection user name
psw - the connection password
host - the connection host name

TQL

public TQL(java.lang.String host,
           int port,
           java.lang.String instance,
           java.lang.String user,
           java.lang.String psw,
           java.lang.String log)
Create a TQL instance using connection parameters and a specified log file. Initializes the connection object.

Parameters:
host - the connection host name
port - the connection port number
instance - the connection instance name
user - the connection user name
psw - the connection password
host - the connection host name
log - the name of the log file to be used (can be null to prevent logging)
Method Detail

getDefaultDelimiter

public java.lang.String getDefaultDelimiter()
Get the default delimiter(s).

Returns:
the default delimiter string which contains the default field delimiter (in position 0) and the default group delimiter (in position 1)

setQuerystring

public void setQuerystring(java.lang.String query)
Set the TQL query string. Resets the query object and query file.

Parameters:
query - the string containing the query

setQueryfile

public void setQueryfile(java.lang.String name)
Set the TQL query file. Resets the query object and query string.

Parameters:
name - the name of the query file

setExportfile

public void setExportfile(java.lang.String name)
Set the TQL export file. Resets the export writer. Text (.txt) and Excel (.xls/.xlsx) file types are supported.

Parameters:
name - the name of the export file

setExportwriter

public void setExportwriter(java.io.PrintWriter writer)
Set the TQL export writer. Clears any export file specification.

Parameters:
writer - the PrintWriter to be used for exported data

setQueryObject

public void setQueryObject(java.util.List<StatementBean> array)
Set the TQL query object. Resets the query file and query string. **This method is for TQL internal use only.**

Parameters:
array - the TQL Query Object

getDelimiter

public java.lang.String getDelimiter()
Get the value of the TQL DELIMITER variable used to separate fields in export lines.

Returns:
the current delimiter string which contains the current field delimiter (in position 0) and the current group delimiter (in position 1)

setDelimiter

public void setDelimiter(java.lang.String delim)
Set the TQL export file delimiters. If delim is null or the empty string, the default delimiters are set. Otherwise, the first character of the argument becomes the field delimiter and the second character (if present) becomes the group delimiter.

Parameters:
delim - the export file delimiter

getHeader

public boolean getHeader()
Get the value of the TQL HEADER variable that determines whether a header line should be placed in the export file.

Returns:
whether a header row will be written

setHeader

public void setHeader(boolean header)
Set the value of the TQL HEADER variable. A true value causes a header line to be placed in the export file.

Parameters:
header - whether a header row should be written

getAxisName

public java.lang.String getAxisName()
Get the value of the TQL AXIS variable that names the AssociationType used as the parent-to-child link for Namespaces. An empty value defaults to Superconcept/Subconcept for Ontylog Namespaces or "Parent Of" for Thesaurus Namespaces.

Returns:
the name of the parent-to-child AssociationType

setAxisName

public void setAxisName(java.lang.String axis)
Set the value of the TQL AXIS variable. This is the name of the AssociationType used as the parent-to-child link for Namespaces. An empty value defaults to Superconcept/Subconcept for Ontylog Namespaces or "Parent Of" for Thesaurus Namespaces. The value may begin with "INV" to denote that the link points from child-to-parent.

Parameters:
axis - the name of the parent-to-child AssociationType

getAxisObject

public QualifiedObject getAxisObject(int nsid)
                              throws java.lang.Exception
Get the qualified object representing the axis (hierarchy) relationship for a namespace The base direction is Parent to Child (parent_of).

Parameters:
nsid - the id of the target namespace
Throws:
java.lang.Exception - on unknown association/role after logging error

getAxisObject

public static QualifiedObject getAxisObject(java.lang.String name,
                                            int nsid)
                                     throws java.lang.Exception
Static entry to get the qualified object representing the axis (hierarchy) relationship for a namespace The base direction is Parent to Child (parent_of).

Parameters:
the - name to be used as the axis, may include "inv"
nsid - the id of the target namespace
Throws:
java.lang.Exception - on unknown association/role after logging error

getLimit

public int getLimit()
Get the value of the TQL LIMIT variable that limits the number of concept lines exported.

Returns:
the maximum number of concept lines to be exported (zero means all)

setLimit

public void setLimit(int n)
Set the value of the TQL LIMIT variable. A non-zero value limits the number of concept lines exported to that number.

Parameters:
n - the maximum number of concept lines to be exported

getAppend

public boolean getAppend()
Get the value of the TQL APPEND variable that determines whether exports are unconditionally appended to the export file.

Returns:
whether exports are appended

setAppend

public void setAppend(boolean b)
Set the value of the TQL APPEND variable. A value of true causes exports to be unconditionally appended to the export file.

Parameters:
b - whether exports should be appended

getPruneTerms

public boolean getPruneTerms()
Get the value of the TQL PRUNE_TERMS variable that determines whether orphaned Terms are deleted.

Returns:
whether orphaned Terms will be deleted

setPruneTerms

public void setPruneTerms(boolean b)
Set the value of the TQL PRUNE_TERMS variable. A true value causes orphaned Terms to be deleted.

Parameters:
b - whether orphaned Terms should be deleted

getUnique

public boolean getUnique()
Get the value of the TQL UNIQUE variable that determines whether only unique lines are exported.

Returns:
whether only unique lines will be written

setUnique

public void setUnique(boolean b)
Set the value of the TQL UNIQUE variable. A true value causes only unique lines to be exported.

Parameters:
b - whether only unique lines should be written

getRetainHead

public boolean getRetainHead()
Get the value of the TQL RETAIN_HEAD variable that determines whether the DELETE_TREES command deletes its specified, head, Concepts.

Returns:
whether head concepts are retained

setRetainHead

public void setRetainHead(boolean b)
Set the value of the TQL RETAIN_HEAD variable. A true value causes the DELETE_TREES command to not delete specified, head, Concepts.

Parameters:
b - whether head concepts should be retained

getTypeDefs

public boolean getTypeDefs()
Get the value of the TQL TYPEDEFS variable that determines whether Type definitions are included in EXPORT_CONCEPTS or EXPORT_SUBSET output.

Returns:
whether TYPEDEFS will be exported

setTypeDefs

public void setTypeDefs(boolean b)
Set the value of the TQL TYPEDEFS variable. A true value causes Type definitions to be included in EXPORT_CONCEPTS or EXPORT_SUBSET output.

Parameters:
b - whether type definitions should be written

getDateFormat

public java.lang.String getDateFormat()
Get the value of the TQL DATE_FORMAT variable that specifies the format of exported dates (@D and version dates).

Returns:
the current date format string (see SimpleDateFormat

setDateFormat

public void setDateFormat(java.lang.String str)
Set the value of the TQL DATE_FORMAT variable. This string specifies the export format of internal DTS dates (@D and version dates).

Parameters:
the - Java SimpleDateFormat format string

getTimeFormat

public java.lang.String getTimeFormat()
Get the value of the TQL TIME_FORMAT variable that specifies the format of exported times (@T).

Returns:
the current date format string (see SimpleDateFormat

setTimeFormat

public void setTimeFormat(java.lang.String str)
Set the value of the TQL TIME_FORMAT variable. This string specifies the export format of internal DTS times (@T).

Parameters:
the - Java SimpleDateFormat format string

getSize

public int getSize()
Get the value of the TQL SIZE variable that gives the size (number of Concepts or Terms) of the last Collection.

Returns:
the size of last Collection

hasParameters

public boolean hasParameters()
Test whether the query has parameters. TQL Query object must have previous been set by setQueryfile or setQuerystring and parsed by parse. If the query has parameters, they can be replaced by a call to replaceParameters.

Returns:
whether the query has parameters
See Also:
parse(), #replaceParameters

replaceParametersAndParse

public boolean replaceParametersAndParse(java.util.HashMap<java.lang.String,java.lang.String> parameterMap)
Replace query parameters with string values. TQL query object must have previously been set by setQueryfile or setQuerystring. Parameters in the TQL query string will be replaced by their values in the parameter map and query will be parsed. Note that TQL CONSTRAIN statements are not processed by this method. Simple string replacement is performed. Any parse errors, including unresolved parameter errors, are logged and may be captured via an ActionListener.

Parameters:
parameterMap - HashMap\ of parameter names (keys)and associated values
Returns:
whether the query parse is successful
See Also:
parse(), hasParameters()

abort

public void abort()
Abort the export process. This will (eventually) terminate the run thread. Actual termination can be tracked through an ActionEvent.


isAborted

public boolean isAborted()
Check for abort request.

Returns:
whether an abort request has been received

parse

public boolean parse()
Parse the query. Query source must have previous been set by setQueryfile or setQuerystring. A successful parse sets the TQL query object. This method may be used if determination of a valid query is desired prior to running the query. Any parse errors are logged and may be captured via an ActionListener.

Returns:
whether the query parse is successful
See Also:
setQueryfile(String), setQuerystring(String)

getStatementTypes

public TQL.StatementType[] getStatementTypes()
Get the query statement types. Calls parse() if query object has not been prepared.

Returns:
array of StatementTypes

isReadonly

public boolean isReadonly()
Returns true if this query does not modify the DTS knowledgebase. Calls parse() if query object has not been prepared.

Returns:
true if all statements in the query are read-only

run

public void run()
Run (execute) the query. The query to be executed will be taken from the first non-null of the query object, the query string, or the query file, in that order.

Specified by:
run in interface java.lang.Runnable
Overrides:
run in class java.lang.Thread

getCollection

public DTSConcept[] getCollection()
Deprecated. use getCollectionConcepts();

Get the array of selected concepts from the last executed query.

Returns:
an array of DTSConcepts with no additional attributes

getCollectionObjects

public DTSObject[] getCollectionObjects()
Get the array of selected DTSObject ojectsfrom the last executed collection query.

Returns:
an array of DTSObjects with no additional attributes

getCollectionConcepts

public DTSConcept[] getCollectionConcepts()
Get the array of selected DTSConcept objects from the last executed collection query. Returns an empty array if query was not a basic collection query or if collection was Term-based.

Returns:
an array of DTSConcept with no additional attributes

getCollectionTerms

public Term[] getCollectionTerms()
Get the array of selected Term objects from the last executed collection query. Returns an empty array if query was not a basic collection query or if collection was Concept-based.

Returns:
an array of Term with no additional attributes

getCollection

public DTSConcept[] getCollection(ConceptAttributeSetDescriptor casd)
                           throws DTSException
Deprecated. use getCollectionConcepts(casd)

Get the array of selected concepts from the last executed query. Each concept in the array will be filled with the attributes specified in the ConceptAttributeSetDescritor.

Parameters:
casd - the ConceptAttributeSetDescriptor that defines the attributes to be returned on the concepts
Returns:
an array of DTSConcepts with the specified attributes
Throws:
DTSException - if an error occurs in accessing the requested concept attributes

getCollectionConcepts

public DTSConcept[] getCollectionConcepts(ConceptAttributeSetDescriptor casd)
                                   throws DTSException
Get the array of selected concepts from the last executed collection query. Each concept in the array will be filled with the attributes specified in the ConceptAttributeSetDescritor. Returns an empty array if query was not a basic collection query or if collection was Term-based.

Parameters:
casd - the ConceptAttributeSetDescriptor that defines the attributes to be returned on the concepts
Returns:
an array of DTSConcepts with the specified attributes
Throws:
DTSException - if an error occurs in accessing the requested concept attributes

getCollectionTerms

public Term[] getCollectionTerms(TermAttributeSetDescriptor tasd)
                          throws DTSException
Get the array of selected terms from the last executed collection query. Each term in the array will be filled with the attributes specified in the TermAttributeSetDescritor. Returns an empty array if query was not a basic collection query or if collection was Concept-based.

Parameters:
tasd - the TermAttributeSetDescriptor that defines the attributes to be returned on the terms
Returns:
an array of Terms with the specified attributes
Throws:
DTSException - if an error occurs in accessing the requested term attributes

log

public void log(java.lang.String mess,
                int code)
write log messages and fire associated events


addActionListener

public void addActionListener(java.awt.event.ActionListener al)
Add an ActionListener for monitoring of log events.

Parameters:
al - ActionListener to be added

removeActionListener

public void removeActionListener(java.awt.event.ActionListener al)
Remove an ActionListener from the listener list.

Parameters:
al - ActionListener to be removed

main

public static void main(java.lang.String[] args)
Run TQL from the command line. Usage is:

TQL -host:HOST -port:PORT -instance:INSTANCE -user:USER -psw:PASSWORD -query:QUERYFILE -output:OUTFILE -delim:DELIMITER -header:HEADER -log:LOGFILE

If the argument list is empty, TQL will prompt for the arguments.

Parameters:
args - the argument array