Chapter 9. OpenAPI Programming
Index:
HXTT Text (CSV) supports more than 180 SQL functions. Please email us if you wish
to complement some new SQL functions. HXTT Text (CSV) supports also user-defined SQL
functions, and you should use only this feature to provide special SQL functions
in your project.
First, you need to implement com.hxtt.sql.ExtendedFunctionInterface.
public interface ExtendedFunctionInterface { /** * Used to verify whether functionName is supported, and has a correct prarameter count. * @param functionName the name of function * @param parameters the parameter list of function, which can be null * @return value * @throws SQLException if has an incorrect parameter number */ public boolean isExtendedFunction(String functionName,Object[] parameters)throws SQLException; /** * Used to evaluate function value. * @param functionName the name of function * @param values the value list of function, which can be null * @return value * @throws SQLException if failed to calculate the function */ public Object evaluate(String functionName,Object[] values)throws SQLException; /** * Used to get the SQL type of the value that is expected to be returned when evaluate() is called. * @param functionName * @return the SQL type or Types.NULL if functionName is supported */ public int getType(String functionName); /** * Used to get the SQL types of the parameter values that are expected to be returned when evaluate() is called. * return null if function hasn't any parameter, or you wish to use the default SQL types. * use Types.NULL for that specific parameter if you wish to get the default SQL type. * @param functionName * @return the SQL type list or null if functionName is supported */ public int[] getParameterTypes(String functionName); /** * Used to estimate the maximum number of characters that should be contained in a String returned by evaluate(String functionName,Object[] values). * Zero is returned if this value object does not represent Types.VARCHAR, Types.BINARY, Types.LONGVARCHAR, or Types.LONGBINARY. * @param functionName * @return maximum size * @throws SQLException if functionName is supported */ public int estimateValueSize(String functionName) throws SQLException; }
Let us see a sample:
import com.hxtt.sql.ExtendedFunctionInterface; import java.sql.SQLException; import java.sql.Types; /** * Show how to complement some sql functions. * This sample complements tostring(value) and random() for demo purpose */ public class Functions implements ExtendedFunctionInterface { public Functions() { } /** * Used to verify whether functionName is supported, and has a correct prarameter count. * @param functionName the name of function * @param parameters the parameter list of function, which can be null * @return value * @throws SQLException if has an incorrect parameter number */ public boolean isExtendedFunction(String functionName, Object[] parameters) throws SQLException { if (functionName.equalsIgnoreCase("tostring")) { if (parameters != null && parameters.length == 1) { return true; } else { throw new SQLException("Invalid parameter value in tostring function"); } } else if (functionName.equalsIgnoreCase("random")) { if (parameters == null) { return true; } else { throw new SQLException("Invalid parameter value in random function"); } } return false; } /** * Used to evaluate function value. * @param functionName the name of function * @param values the value list of function, which can be null * @return value * @throws SQLException if failed to calculate the function */ public Object evaluate(String functionName, Object[] values) throws SQLException { if (functionName.equalsIgnoreCase("tostring")) { return values[0] + ""; } else if (functionName.equalsIgnoreCase("random")) { return new Double(Math.random()); } throw new SQLException("Inner Error:("); } /** * Used to get the SQL type of the value that is expected to be returned when evaluate() is called. * @param functionName * @return the SQL type or Types.NULL if functionName is supported */ public int getType(String functionName) { if (functionName.equalsIgnoreCase("tostring")) { return Types.VARCHAR; } else if (functionName.equalsIgnoreCase("random")) { return Types.DOUBLE; } return Types.NULL; } /** * Used to get the SQL types of the parameter values that are expected to be returned when evaluate() is called. * return null if function hasn't any parameter, or you wish to use the default SQL types. * use Types.NULL for that specific parameter if you wish to get the default SQL type. * @param functionName * @return the SQL type list or null if functionName is supported */ public int[] getParameterTypes(String functionName) { if (functionName.equalsIgnoreCase("tostring")) { return new int[] { Types.VARCHAR}; } return null; } /** * Used to estimate the maximum number of characters that should be contained in a String returned by evaluate(String functionName,Object[] values). * Zero is returned if this value object does not represent Types.VARCHAR, Types.BINARY, Types.LONGVARCHAR, or Types.LONGBINARY. * @param functionName * @return maximum size * @throws SQLException if functionName is supported */ public int estimateValueSize(String functionName) throws SQLException { if (functionName.equalsIgnoreCase("tostring")) { return 20; } else if (functionName.equalsIgnoreCase("random")) { return 8; } return 10; } }
Then you can use com.hxtt.sql.OpenAPI.registerExtendedFunction("Functions"); to regiester Functions class. Then you can use those user-defined functions in SQL. For instance, "select abs(random()),tostring(date) from test;".
Start/Stop Server Programmatically
If you wish to start a server for remote connections from your application, you can call two functions of com.hxtt.sql.admin.Admin class:
public void startServer(String serverName)throws SQLException
public void stopServer(String serverName)throws SQLException
For instance: try { com.hxtt.sql.admin.Admin admin = new com.hxtt.sql.admin.Admin(); admin.show();//It can be invisible too. admin.startServer("test1"); admin.stopServer("test1"); admin.stopServer("test4"); } catch (SQLException e) { System.out.println(e.getMessage()); }
Get the table structure creation sql from ODBC compatible schema ini file
The method com.hxtt.sql.text.OpenAPI.loadSchemaIniFile function can get the table structure creation sql from odbc compatiable schema ini file, then you can use the statement.executeUpdate function to define the table structure.
loadSchemaIniFile("c:\\textfiles\\schema.ini"); The content in simpleSchema.ini is followed: [Contacts.txt] ColNameHeader=True format=Delimited(" ") MaxScanRows=0 CharacterSet=ANSI Col1="Name" Char Width 10 Col2="Company" Char Width 18 Col3="ConnDate" DATE [conta.cns] ColNameHeader=false Format=CSVDelimited MaxScanRows=25 CharacterSet=OEM This function will return the followed String result: create table "Contacts.txt" ("Name" varchar ( 10),"Company" varchar ( 18),"ConnDate" DATE('yyyy-MM-dd'),_CSV_Separator char(1) default ' ',_CSV_Header boolean default true); create table "conta.cns" (_CSV_Separator char(1) default ',',_CSV_Header boolean default false)