When a connection occurs for a JDBC or Java based ODBC driver built using the SDK the following process occurs to validate the connection settings and establish a connection.

The connection process will use the following methods in your IConnection object:

– public ConnSettingResponseMap updateConnectionSettings(ConnSettingRequestMap requestMap)
– public void connect(ConnSettingRequestMap requestMap)

See the method comments for more detail on each of the parameters.

When a connection occurs, a connection URL is passed to the JDBC driver. As an example, take the connection string “jdbc:simba://User=user;Password=pass”. This connection string is broken down into key-value pairs and stored in a ConnSettingRequestMap, in this case that map would contain two entries: {“User”, “user”} and {“Password”, “pass”}. This map is then passed down to the DSII.

The map is first passed to updateConnectionSettings(), which is responsible for verifying that all of the required, and any optional, connection settings are present. Any settings that are not present should be added to the ConnSettingResponseMap that should be returned. Since this is a common task there are utility functions that can be used to facilitate this: verifyRequiredSetting() and verifyOptionalSetting(). See any of the sample drivers for examples on how to use these functions. You can also manually add entries to the ConnSettingResponseMap  if you don’t want to use the utility functions.

When using a JDBC driver, if all of the required settings are not present during a connection it will fail. There is no mechanism to prompt for more information in JDBC. If there are no required settings in the ConnSettingResponseMap after updateConnectionSettings() has been called, connect() will be called. Note that optional settings can be present in the ConnSettingResponseMap as they are not required for a connection to be made. During connect(), you should have all the needed settings to make a connection as verified by updateConnectionSettings(). You can use the utility functions getRequiredSetting() and getOptionalSetting() to request the required and optional settings for your connection, and attempt to make an actual connection. If a required setting is not present at this stage, it is a logic error and the connection should fail. If verification of any of the settings fails, such as an incorrect user name or password, then either a BadAuthException or an exception with the DIAG_INVALID_AUTH_SPEC DiagState should be thrown.