com.eibus.applicationconnector.sql

Class WCPDBConnection

java.lang.Object

DBConnection

com.eibus.applicationconnector.sql.WCPDBConnection

public class WCPDBConnection
extends DBConnection

Provides public API to access XQY layer

Field Summary

Fields

Modifier and Type	Field and Description
static int	WCP_E_ACCESS_DENIED
static int	WCP_E_CONNECTION_FAILED
static int	WCP_E_TUPLE_CHANGED
static int	WCP_E_UNKNOWN_ERROR

Constructor Summary

Constructors

Constructor and Description
WCPDBConnection(int dso) Deprecated. Use the connection pool com.eibus.applicationconnector.sql.DBConnectionPool instead of constructing independent connections yourself.

Method Summary

Modifier and Type	Method and Description
int	abortCurrentTransaction() Aborts the current update transaction
int	commitCurrentTransaction() Commits the current update transaction
int	createAuditTable(int node) Method to create a audit-table for a given table.
int	executeDDL(int metadata) Method to execute any SQL DDL command against the backend data source This DDL execution is autocommit in nature, ie., any DDL execution can't be rolled back.
int	executeDML(int commandNode) Method to execute any SQL DML command against the backend data source This will normally be inside a transaction.
java.lang.String	getConditionString(int node)
int	getErrorCode() Gets the current error code.
IStringResource	getErrorMessage() Returns localized error message.
IStringResource	getErrorMessage(int xqyErrorNode) Returns localized error message.
int	getMetaData(int metadata, AccessControlObject accessControlObject) Method to retrieve metadata from backend data source
boolean	getNullPrecedence() Sets or unsets priority for null="true" over data if both are peresent in a node
int	purgeAuditTable(int node) Method to purge a audit-table.
int	query(int constructor, AccessControlObject accessControlObject) Method to read data from backend data source
void	resetConnectionCache() resetConnectionCache will clear the PreparedStatement/resultset/metadata Cache on Current Connection Object this api should not be used when connection is processing some request it can be used when you just got a connection from connection pool or before putting back the connection into connection pool.
protected void	setConnectionId(int connectionId)
void	setExtendeddbConnectionProperties(IConnectionCustomizer connectionCustomizer) Set extended connection properties on this connection
void	setNullPrecedence(boolean priority) Sets or unsets priority for null="true" over data if both are peresent in a node
java.lang.String	toString()
void	unSetExtendeddbConnectionProperties() Unset extended connection properties
int	update(int update, AccessControlObject accessControlObject) Method to update data in backend data source
int	validateCommand(int validate) Method to validate an SQL query against the backend data source It returns the metadata information of the resultset returned by the query

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

WCP_E_CONNECTION_FAILED

public static int WCP_E_CONNECTION_FAILED

WCP_E_ACCESS_DENIED

public static int WCP_E_ACCESS_DENIED

WCP_E_TUPLE_CHANGED

public static int WCP_E_TUPLE_CHANGED

WCP_E_UNKNOWN_ERROR

public static int WCP_E_UNKNOWN_ERROR

Constructor Detail

WCPDBConnection

public WCPDBConnection(int dso)

Deprecated. Use the connection pool com.eibus.applicationconnector.sql.DBConnectionPool instead of constructing independent connections yourself.

Creates a database connection object with given database connection properties

Parameters:

dso - A pointer to a native XML tree containing configuration information for the Database Connection

Example
For OLEDB connector
<dso dataSource ="cin1145" driver="OLEDB" provider="SQLOLEDB" userId="sa" password="" update="true" defaultDB="Northwind"/>
For JDBC connector
<dso jdbcDriver="oracle.jdbc.driver.OracleDriver" driver="JDBC" update="true" defaultDB="SCOTT" connectionString="jdbc:oracle:thin:@test:1521:ORCL" userId="scott" password="dGlnZXI=">

More description about each attribute
driver - 'OLEDB' for OleDB connectivity, 'JDBC' for JDBC connectivity
userId - database User name
password - Base64 encoded password
defaultDB - default database to be connected. See OLEDB connector documentation for more details
update - true/false.
Is it an update connection or not??
If it is read-only connection, then some optimizations will be done at driver level to improve performance.

OLEDB specific attributes
dataSource - The backend datasource. The value given for 'datasource' in OLEDB SOAP processor properties
provider - OLEDB provider to be used. See OLEDB connector documentation for more details

JDBC specific attributes
jdbcDriver - the JDBC driver class to be used. See JDBC connector documentation for more details
connectionString - the connection string contains the inputs to connect the database. See JDBC connector documentation for its format & more details

In DB connection object, cursor & query cache are maintained internally.
The user can also specify the size & refresh intervals for the cache.
Example
<dso dataSource ="cin1145" driver="OLEDB" provider="SQLOLEDB" userId="sa" password="" update="true" defaultDB="Northwind">
<cursor-cache>
<size>1000</size>
<refresh-interval>3600</refresh-interval>
</cursor-cache>
<query-cache>
<size>1000</size>
<refresh-interval>3600</refresh-interval>
</query-cache>
</dso>
Default cache size is 1000 and default refresh interval is 3600 seconds

Method Detail

query

public int query(int constructor,
                 AccessControlObject accessControlObject)

Method to read data from backend data source

Parameters:

constructor - A pointer to a native XML tree containing SQL query information in Cordys Integrator protocol format

accessControlObject - The user access control information which can be obtained using 'getAccessControlObject' method of 'com.eibus.security.ac.Registration' class

Returns:

returns 0 if SUCCESS, less than 0 if FAILURE

Example for 'constructor' parameter
<dataset>
<constructor language="DBSQL">
<query>select * from Employees where EmployeeID = :EmployeeID</query>
<parameters>
<EmployeeID dd="Employees.EmployeeID">1</EmployeeID>
</parameters>
</constructor>
</dataset>

update

public int update(int update,
                  AccessControlObject accessControlObject)

Method to update data in backend data source

Parameters:

update - A pointer to a native XML tree containing SQL update query information in Cordys Integrator protocol format

accessControlObject - The user access control information which can be obtained using 'getAccessControlObject' method of 'com.eibus.security.ac.Registration' class

Returns:

returns 0 if SUCCESS, less than 0 if FAILURE

Example for 'update' parameter
<dataset>
<update>
<tuple>
<old>
<Employees>
<EmployeeID>1</EmployeeID>
<FirstName>Nancy</FirstName>
</Employees>
</old>
<new>
<Employees>
<EmployeeID>1</EmployeeID>
<FirstName>Nancy123</FirstName>
</Employees>
</new>
</tuple>
</update>
</dataset>

getMetaData

public int getMetaData(int metadata,
                       AccessControlObject accessControlObject)

Method to retrieve metadata from backend data source

Parameters:

metadata - A pointer to a native XML tree containing SQL query information in Cordys Integrator protocol format

accessControlObject - The user access control information which can be obtained using 'getAccessControlObject' method of 'com.eibus.security.ac.Registration' class

Returns:

returns 0 if SUCCESS, less than 0 if FAILURE

Example for 'metadata' parameter
<metadata
requestType="getTableInfo"
tableCatalog="Northwind"
tableSchema=""
tableName="Employees"
tableType="TABLE"/>

The above example returns the table information about 'Employees' table in 'Northwind' catalog

requestType - The type of metadata request. Possible values are
'getTables' - gets all tables from datasource
'getTableInfo' - gets the table information
'getProcedures' - gets all the procedures from datasource
'getProcedureInfo' - gets the procedure information
'getBackEndInfo' - gets the database product name and database connector name

Other attributes acts as the filters for the metadata retrieval.
Possible values for 'tableType' are 'TABLE'/'VIEW'.

validateCommand

public int validateCommand(int validate)

Method to validate an SQL query against the backend data source
It returns the metadata information of the resultset returned by the query

Parameters:

validate - A pointer to a native XML tree containing SQL query information in Cordys Integrator protocol format

accessControlObject - The user access control information which can be obtained using 'getAccessControlObject' method of 'com.eibus.security.ac.Registration' class

Returns:

returns 0 if SUCCESS, less than 0 if FAILURE

Example for 'validate' parameter
<dataset>
<validate>
<query> select * from Employees where EmployeeID = :EmployeeID</query>
</validate>
</dataset>


The above example returns the resultset metadata returned the query

executeDDL

public int executeDDL(int metadata)

Method to execute any SQL DDL command against the backend data source
This DDL execution is autocommit in nature, ie., any DDL execution can't be rolled back.

Parameters:

metadata - A pointer to a native XML tree containing SQL DDL command in Cordys Integrator protocol format

Returns:

returns 0 if SUCCESS, less than 0 if FAILURE

Example for 'metadata' parameter
<implementation>
<metadata> create table temp_table (field1 int primary key, field2 varchar(20))</metadata>
</implementation>

executeDML

public int executeDML(int commandNode)

Method to execute any SQL DML command against the backend data source
This will normally be inside a transaction. So application needs to commit or abort the transaction.

Parameters:

commandNode - A native xml node representing the dml request in the expected format

Returns:

returns 0 if SUCCESS, less than 0 if FAILURE

Example for 'DML'
<executeDML> <DML> <command>insert into XQY_EXECUTEDML(INT1,FLOAT1, INT1, NVARCHAR1, VARCHAR1, DATETIME1, NUMERIC1) values(:BIGINT1, :FLOAT1, :INT1, :NVARCHAR1, :VARCHAR1, :DATETIME1, :NUMERIC1)</command> <parameters> <BIGINT1 dd="XQY_EXECUTEDML.INT1">1002</BIGINT1> <FLOAT1 dt="r8">1002.1234</FLOAT1> <INT1 dd="XQY_EXECUTEDML">1002</INT1> <NVARCHAR1 dd="XQY_EXECUTEDML.NVARCHAR1">Test1002</NVARCHAR1> <VARCHAR1 dd="XQY_EXECUTEDML.VARCHAR1" guid="true"/> <DATETIME1 dd="XQY_EXECUTEDML.DATETIME1">2007-12-12T12:12:12.123456789</DATETIME1> <NUMERIC1 dd="XQY_EXECUTEDML.NUMERIC1">1002</NUMERIC1> </parameters> </DML> <DML> .......... </DML> </executeDML>

After execution the number of rows affected by the DML statement will be present in the rows tag.

commitCurrentTransaction

public int commitCurrentTransaction()

Commits the current update transaction

Returns:

returns 0 if the commit SUCCESS, else returns less than 0 if FAILURE

abortCurrentTransaction

public int abortCurrentTransaction()

Aborts the current update transaction

Returns:

returns 0 if the abort SUCCESS, else returns less than 0 if FAILURE

createAuditTable

public int createAuditTable(int node)

Method to create a audit-table for a given table.

Parameters:

node - A pointer to a native XML tree containing table-node and an auditTable-node

Returns:

returns 0 if SUCCESS, less than 0 if FAILURE

Example for 'createAuditTable'. Recommended Usage.
<dataset>
<createAuditTable>
<table>Employees</table>
<auditTable version="1" >Employees_Audit</auditTable>
</createAuditTable>
</dataset>
Example for 'createAuditTable'. NOT Recommended as there is no GUID in the Primary key of the audit-table.
<dataset>
<createAuditTable>
<table>Employees</table>
<auditTable>Employees_Audit</auditTable>
</createAuditTable>
</dataset>

purgeAuditTable

public int purgeAuditTable(int node)

Method to purge a audit-table.

Parameters:

node - A pointer to a native XML tree containing auditTable-node

Returns:

returns 0 if SUCCESS, less than 0 if FAILURE

Example for 'purgeAuditTable'.
<dataset>
<purgeAuditTable>
<auditTable>Employees_Audit</auditTable>
</purgeAuditTable>
</dataset>

setNullPrecedence

public void setNullPrecedence(boolean priority)

Sets or unsets priority for null="true" over data if both are peresent in a node

Parameters:

priority - - boolean value denoting the priority for null="true"

setExtendeddbConnectionProperties

public void setExtendeddbConnectionProperties(IConnectionCustomizer connectionCustomizer)

Set extended connection properties on this connection

Parameters:

: - connectionCustomizer - an instance of implementation of com.cordys.xqy.connection.IConnectionCustomizer

unSetExtendeddbConnectionProperties

public void unSetExtendeddbConnectionProperties()

Unset extended connection properties

getNullPrecedence

public boolean getNullPrecedence()

Sets or unsets priority for null="true" over data if both are peresent in a node

Returns:

returns true if null has priority ,else returns false

getErrorCode

public int getErrorCode()

Gets the current error code. Once error code is returned, existing error details will be cleared.Subsequent calls will return 0 till another error occurs.

Returns:

returns Cordys Error code if error occurs, else returns 0

getConditionString

public java.lang.String getConditionString(int node)

setConnectionId

protected void setConnectionId(int connectionId)

toString

public java.lang.String toString()

getErrorMessage

public IStringResource getErrorMessage()

Returns localized error message. This error message contains both the the message and the corresponding insertions.

Returns:

Error message in IStringResource form if error exists, else null It will always returns a IStringResource for first found error element if xml node contains multiple error elements

getErrorMessage

public IStringResource getErrorMessage(int xqyErrorNode)

Returns localized error message. This error message contains both the the message and the corresponding insertions.

Parameters:

The - request xml node which caused error.

Returns:

Error message in IStringResource form if error exists, else null It will always returns a IStringResource for first found error element if xml node contains multiple error elements

resetConnectionCache

public void resetConnectionCache()

resetConnectionCache will clear the PreparedStatement/resultset/metadata Cache on Current Connection Object this api should not be used when connection is processing some request it can be used when you just got a connection from connection pool or before putting back the connection into connection pool.