|
Utility class that may be used when (Java-)coding classes and methods in USoft Service Definer.
With USoftService, you can control transaction behaviour precisely. USoftService allows you to execute multiple statements within the same transaction.
Constructor method that creates a connection to the rules engine.
Syntax
public USoftService( String connection, Class<?> forClass )
throws InstantiationException
The connection parameter is the name of the connection used to connect to the Rules Engine, as defined in Service Definer. This parameter is required, but if you do not want to name a specific connection, you can pass the wildcard string value "*" for it, in which case a connection is randomly chosen from the list of Connections in Service Definer associated with the class or service named by the forClass parameter.
The required forClass identifies the Service Definer class where the connection is used. In Service Definer, you can query this class in either the Classes window or the Services window, depending on whether it is a generic class or a service. Both these windows have a Connection tab that lists the connection(s) used.
Exceptions
|
Thrown if
|
InstantiationException
|
The connection parameter names a specific connection, but no connection by that name is found among the connections associated with the class or service named by the forClass parameter.
The value "*" is passed for the connection parameter, but no connections are found associated with the class or service named by the forClass parameter.
|
|
Constructor method that creates a connection to the rules engine associated with the specified username/password combination.
Syntax
public USoftService( String userName, String password, String connection, Class<?> forClass )
throws InstantiationException
The required userName is the user who connects to the Rules Engine.
The required password is the password used to connect to the Rules Engine.
The connection parameter is the name of the connection used to connect to the Rules Engine, as defined in Service Definer. This parameter is required, but if you do not want to name a specific connection, you can pass the wildcard string value "*" for it, in which case a connection is randomly chosen from the list of Connections in Service Definer associated with the class or service named by the forClass parameter.
The required forClass identifies the Service Definer class where the connection is used. In Service Definer, you can query this class in either the Classes window or the Services window, depending on whether it is a generic class or a service. Both these windows have a Connection tab that lists the connection(s) used.
Exceptions
|
Thrown if
|
InstantiationException
|
The connection parameter names a specific connection, but no connection by that name is found among the connections associated with the class or service named by the forClass parameter.
The value "*" is passed for the connection parameter, but no connections are found associated with the class or service named by the forClass parameter.
|
|
Closes the Rules Engine connection.
Syntax
public void close()
|
Gets the last generated value for a primary key column based on a domain that generates unique values.
Syntax
public Integer getLastGeneratedUniqueValue()
throws SQLException
Exceptions
|
Thrown if
|
SQLException
|
An error is raised by the Rules Engine.
|
See also
USoftService example code
|
Opens a connection to the rules engine.
Syntax
public void open()
throws REConnectException
Exceptions
|
Thrown if
|
REConnectException
|
A connection to the rules engine could not be established. The cause may be that the username/password combination is incorrect, or that the rule service has not been started.
|
|
Opens a connection to the rules engine with the specified username and password.
Syntax
public void open( String username, String pwd )
throws REConnectException
Exceptions
|
Thrown if
|
REConnectException
|
A connection to the rules engine could not be established. The cause may be that the username/password combination is incorrect, or that the rule service has not been started.
|
|
Executes a given SQL statement in an already open Rules Engine connection. Does not specify any action to be performed after SQL execution.
Returns the result set retrieved by the statement, serialized to the specified output class.
Syntax
public <T> T sql( Class<T> outputClass, String statementName, Object[] inputParameters )
throws IllegalArgumentException, SQLException
The required outputClass is the type of object that the caller requires the function to return. This is typically, but not necessarily, the name of a structure defined in the Services Definer. For details on allowed output classes, see " Java output classes returned by sql() ".
The required statementName is the name of the SQL statement as defined in USoft Service Definer.
inputParameters is an array of one or more objects that match host variables used in the statement (notated using the ':' prefix) one by one. The inputParameters parameter is required, but if the statement does not use any host variables, you can call the function passing the parameter value new Object[0] instead of (a) specific value(s).
Exceptions
|
Thrown if
|
IllegalArgumentException
|
No statement with the specified name is defined for the service, or the input parameters do not match the host variables defined in the statement.
|
SQLException
|
An error is raised by the Rules Engine.
|
|
Executes a given SQL statement that is a manipulation (INSERT, UPDATE, or DELETE) in an already open Rules Engine connection. Specifies which action must be performed after SQL execution relative to transaction behaviour (commit, rollback...), OR specifies that no such action is desired.
Returns the result set retrieved by the statement, serialized to the specified output class.
Syntax
public <T> T sql( Class<T> outputClass, String statementName, Object[] inputParameters, String TransactionMode )
throws IllegalArgumentException, SQLException
The required outputClass is the type of object that the caller requires the function to return. This is typically, but not necessarily, the name of a structure defined in the Services Definer. For details on allowed output classes, see " Java output classes returned by sql() ".
The required statementName is the name of the SQL INSERT, UPDATE, or DELETE statement as defined in USoft Service Definer.
inputParameters is an array of one or more objects that match host variables used in the statement (notated using the ':' prefix) one by one. The inputParameters parameter is required, but if the statement does not use any host variables, you can call the function passing the parameter value new Object[0] instead of (a) specific value(s).
TransactionMode is a required string parameter that must have 1 of the following values. You will find detailed information about rules being executed at record-store time, pre-commit time and commit time in the "Rules Engine Guide" section of the USoft Definer Help in USoft 9 product documentation.
Value
|
Meaning
|
RuleService.Commit
|
Following SQL execution, the transaction is committed.
You can inspect the effect of this commit by executing a SELECT statement as a subsequent action.
|
RuleService.Precommit
|
Following SQL execution, any rules evaluated at pre-commit time are executed.
You can inspect the effect of these rules by executing a SELECT statement as a subsequent action. After this inspection you can decide to either commit or rollback this effect.
|
RuleService.NoTransaction
|
Following SQL execution, no specific action is performed relative to the transaction.
|
RuleService.Rollback
|
Following SQL execution, the transaction is rolled back.
The effect of any non-committed SQL manipulations, including the effect (if any) of executing the statement identified by statementName, is rolled back. Use this TransactionMode setting only to test if executing the statement would raise any errors raised at record-store time.
|
Exceptions
|
Thrown if
|
IllegalArgumentException
|
No statement with the specified name is defined for the service, or the input parameters do not match the host variables defined in the statement.
|
SQLException
|
An error is raised by the Rules Engine.
|
|
Returns the last RulesService warning after executing a sql statement.
Syntax
public SQLWarning getWarning()
Example
USoftService usoft = null;
try {
usoft = new USoftService(username, password, "EmployeeAppConnection", this.getClass());
usoft.open();
usoft.sql(Integer.class, "Update_Employee", new Object[]{ empl });
if( usoft.warningHasOccurred() ){
Logger log = Logger.getLogger( this.getClass() );
log.warn("A warning has occurred while updating an employee -> " + usoft.getWarning());
}
}
finally {
if( usoft != null )
usoft.close();
}
|
Returns a boolean to indicate if a warning has occurred during the last sql statement. If the result is true, a warning has occurred.
Syntax
public boolean warningHasOccurred()
|
See also
USoftService example code
|
