Scripted SQL Connector

The Scripted SQL Connector uses Groovy scripts to interact with a JDBC database.

This chapter describes the structure and configuration of the Scripted SQL Connector, the operations that are supported by the connector, and the connector schema. The Scripted SQL Connector does not support connector pooling.

Scripted SQL Connector Reference Object

The Scripted SQL Connector has the following unique identifiers, expressed here in JSON format.

"connectorRef" : {
    "bundleName" : "org.openidentityplatform.openicf.connectors.groovy-connector",
    "bundleVersion" : "[1.4.0.0,2)",
    "connectorName" : "org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector"
}

You can use OpenIDM to generate this configuration automatically when you configure the connector. Alternatively, you can copy this section and paste it directly into your connector configuration file (provisioner.openicf-connector-name.json). (for example, provisioner.openicf-scriptedsql.json

Samples

Scripted SQL

OpenICF Interfaces Implemented by the Scripted SQL Connector

Authenticate

Provides simple authentication with two parameters, presumed to be a user name and password.

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Resolve Username

Resolves an object by its username and returns the uid of the object.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics:

• The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
• The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.
• The script has access to any script-arguments passed in by the application.

Script on Resource

Runs a script on the target resource that is managed by this connector.

Search

Searches the target resource for all objects that match the specified object class and filter.

Sync

Polls the target resource for synchronization events, that is, native changes to objects on the target resource.

Test

Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

Scripted SQL Connector Configuration

Configuration Properties

Property	Description	Type	Default	Encrypted	Required
password	The connection password to be passed to our JDBC driver to establish a connection. Note that method DataSource.getConnection(username,password) by default will not use credentials passed into the method, but will use the ones configured here. See alternateUsernameAllowed property for more details.	GuardedString	null	Yes	No
customConfiguration	Custom Configuration script for Groovy ConfigSlurper	String	null		No
customSensitiveConfiguration	Custom Sensitive Configuration script for Groovy ConfigSlurper	GuardedString	null	Yes	No
maxIdle	The maximum number of connections that should be kept in the pool at all times. Default value is maxActive:100 Idle connections are checked periodically (if enabled) and connections that been idle for longer than minEvictableIdleTimeMillis will be released. (also see testWhileIdle)	int	100		No
jdbcInterceptors	A semicolon separated list of classnames extending org.apache.tomcat.jdbc.pool.JdbcInterceptor class. See Configuring JDBC interceptors below for more detailed description of syntaz and examples. These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object. The default value is null.	String	null		No
defaultTransactionIsolation	The default TransactionIsolation state of connections created by this pool. One of the following: NONE, READ_COMMITTED, READ_UNCOMMITTED, REPEATABLE_READ, SERIALIZABLE If not set, the method will not be called and it defaults to the JDBC driver.	int	-1		No
validationQuery	The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query does not have to return any data, it just cant throw a SQLException. The default value is null. Example values are SELECT 1(mysql), select 1 from dual(oracle), SELECT 1(MS Sql Server)	String	null		No
testOnConnect		boolean	false		No
abandonWhenPercentageFull	Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are above the percentage defined by abandonWhenPercentageFull. The value should be between 0-100. The default value is 0, which implies that connections are eligible for closure as soon as removeAbandonedTimeout has been reached.	int	0		No
testOnReturn	The indication of whether objects will be validated before being returned to the pool. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. The default value is false.	boolean	false		No
username	The connection username to be passed to our JDBC driver to establish a connection. Note that method DataSource.getConnection(username,password) by default will not use credentials passed into the method, but will use the ones configured here. See alternateUsernameAllowed property for more details.	String	null		No
minIdle	The minimum number of established connections that should be kept in the pool at all times. The connection pool can shrink below this number if validation queries fail. Default value is derived from initialSize:10 (also see testWhileIdle)	int	10		No
dataSourceJNDI	The JNDI name for a data source to be looked up in JNDI and then used to establish connections to the database. See the dataSource attribute. Default value is null	String	null		No
validationInterval	avoid excess validation, only run validation at most at this frequency - time in milliseconds. If a connection is due for validation, but has been validated previously within this interval, it will not be validated again. The default value is 30000 (30 seconds).	long	30000		No
ignoreExceptionOnPreLoad	Flag whether ignore error of connection creation while initializing the pool. Set to true if you want to ignore error of connection creation while initializing the pool. Set to false if you want to fail the initialization of the pool by throwing exception.	boolean	false		No
accessToUnderlyingConnectionAllowed	Property not used. Access can be achieved by calling unwrap on the pooled connection. see javax.sql.DataSource interface, or call getConnection through reflection or cast the object as javax.sql.PooledConnection	boolean	true		No
url		String	null		No
defaultReadOnly	The default read-only state of connections created by this pool. If not set then the setReadOnly method will not be called. (Some drivers dont support read only mode, ex: Informix)	boolean	false		No
rollbackOnReturn	If autoCommit==false then the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool Default value is false.	boolean	false		No
alternateUsernameAllowed	By default, the jdbc-pool will ignore the DataSource.getConnection(username,password) call, and simply return a previously pooled connection under the globally configured properties username and password, for performance reasons. The pool can however be configured to allow use of different credentials each time a connection is requested. To enable the functionality described in the DataSource.getConnection(username,password) call, simply set the property alternateUsernameAllowed to true. Should you request a connection with the credentials user1/password1 and the connection was previously connected using different user2/password2, the connection will be closed, and reopened with the requested credentials. This way, the pool size is still managed on a global level, and not on a per schema level.	boolean	false		No
initSQL	A custom query to be run when a connection is first created. The default value is null.	String	null		No
validatorClassName	The name of a class which implements the org.apache.tomcat.jdbc.pool.Validator interface and provides a no- arg constructor (may be implicit). If specified, the class will be used to create a Validator instance which is then used instead of any validation query to validate connections. The default value is null. An example value is com.mycompany.project.SimpleValidator.	String	null		No
defaultCatalog	The default catalog of connections created by this pool.	String	null		No
testOnBorrow	The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. In order to have a more efficient validation, see validationInterval. Default value is false	boolean	false		No
connectionProperties	The connection properties that will be sent to our JDBC driver when establishing new connections. Format of the string must be [propertyName=property;] NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here. The default value is null.	String	null		No
useDisposableConnectionFacade	Set this to true if you wish to put a facade on your connection so that it cannot be reused after it has been closed. This prevents a thread holding on to a reference of a connection it has already called closed on, to execute queries on it.	boolean	true		No
maxActive	The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100	int	100		No
maxAge	Time in milliseconds to keep this connection. When a connection is returned to the pool, the pool will check to see if the now - time-when-connected > maxAge has been reached, and if so, it closes the connection rather than returning it to the pool. The default value is 0, which implies that connections will be left open and no age check will be done upon returning the connection to the pool.	long	0		No
suspectTimeout	Timeout value in seconds. Similar to to the removeAbandonedTimeout value but instead of treating the connection as abandoned, and potentially closing the connection, this simply logs the warning if logAbandoned is set to true. If this value is equal or less than 0, no suspect checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets logged and a JMX notification gets sent once.	int	0		No
numTestsPerEvictionRun		int	0		No
name		String	Tomcat Connection Pool		No
maxWait	The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. Default value is 30000 (30 seconds)	int	30000		No
defaultAutoCommit	The default auto-commit state of connections created by this pool. If not set, default is JDBC driver default (If not set then the setAutoCommit method will not be called.)	boolean	null		No
commitOnReturn	If autoCommit==false then the pool can complete the transaction by calling commit on the connection as it is returned to the pool If rollbackOnReturn==true then this attribute is ignored. Default value is false.	boolean	false		No
jmxEnabled	Register the pool with JMX or not. The default value is true.	boolean	true		No
validationQueryTimeout	The timeout in seconds before a connection validation queries fail. This works by calling java.sql.Statement.setQueryTimeout(seconds) on the statement that executes the validationQuery. The pool itself doesnt timeout the query, it is still up to the JDBC driver to enforce query timeouts. A value less than or equal to zero will disable this feature. The default value is -1.	int	-1		No
testWhileIdle	The indication of whether objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. The default value is false and this property has to be set in order for the pool cleaner/test thread is to run (also see timeBetweenEvictionRunsMillis)	boolean	false		No
useEquals	Set to true if you wish the ProxyConnection class to use String.equals and set to false when you wish to use == when comparing method names. This property does not apply to added interceptors as those are configured individually. The default value is true.	boolean	true		No
useLock		boolean	false		No
driverClassName	The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible from the same classloader as tomcat-jdbc.jar	String	null		No
logValidationErrors	Set this to true to log errors during the validation phase to the log file. If set to true, errors will be logged as SEVERE. Default value is false for backwards compatibility.	boolean	false		No
removeAbandonedTimeout	Timeout in seconds before an abandoned(in use) connection can be removed. The default value is 60 (60 seconds). The value should be set to the longest running query your applications might have.	int	60		No
fairQueue	Set to true if you wish that calls to getConnection should be treated fairly in a true FIFO fashion. This uses the org.apache.tomcat.jdbc.pool.FairBlockingQueue implementation for the list of the idle connections. The default value is true. This flag is required when you want to use asynchronous connection retrieval. Setting this flag ensures that threads receive connections in the order they arrive. During performance tests, there is a very large difference in how locks and lock waiting is implemented. When fairQueue=true there is a decision making process based on what operating system the system is running. If the system is running on Linux (property os.name=Linux. To disable this Linux specific behavior and still use the fair queue, simply add the property org.apache.tomcat.jdbc.pool.FairBlockingQueue.ignoreOS=true to your system properties before the connection pool classes are loaded.	boolean	true		No
logAbandoned	Flag to log stack traces for application code which abandoned a Connection. Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated. The default value is false.	boolean	false		No
removeAbandoned	Flag to remove abandoned connections if they exceed the removeAbandonedTimeout. If set to true a connection is considered abandoned and eligible for removal if it has been in use longer than the removeAbandonedTimeout Setting this to true can recover db connections from applications that fail to close a connection. See also logAbandoned The default value is false.	boolean	false		No
timeBetweenEvictionRunsMillis	The number of milliseconds to sleep between runs of the idle connection validation/cleaner thread. This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often we validate idle connections. The default value is 5000 (5 seconds).	int	5000		No
minEvictableIdleTimeMillis	The minimum amount of time an object may sit idle in the pool before it is eligible for eviction. The default value is 60000 (60 seconds).	int	60000		No
initialSize	The initial number of connections that are created when the pool is started. Default value is 10	int	10		No
propagateInterruptState	Set this to true to propagate the interrupt state for a thread that has been interrupted (not clearing the interrupt state). Default value is false for backwards compatibility.	boolean	false		No

Groovy Engine configuration Properties

Property	Description	Type	Default	Encrypted	Required
targetDirectory	Directory into which to write classes	File	null		No
warningLevel	Warning Level of the compiler	int	1		No
scriptExtensions	Description is not available	String[]	['groovy']		No
minimumRecompilationInterval	Sets the minimum of time after a script can be recompiled.	int	100		No
scriptBaseClass	Base class name for scripts (must derive from Script)	String	null		No
scriptRoots	The root folder to load the scripts from. If the value is null or empty the classpath value is used.	String[]	null		Yes
tolerance	The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.	int	10		No
debug	If true, debugging code should be activated	boolean	false		No
classpath	Classpath for use during compilation.	String[]	[]		No
disabledGlobalASTTransformations	Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/ org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled.	String[]	null		No
verbose	If true, the compiler should produce action information	boolean	false		No
sourceEncoding	Encoding for source files	String	UTF-8		No
recompileGroovySource	If set to true recompilation is enabled	boolean	false		No

Operation Script Files Properties

Property	Description	Type	Default	Encrypted	Required
createScriptFileName	The name of the file used to perform the CREATE operation.	String	null		Create
customizerScriptFileName	The script used to customize some function of the connector. Read the documentation for more details.	String	null		No
authenticateScriptFileName	The name of the file used to perform the AUTHENTICATE operation.	String	null		Authenticate
scriptOnResourceScriptFileName	The name of the file used to perform the RUNSCRIPTONRESOURCE operation.	String	null		Script On Resource
deleteScriptFileName	The name of the file used to perform the DELETE operation.	String	null		Delete
resolveUsernameScriptFileName	The name of the file used to perform the RESOLVE_USERNAME operation.	String	null		Resolve Username
searchScriptFileName	The name of the file used to perform the SEARCH operation.	String	null		Get Search
updateScriptFileName	The name of the file used to perform the UPDATE operation.	String	null		Update
schemaScriptFileName	The name of the file used to perform the SCHEMA operation.	String	null		Schema
testScriptFileName	The name of the file used to perform the TEST operation.	String	null		Test
syncScriptFileName	The name of the file used to perform the SYNC operation.	String	null		Sync