public class Datahub
extends Object
To use the class, you need to have the tools.jar file from the Java SDK 1.6+ on your classpath. This is because the Datahub compiles SQL table creation statements at runtime. The tools.jar file is in the JDK lib directory. When using Eclipse, you typically add the tools.jar file to the JRE system library configuration, instead of the project classpath.
There is no Datahub constructor - all of the methods are static.
To add compiled tables to the
Datahub, use the HubTable
constructor.
Table source code files are prepared using
makeTableFile
.
See the Datahub demonstration application, package datahubApp, for example java usage. The example classes demonstrate typical server use, remote client use, using a table for logging, and a technique for using tables for persistent storage.
This Java documentation is reference material primarily intended to help the developer use the API from an IDE such as Eclipse or NetBeans. Hume Integration Software also provides User Guide material which explains the syntax and features of the SQL command language, return code values, and other topics such as installing and configuring the software.
Modifier and Type | Class and Description |
---|---|
static class |
Datahub.HtmlSaveResult
A data structure used to return htmlSave() results
|
Modifier and Type | Field and Description |
---|---|
static String |
doubleFormatSpec
You can optionally supply a String.format(doubleFormatSpec, d)
format specification string to control how all double values are formatted.
|
static int |
ERR_BASIC_USAGE
non-specific syntax error, error message is usage help text
|
static int |
ERR_COMMUNICATION_ERROR
a communication error when using the dmh eval command
|
static int |
ERR_CREATE_CLASSLOAD
error loading the TableRow class for a table create.
|
static int |
ERR_CREATE_COMPILE
error compiling the TableRow java code for a table create.
|
static int |
ERR_DUPLICATE_SUBSCRIPTION_NAME
subscription name is already in use
|
static int |
ERR_FILE_IO
file system error
|
static int |
ERR_IMPROPER_VALUE
a value supplied is not proper for the usage context
|
static int |
ERR_INCLUDE_WARNING
warning result from the INCLUDE command that errors were encountered
from included statements
|
static int |
ERR_INSERT_UNIQUE_KEY_VIOLATION
a table row with the same primary composite key value already exists
|
static int |
ERR_INVALID_SYNTAX
syntax error, error message is specific for the error
|
static int |
ERR_MISSING_TERM
missing a specific keyword or expected value
|
static int |
ERR_NOT_CREATED
error instantiating a new table
|
static int |
ERR_SEND_ERROR
error when sending initial sync message(s) during subscription open
|
static int |
ERR_TABLE_DUPLICATION
table name is already in use
|
static int |
ERR_TABLE_WAS_DROPPED
the table has been dropped
|
static int |
ERR_UNEXPECTED_EXCEPTION
an unexpected java Exception was encountered
|
static int |
ERR_UNKNOWN_COLUMN
column name not found
|
static int |
ERR_UNKNOWN_TABLE
table name not found
|
static int |
ERR_UNKNOWN_VALUE
unknown subscription name, file name, or similar item
|
static int |
ERR_UNSUPPORTED_COMBO
mutually exclusive features have been specified for a subscription open.
|
static int |
ERR_UPDATE_UNIQUE_KEY_VIOLATION
the update would create more than one row with the same key value
|
static int |
ERR_WOULD_OVERWRITE
an output file already exists and the overwrite option is not specfied
|
static PrintStream |
errorOut
You can optionally provide a different PrintStream for error output.
|
static boolean |
printSqlExceptions
If this value is set true, all SqlExceptions are printed to the
errorOut PrintStream.
|
static boolean |
sqlColonTerminate
If this value is set true, then SQL statements generated by the Datahub
are terminated by a colon.
|
Constructor and Description |
---|
Datahub() |
Modifier and Type | Method and Description |
---|---|
static void |
addEvalProc(String commandName,
EvalProcItf evalObject)
Add a Java command to implement the SQL "eval commandName [arg]+" statement type.
|
static void |
addLvalProc(String commandName,
LvalProcItf lvalObject)
Add a Java command to implement the SQL "lval commandName [arg]+" statement type.
|
static String |
dmhClientInit(DmhClientItf dmh,
String boxname)
Join a DMH Group as a client that processes SQL command messages.
|
static DmhClientItf |
dmhClientInit(String boxnameAtGroupname,
StringBuilder errmsg)
Join a DMH Group as a client that processes SQL command messages.
|
static String |
dmhServerInit(String boxname,
String groupname)
The Datahub static main() optionally calls this procedure to initialize usage
of the DMH message system as a server.
|
static HubTable[] |
getTables()
Obtain an array of the data tables.
|
static Datahub.HtmlSaveResult |
htmlSave(boolean oneDocument,
boolean wantData,
boolean wantSchema,
boolean wantContents)
Save selected table information for all of the tables as one combined document
or as an HTML document per table in the current directory.
|
static Datahub.HtmlSaveResult |
htmlSave(boolean oneDocument,
boolean wantData,
boolean wantSchema,
boolean wantContents,
boolean wantSchemaDescription,
String[] tableNames,
String pathnameOrDir)
Save selected table information as one combined document or as an HTML document per table.
|
static void |
main(String[] args)
Execute the Datahub, optionally as a DMH server, optionally with console
input, optionally with a User interface.
|
static void |
makeTableFile(String sqlCreateStmt,
String directory,
String packageName)
A procedure for the Java user to prepare TableRowName.java files.
|
static void |
refreshTableList()
If the GUI is showing, update the table display list.
|
static String |
schemaHtmlData(HubTable table,
boolean addDescriptionCol)
Returns HTML text describing the schema of a table.
|
static String |
selectToHtml(String data)
Convert the sqlReply() table data list selection format to HTML text.
|
static String |
selectToHtml(String data,
String emptyString)
Convert the sqlReply() table data list selection format to HTML text.
|
static boolean |
setTableDir(String directoryPath)
Optionally set the directory for generated TableRow
|
static int |
sql(String sql)
Execute an SQL statement and provide a return code result.
|
static String |
sqlReply(String sql)
Execute an SQL statement and provide a string result structured as a list.
|
static String |
sqlReply(String sql,
BufferedReader fptr)
A version of sqlreply to accomodate data values that embed
newlines.
|
static void |
tableDrop(String tableName)
Drop (delete) a table.
|
static HubTable |
tableGet(String tablename)
Get a reference to a table for direct use in Java code.
|
static String[][] |
tableList()
Obtain the Datahub table summary information which is prominently
featured in the GUI as a two-dimensional array.
|
static boolean |
tablelistSubClose(String subname)
Close a subscription that was opened using tablelistSubscribe.
|
static boolean |
tablelistSubscribe(SubscriberItf receiver,
String subname)
Open a subscription that provides current and future notifications of created or
dropped tables as Java instance data.
|
static String |
tableRowClassname(String tablename)
This method returns the class name of a table data row type when the class
is generated automatically from an SQL create table statement.
|
static void |
usage()
Print a usage message to stdout explaining the command line options to main,
and showing an example of adding tools.jar to the classpath.
|
static String |
xmlSanitize(String data)
For proper conversion of table data to XML or HTML text, special
characters including '&', '<', '>', and '&guot;' have to be escaped.
|
public static String doubleFormatSpec
public static final int ERR_BASIC_USAGE
public static final int ERR_COMMUNICATION_ERROR
public static final int ERR_CREATE_CLASSLOAD
public static final int ERR_CREATE_COMPILE
public static final int ERR_DUPLICATE_SUBSCRIPTION_NAME
public static final int ERR_FILE_IO
public static final int ERR_IMPROPER_VALUE
public static final int ERR_INCLUDE_WARNING
public static final int ERR_INSERT_UNIQUE_KEY_VIOLATION
public static final int ERR_INVALID_SYNTAX
public static final int ERR_MISSING_TERM
public static final int ERR_NOT_CREATED
public static final int ERR_SEND_ERROR
public static final int ERR_TABLE_DUPLICATION
public static final int ERR_TABLE_WAS_DROPPED
public static final int ERR_UNEXPECTED_EXCEPTION
public static final int ERR_UNKNOWN_COLUMN
public static final int ERR_UNKNOWN_TABLE
public static final int ERR_UNKNOWN_VALUE
public static final int ERR_UNSUPPORTED_COMBO
public static final int ERR_UPDATE_UNIQUE_KEY_VIOLATION
public static final int ERR_WOULD_OVERWRITE
public static PrintStream errorOut
public static boolean printSqlExceptions
public static boolean sqlColonTerminate
The Datahub accepts and ignores semicolons on input. They do not denote the end of a statement.
public static void addEvalProc(String commandName, EvalProcItf evalObject)
commandName
- evalObject
- public static void addLvalProc(String commandName, LvalProcItf lvalObject)
commandName
- lvalObject
- public static String dmhClientInit(DmhClientItf dmh, String boxname)
dmh
- the DMH client connectionboxname
- our command receiving mailboxpublic static DmhClientItf dmhClientInit(String boxnameAtGroupname, StringBuilder errmsg)
boxnameAtGroupname
- boxname@[hostOrIp:]groupNameerrmsg
- used to pass an error message to the callerpublic static String dmhServerInit(String boxname, String groupname)
groupname
- the DMH groupnamepublic static HubTable[] getTables()
public static Datahub.HtmlSaveResult htmlSave(boolean oneDocument, boolean wantData, boolean wantSchema, boolean wantContents)
oneDocument
- write a single document else one per tablewantData
- include the current table datawantSchema
- include the table schemaswantContents
- include a table of contentspublic static Datahub.HtmlSaveResult htmlSave(boolean oneDocument, boolean wantData, boolean wantSchema, boolean wantContents, boolean wantSchemaDescription, String[] tableNames, String pathnameOrDir)
oneDocument
- write a single document else one per tablewantData
- include the current table datawantSchema
- include the table schemaswantContents
- include a table of contentswantSchemaDescription
- add a blank description columntableNames
- specify which tables are included.pathnameOrDir
- output pathname or directory for multiple table filespublic static void main(String[] args)
Command line options:
public static void makeTableFile(String sqlCreateStmt, String directory, String packageName) throws SqlException
HubTable abcd = new HubTable("abcd", new TableRowAbcd());
The example Datahub application includes the class MakeTableFiles which has a static Main method for the purpose of generating table files and table construction statements. You may want to copy and modify this class and use it in your application.
sqlCreateStmt
- the SQL create table statementdirectory
- output directory path for the java file.
A value such as "c:/cimdev/java/com/semico/autocell" is used so that the java file is
written into the source code directory for your package. Slash path delimiters work on all
platforms. A null input value causes the logic to use subdirectory bin of the current working
directory, or the current working directory if bin does not exist. An empty string value
implies the current working directory.packageName
- optional package name specification such as
"com.semico.autocell", use null or "" for noneSqlException
public static void refreshTableList()
public static String schemaHtmlData(HubTable table, boolean addDescriptionCol)
table
- addDescriptionCol
- whether to add a blank column for field descriptionspublic static String selectToHtml(String data)
data
- public static String selectToHtml(String data, String emptyString)
data
- emptyString
- a value to represent empty strings such as public static boolean setTableDir(String directoryPath)
The default value is the subdirectory bin of the current working directory, else the working directory if bin does not exist.
public static int sql(String sql) throws SqlException
The return value of a delete statement is 3 if no rows were
deleted and 0 if one or more rows were deleted. See the
deleteWhere
method if you want a count of rows deleted.
The return value of an update statement is similar. The
sqlReply
method provides a count of updated rows in the returned text.
There are HubTable methods to update a single row.
sql
- an SQL commandSqlException
- for syntax, unknown name or other major errorpublic static String sqlReply(String sql)
Here is the summary of commands as provided by the HELP command. Command keywords are not case sensitive. We are using case to distinguish replaced values from keywords.
# [comment text]
CLOSE SUB subname TO table
CREATE TABLE table ( colname type [, colname type]*, PRIMARY KEY(colname [,colname]*)); type:= { INT[EGER] | LONG | VARCHAR | VARCHAR(n) | FLOAT | DOUBLE }
DELETE FROM table [WHERE search_condition]
DROP TABLE table
ECHO text
EVAL procName [arg [arg]*]*
EXIT
HELP [command]
INCLUDE pathname
INFO {TABLE | SCHEMA table | SUB table | VALUES}
INSERT INTO table ( column [,column]*) VALUES ( value [,value]*)
LVAL procName [arg [arg]*]*
OPEN SUB subname TO table SENDTO=mailbox [REPLYTO=mailbox] [LISTFORMAT [ARGDATA=data]] [INSERT] [UPDATE] [DELETE] [DROP] [CREATE] [SYNC] { * | column [,column]*} [WHERE search_condition]
PING
READ [OVER] table
REM [comment_text]
SELECT { * | column [,column]* } FROM table [WHERE search_condition]
UPDATE table SET column=value [,column=value] [WHERE search_condition]
WRITE [OVER] table [pathname]
Return code values are summarized as follows:
0 - an unconditional success
>0 - success with a warning message
<0 - an error and an error diagnostic message
sql
- the input SQL statement
The return value of a selection result is formatted as a 7 element list:
(0) notificationType (usually the word select)
(1) tablename
(2) columns
(3) keyColumns
(4) rowCount
(5) resultList containing returnCode and resultMessage list elements
(6) dataRows
The return value of an eval method is a two element list:
(0) returnCode
(1) resultText
The StringList
or
the TclList
classes are used to parse list
results.
public static String sqlReply(String sql, BufferedReader fptr)
sql
- SQL statementfptr
- open stream readerpublic static void tableDrop(String tableName)
tableName
- public static HubTable tableGet(String tablename)
tablename
- public static String[][] tableList()
public static boolean tablelistSubClose(String subname)
subname
- the unique name of the subscriptionpublic static boolean tablelistSubscribe(SubscriberItf receiver, String subname)
receiver
- the receiving objectsubname
- a name for the subscription which is uniquepublic static String tableRowClassname(String tablename)
tablename
- public static void usage()
public static String xmlSanitize(String data)
data
- input data with possible special characters