Qorus Integration Engine®  4.0.3_git
com.qoretechnologies.qorus.DbRemoteReceive Class Reference

Java wrapper for the OMQ::DbRemoteReceive class in Qorus. More...

Inheritance diagram for com.qoretechnologies.qorus.DbRemoteReceive:
org::qore::jni::QoreObjectWrapper

Public Member Methods

 DbRemoteReceive (QoreObject obj)
 creates the object as a wrapper for the Qore object
 
 DbRemoteReceive (DbRemote remote, String stream, String table_name, HashMap< String, Object > options) throws Throwable
 constructor taking a DbRemote object for the remote server More...
 
 DbRemoteReceive (DbRemote remote, String stream, String table_name) throws Throwable
 constructor taking a DbRemote object for the remote server More...
 
 DbRemoteReceive (String remote, String datasource, String stream, String table_name, HashMap< String, Object > options) throws Throwable
 constructor taking a string giving the name of the remote connection for the remote server More...
 
 DbRemoteReceive (String remote, String datasource, String stream, String table_name) throws Throwable
 constructor taking a string giving the name of the remote connection for the remote server More...
 
 DbRemoteReceive (QorusSystemRestHelper remote, String datasource, String stream, String table_name, HashMap< String, Object > options) throws Throwable
 constructor taking a com.qoretechnologies.qorus.QorusSystemRestHelper object for the remote server More...
 
 DbRemoteReceive (QorusSystemRestHelper remote, String datasource, String stream, String table_name) throws Throwable
 constructor taking a com.qoretechnologies.qorus.QorusSystemRestHelper object for the remote server More...
 
void openStream (String stream, String table_name, HashMap< String, Object > options) throws Throwable
 flushes the current stream and reopens a new stream with the same remote connection and in the same datasources More...
 
void openStream (String stream, String table_name) throws Throwable
 flushes the current stream and reopens a new stream with the same remote connection and in the same datasources More...
 
void commit () throws Throwable
 Commit remote transaction. More...
 
void rollback (boolean disconnect) throws Throwable
 Rollback remote transaction. More...
 
void disconnect () throws Throwable
 Disconnects the connection.
 
void rollback () throws Throwable
 Rollback remote transaction and disconnect the connection. More...
 
HashMap< String, ObjectgetData (int timeout_ms) throws Throwable
 returns queued data as soon as it is available, if the timeout is omitted or equal or less than 0, no timeout is used and the call will block until data is available on the queue; once this method return null it signifies that the end of stream data condition has been reached; do not call this method again after it returns null More...
 
HashMap< String, ObjectgetData () throws Throwable
 returns queued data as soon as it is available, no timeout is used and the call will block until data is available on the queue; once this method return null it signifies that the end of stream data condition has been reached; do not call this method again after it returns null More...
 
HashMap< String, ObjectgetAllData (int timeout_ms) throws Throwable
 Returns all data received by the object in a single call, if the timeout is omitted or equal or less than 0, no timeout is used and the call will block until data is available on the queue. More...
 
HashMap< String, ObjectgetAllData () throws Throwable
 Returns all data received by the object in a single call, no timeout is used and the call will block until data is available on the queue. More...
 
HashMap< String, Object > [] getDataRows (int timeout_ms) throws Throwable
 
HashMap< String, Object > [] getDataRows () throws Throwable
 
HashMap< String, Object > [] getAllDataRows (int timeout_ms) throws Throwable
 returns all data recevied by the object in a single call as a list of rows, if the timeout is omitted or equal or less than 0, no timeout is used and the call will block until data is available on the queue More...
 
HashMap< String, Object > [] getAllDataRows () throws Throwable
 returns all data recevied by the object in a single call as a list of rows, no timeout is used and the call will block until data is available on the queue More...
 
StreamConfig config () throws Throwable
 returns the configuration object
 

Detailed Description

Java wrapper for the OMQ::DbRemoteReceive class in Qorus.

Constructor & Destructor Documentation

◆ DbRemoteReceive() [1/6]

com.qoretechnologies.qorus.DbRemoteReceive.DbRemoteReceive ( DbRemote  remote,
String  stream,
String  table_name,
HashMap< String, Object options 
) throws Throwable
inline

constructor taking a DbRemote object for the remote server

Parameters
remotea DbRemote object
streamthe system.sqlutil service stream to be used
table_namea string with remote table name located in the remote datasource
optionsoptional Streaming API Constructor Options as follows:
  • "block": data block size; the number of rows to retrieve from the remote database and send in each block
  • "block_queue_size": the number of blocks to queue for receiving before the I/O thread will block (default: 2); the total number of rows that can be queued = block_queue_size * block
  • "timeout": an HTTP socket timeout value in milliseconds; used locally and in the remote for socket I/O and queue operations; default value: 5m
  • "loglevel": a default log level option for logging; see Log Levels for valid value
  • "no_remote_timeout": if True the "timeout" option will not be sent to the remote
  • "select": select options for the source select statement
  • "transaction": start a remote transaction; if this option is not given, the remote transaction status is left unchanged
Note
  • a remote transaction is only started in this object's constructor if the transaction option is set, otherwise the remote transaction status is left unchanged
  • the explicit or default timeout value here overrides any socket I/O timeout set for the remote connection object

◆ DbRemoteReceive() [2/6]

com.qoretechnologies.qorus.DbRemoteReceive.DbRemoteReceive ( DbRemote  remote,
String  stream,
String  table_name 
) throws Throwable
inline

constructor taking a DbRemote object for the remote server

Parameters
remotea DbRemote object
streamthe system.sqlutil service stream to be used
table_namea string with remote table name located in the remote datasource
Note
the explicit or default timeout value here overrides any socket I/O timeout set for the remote connection object

◆ DbRemoteReceive() [3/6]

com.qoretechnologies.qorus.DbRemoteReceive.DbRemoteReceive ( String  remote,
String  datasource,
String  stream,
String  table_name,
HashMap< String, Object options 
) throws Throwable
inline

constructor taking a string giving the name of the remote connection for the remote server

Parameters
remotethe name of the remote connection for the remote server
datasourcea string with name of the remote datasource to use
streamthe system.sqlutil service stream to be used
table_namea string with remote table name located in the remote datasource
optionsoptional Streaming API Constructor Options as follows:
  • "block": data block size; the number of rows to retrieve from the remote database and send in each block
  • "block_queue_size": the number of blocks to queue for receiving before the I/O thread will block (default: 2); the total number of rows that can be queued = block_queue_size * block
  • "timeout": an HTTP socket timeout value in milliseconds; used locally and in the remote for socket I/O and queue operations; default value: 5m
  • "loglevel": a default log level option for logging; see Log Levels for valid value
  • "no_remote_timeout": if True the "timeout" option will not be sent to the remote
  • "select": select options for the source select statement
  • "transaction": start a remote transaction; if this option is not given, the remote transaction status is left unchanged
Note
  • a remote transaction is only started in this object's constructor if the transaction option is set, otherwise the remote transaction status is left unchanged
  • the explicit or default timeout value here overrides any socket I/O timeout set for the remote connection object

◆ DbRemoteReceive() [4/6]

com.qoretechnologies.qorus.DbRemoteReceive.DbRemoteReceive ( String  remote,
String  datasource,
String  stream,
String  table_name 
) throws Throwable
inline

constructor taking a string giving the name of the remote connection for the remote server

Parameters
remotethe name of the remote connection for the remote server
datasourcea string with name of the remote datasource to use
streamthe system.sqlutil service stream to be used
table_namea string with remote table name located in the remote datasource
Note
the explicit or default timeout value here overrides any socket I/O timeout set for the remote connection object

◆ DbRemoteReceive() [5/6]

com.qoretechnologies.qorus.DbRemoteReceive.DbRemoteReceive ( QorusSystemRestHelper  remote,
String  datasource,
String  stream,
String  table_name,
HashMap< String, Object options 
) throws Throwable
inline

constructor taking a com.qoretechnologies.qorus.QorusSystemRestHelper object for the remote server

Parameters
remotea com.qoretechnologies.qorus.QorusSystemRestHelper object
datasourcea string with name of the remote datasource to use
streamthe system.sqlutil service stream to be used
table_namea string with remote table name located in the remote datasource
optionsoptional Streaming API Constructor Options as follows:
  • "block": data block size; the number of rows to retrieve from the remote database and send in each block
  • "block_queue_size": the number of blocks to queue for receiving before the I/O thread will block (default: 2); the total number of rows that can be queued = block_queue_size * block
  • "timeout": an HTTP socket timeout value in milliseconds; used locally and in the remote for socket I/O and queue operations; default value: 5m
  • "loglevel": a default log level option for logging; see Log Levels for valid value
  • "no_remote_timeout": if True the "timeout" option will not be sent to the remote
  • "select": select options for the source select statement
  • "transaction": start a remote transaction; if this option is not given, the remote transaction status is left unchanged
Note
  • a remote transaction is only started in this object's constructor if the transaction option is set, otherwise the remote transaction status is left unchanged
  • the explicit or default timeout value here overrides any socket I/O timeout set for the remote connection object

◆ DbRemoteReceive() [6/6]

com.qoretechnologies.qorus.DbRemoteReceive.DbRemoteReceive ( QorusSystemRestHelper  remote,
String  datasource,
String  stream,
String  table_name 
) throws Throwable
inline

constructor taking a com.qoretechnologies.qorus.QorusSystemRestHelper object for the remote server

Parameters
remotea com.qoretechnologies.qorus.QorusSystemRestHelper object
datasourcea string with name of the remote datasource to use
streamthe system.sqlutil service stream to be used
table_namea string with remote table name located in the remote datasource
Note
  • a remote transaction is only started in this object's constructor if the transaction option is set, otherwise the remote transaction status is left unchanged
  • the explicit or default timeout value here overrides any socket I/O timeout set for the remote connection object

Member Function Documentation

◆ commit()

void com.qoretechnologies.qorus.DbRemoteReceive.commit ( ) throws Throwable
inline

Commit remote transaction.

Note
exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread

◆ getAllData() [1/2]

HashMap<String, Object> com.qoretechnologies.qorus.DbRemoteReceive.getAllData ( int  timeout_ms) throws Throwable
inline

Returns all data received by the object in a single call, if the timeout is omitted or equal or less than 0, no timeout is used and the call will block until data is available on the queue.

Examples:
DbRemoteReceive recv = new DbRemoteReceive(qrest, "omquser", "select", table_name, opts);
try {
HashMap<String, Object> h = recv.getAllData(300000);
if (h != null) {
processData(h);
}
} catch (Throwable e) {
recv.disconnect();
throw e;
} finally {
recv.release();
}
Parameters
timeout_msan override for the the timeout for waiting on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally with a maximum resolution of milliseconds; if the timeout limit is exceeded before data is available, a QUEUE-TIMEOUT error is thrown. If no value is given here, the default queue timeout value configured for the object is used (see the "queue_timeout" option in the constructor)
Returns
a hash is returned where keys = columns, values = lists of row values, or null if no data was returned
Exceptions
DB-REMOTE-RECEIVE-ERRORthis exception is thrown if this method is called after it returns null signifying end of stream
QUEUE-TIMEOUTno data was posted to the queue in the timeout period
STREAM-TERMINATEDif the I/O thread was terminated prematurely, this exception will be thrown
Note
  • exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread
  • any exception thrown in this method (I/O error or timeout error) will cause all data to be lost; when this method returns (either normally or due to an exception), the data complete flag is set and no more data can be retrieved from the object

◆ getAllData() [2/2]

HashMap<String, Object> com.qoretechnologies.qorus.DbRemoteReceive.getAllData ( ) throws Throwable
inline

Returns all data received by the object in a single call, no timeout is used and the call will block until data is available on the queue.

Examples:
DbRemoteReceive recv = new DbRemoteReceive(qrest, "omquser", "select", table_name, opts);
try {
HashMap<String, Object> h = recv.getAllData();
if (h != null) {
processData(h);
}
} catch (Throwable e) {
recv.disconnect();
throw e;
} finally {
recv.release();
}
Returns
a hash is returned where keys = columns, values = lists of row values, or null if no data was returned
Exceptions
DB-REMOTE-RECEIVE-ERRORthis exception is thrown if this method is called after it returns null signifying end of stream
QUEUE-TIMEOUTno data was posted to the queue in the timeout period
STREAM-TERMINATEDif the I/O thread was terminated prematurely, this exception will be thrown
Note
  • exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread
  • any exception thrown in this method (I/O error or timeout error) will cause all data to be lost; when this method returns (either normally or due to an exception), the data complete flag is set and no more data can be retrieved from the object

◆ getAllDataRows() [1/2]

HashMap<String, Object> [] com.qoretechnologies.qorus.DbRemoteReceive.getAllDataRows ( int  timeout_ms) throws Throwable
inline

returns all data recevied by the object in a single call as a list of rows, if the timeout is omitted or equal or less than 0, no timeout is used and the call will block until data is available on the queue

Examples:
try {
HashMap<String, Object>[] l = recv.getAllDataRows();
if (l != null) {
processData(h);
}
} catch (Throwable e) {
recv.disconnect();
throw e;
} finally {
recv.release();
}
Parameters
timeout_msan override for the the timeout for waiting on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally with a maximum resolution of milliseconds; if the timeout limit is exceeded before data is available, a QUEUE-TIMEOUT error is thrown. If no value is given here, the default queue timeout value configured for the object is used (see the "queue_timeout" option in the constructor)
Returns
a list of rows or null if no data was returned
Exceptions
DB-REMOTE-RECEIVE-ERRORthis exception is thrown if this method is called after it returns null signifying end of stream
QUEUE-TIMEOUTno data was posted to the queue in the timeout period
STREAM-TERMINATEDif the I/O thread was terminated prematurely, this exception will be thrown
Note
  • exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread
  • any exception thrown in this method (I/O error or timeout error) will cause all data to be lost; when this method returns (either normally or due to an exception), the data complete flag is set and no more data can be retrieved from the object
  • the native column format is converted to row format for the return value of this method

◆ getAllDataRows() [2/2]

HashMap<String, Object> [] com.qoretechnologies.qorus.DbRemoteReceive.getAllDataRows ( ) throws Throwable
inline

returns all data recevied by the object in a single call as a list of rows, no timeout is used and the call will block until data is available on the queue

Examples:
try {
HashMap<String, Object>[] l = recv.getAllDataRows();
if (l != null) {
processData(h);
}
} catch (Throwable e) {
recv.disconnect();
throw e;
} finally {
recv.release();
}
Returns
a list of rows or null if no data was returned
Exceptions
DB-REMOTE-RECEIVE-ERRORthis exception is thrown if this method is called after it returns null signifying end of stream
QUEUE-TIMEOUTno data was posted to the queue in the timeout period
STREAM-TERMINATEDif the I/O thread was terminated prematurely, this exception will be thrown
Note
  • exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread
  • any exception thrown in this method (I/O error or timeout error) will cause all data to be lost; when this method returns (either normally or due to an exception), the data complete flag is set and no more data can be retrieved from the object
  • the native column format is converted to row format for the return value of this method

◆ getData() [1/2]

HashMap<String, Object> com.qoretechnologies.qorus.DbRemoteReceive.getData ( int  timeout_ms) throws Throwable
inline

returns queued data as soon as it is available, if the timeout is omitted or equal or less than 0, no timeout is used and the call will block until data is available on the queue; once this method return null it signifies that the end of stream data condition has been reached; do not call this method again after it returns null

Examples:
DbRemoteReceive recv = new DbRemoteReceive(qrest, "omquser", "select", table_name, opts);
try {
while (true) {
HashMap<String, Object> h = recv.getData(120000);
if (h == null) {
break;
}
processData(h);
}
} catch (Throwable e) {
recv.disconnect();
throw e;
} finally {
recv.release();
}
Parameters
timeout_msan override for the the timeout for waiting on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally with a maximum resolution of milliseconds; if the timeout limit is exceeded before data is available, a QUEUE-TIMEOUT error is thrown. If no value is given here, the default queue timeout value configured for the object is used (see the "queue_timeout" option in the constructor)
Returns
a hash of lists: keys = columns, values = lists of row values or null if all data has been received (do not call this method again after it returns null)
Exceptions
DB-REMOTE-RECEIVE-ERRORthis exception is thrown if this method is called after it returns null signifying end of stream
QUEUE-TIMEOUTthis exception is thrown if a timeout occurs on the Queue
STREAM-TERMINATEDif the I/O thread was terminated prematurely, this exception will be thrown
Note
exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread

◆ getData() [2/2]

HashMap<String, Object> com.qoretechnologies.qorus.DbRemoteReceive.getData ( ) throws Throwable
inline

returns queued data as soon as it is available, no timeout is used and the call will block until data is available on the queue; once this method return null it signifies that the end of stream data condition has been reached; do not call this method again after it returns null

Examples:
DbRemoteReceive recv = new DbRemoteReceive(qrest, "omquser", "select", table_name, opts);
try {
while (true) {
HashMap<String, Object> h = recv.getData();
if (h == null) {
break;
}
processData(h);
}
} catch (Throwable e) {
recv.disconnect();
throw e;
} finally {
recv.release();
}
Returns
a hash of lists: keys = columns, values = lists of row values or null if all data has been received (do not call this method again after it returns null)
Exceptions
DB-REMOTE-RECEIVE-ERRORthis exception is thrown if this method is called after it returns null signifying end of stream
QUEUE-TIMEOUTthis exception is thrown if a timeout occurs on the Queue
STREAM-TERMINATEDif the I/O thread was terminated prematurely, this exception will be thrown
Note
exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread

◆ getDataRows() [1/2]

HashMap<String, Object> [] com.qoretechnologies.qorus.DbRemoteReceive.getDataRows ( int  timeout_ms) throws Throwable
inline
Examples:
DbRemoteReceive recv = new DbRemoteReceive(qrest, "omquser", "select", table_name, opts);
try {
while (true) {
HashMap<String, Object>[] l = recv.getDataRows(120000);
if (l == null) {
break;
}
processData(h);
}
} catch (Throwable e) {
recv.disconnect();
throw e;
} finally {
recv.release();
}
Parameters
timeout_msan override for the the timeout for waiting on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally with a maximum resolution of milliseconds; if the timeout limit is exceeded before data is available, a QUEUE-TIMEOUT error is thrown. If no value is given here, the default queue timeout value configured for the object is used (see the "queue_timeout" option in the constructor)
Returns
a list of row data or null if all data has been received (do not call this method again after it returns null)
Exceptions
DB-REMOTE-RECEIVE-ERRORthis exception is thrown if this method is called after it returns null signifying end of stream
QUEUE-TIMEOUTthis exception is thrown if a timeout occurs on the Queue
STREAM-TERMINATEDif the I/O thread was terminated prematurely, this exception will be thrown
Note
  • exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread
  • the native column format is converted to row format for the return value of this method

◆ getDataRows() [2/2]

HashMap<String, Object> [] com.qoretechnologies.qorus.DbRemoteReceive.getDataRows ( ) throws Throwable
inline
Examples:
DbRemoteReceive recv = new DbRemoteReceive(qrest, "omquser", "select", table_name, opts);
try {
while (true) {
HashMap<String, Object>[] l = recv.getDataRows();
if (l == null) {
break;
}
processData(h);
}
} catch (Throwable e) {
recv.disconnect();
throw e;
} finally {
recv.release();
}
Returns
a list of row data or null if all data has been received (do not call this method again after it returns null)
Exceptions
DB-REMOTE-RECEIVE-ERRORthis exception is thrown if this method is called after it returns null signifying end of stream
QUEUE-TIMEOUTthis exception is thrown if a timeout occurs on the Queue
STREAM-TERMINATEDif the I/O thread was terminated prematurely, this exception will be thrown
Note
  • exceptions thrown in the socket I/O thread will be rethrown when this method is called so that errors can be handled in the main data thread
  • the native column format is converted to row format for the return value of this method

◆ openStream() [1/2]

void com.qoretechnologies.qorus.DbRemoteReceive.openStream ( String  stream,
String  table_name,
HashMap< String, Object options 
) throws Throwable
inline

flushes the current stream and reopens a new stream with the same remote connection and in the same datasources

Example:
out.openStream("update", "table2");
Parameters
streamthe system.sqlutil service stream to be used
table_namea string with remote table name located in the remote datasource
optionsoptional Streaming API Constructor Options as follows:
  • "timeout": an HTTP socket timeout value in milliseconds; used locally and in the remote for socket I/O and queue operations; default value: 5m
  • "loglevel": a default log level option for logging; see Java Log Levels for valid value
  • "block": data block size
  • "no_remote_timeout": if True the "timeout" option will not be sent to the remote
  • "queue_block_size": the number of blocks to queue for sending before the main data thread will block (default: 2)
  • "queue_timeout": the number of milliseconds to wait for queue data before throwing a QUEUE-TIMEOUT exception
Note
the explicit or default timeout value here overrides any socket I/O timeout set for the remote connection object

◆ openStream() [2/2]

void com.qoretechnologies.qorus.DbRemoteReceive.openStream ( String  stream,
String  table_name 
) throws Throwable
inline

flushes the current stream and reopens a new stream with the same remote connection and in the same datasources

Example:
out.openStream("update", "table2");
Parameters
streamthe system.sqlutil service stream to be used
table_namea string with remote table name located in the remote datasource

◆ rollback() [1/2]

void com.qoretechnologies.qorus.DbRemoteReceive.rollback ( boolean  disconnect) throws Throwable
inline

Rollback remote transaction.

Note
it's normally better to disconnect the connection if an error occurs rather than call rollback() when streaming because if a chunked transfer is interrupted, then HTTP calls will fail anyway, and the remote end will rollback the transaction in any case unless an explicit commit is executed
Parameters
disconnecta boolean value to keep connection open or close the connection. Connection closing is the default
See also
disconnect()

◆ rollback() [2/2]

void com.qoretechnologies.qorus.DbRemoteReceive.rollback ( ) throws Throwable
inline

Rollback remote transaction and disconnect the connection.

Note
it's normally better to disconnect the connection if an error occurs rather than call rollback() when streaming because if a chunked transfer is interrupted, then HTTP calls will fail anyway, and the remote end will rollback the transaction in any case unless an explicit commit is executed
See also
disconnect()

The documentation for this class was generated from the following file: