Implement failover support in jConnect using one of the following two methods:
Use the two connection properties, REQUEST_HA_SESSION and SECONDARY_SERVER_HOSTPORT, and set the following:
Set REQUEST_HA_SESSION to "true."
Set the SECONDARY_SERVER_HOSTPORT to the host name and port number where your secondary server is listening. See “Connection properties”, and the 'SECONDARY_SERVER_HOSTPORT' connection property.
Use JNDI to connect to the server. See “Connecting to a server using JNDI”. Include an entry for the primary server and a separate entry for the secondary server in the directory service information file required by JNDI. The primary server entry has an attribute (the HA OID) that refers to the entry for the secondary server.
Using LDAP as the service provider for JNDI, there are three possible forms that this HA attribute can have:
Relative Distinguished Name (RDN) – this form assumes that the search base (typically provided by the java.naming.provider.url attribute) combined with the value of this attribute is enough to identify the secondary server. For example, assume the primary server is at “hostname:4200” and the secondary server is at “hostname:4202”:
dn: servername=haprimary, o=Sybase, c=US 1.3.6.1.4.1.897.4.2.5: TCP#1#hostname 4200 1.3.6.1.4.1.897.4.2.15: servername=hasecondary objectclass: sybaseServer
dn: servername=hasecondary, o=Sybase, c=US 1.3.6.1.4.1.897.4.2.5: TCP#1#hostname 4202 objectclass: sybaseServer
Distinguished Name (DN) – this form assumes that the value of the HA attribute uniquely identifies the secondary server, and may or may not duplicate values found in the search base. For example:
dn: servername=haprimary, o=Sybase, c=US 1.3.6.1.4.1.897.4.2.5: TCP#1#hostname 4200 1.3.6.1.4.1.897.4.2.15: servername=hasecondary, o=Sybase, c=US ou=Accounting objectclass: sybaseServer
dn: servername=hasecondary, o=Sybase, c=US, ou=Accounting 1.3.6.1.4.1.897.4.2.5: TCP#1#hostname 4202 objectclass: sybaseServer
Notice that hasecondary is
located in a different branch of the tree (see the additional ou=Accounting qualifier).
Full LDAP URL – this form assumes nothing about the search base. The HA attribute is expected to be a fully-qualified LDAP URL that is used to identify the secondary (it may even point to a different LDAP server). For example:
dn: servername=hafailover, o=Sybase, c=US 1.3.6.1.4.1.897.4.2.5: TCP#1#hostname 4200 1.3.6.1.4.1.897.4.2.15: ldap://ldapserver: 386/servername=secondary, o=Sybase, c=US ou=Accounting objectclass: sybaseServer
dn: servername=secondary, o=Sybase, c=US, ou=Accounting 1.3.6.1.4.1.897.4.2.5: TCP#1#hostname 4202 objectclass: sybaseServer
In the directory service information file required by JNDI, set the REQUEST_HA_SESSION connection property to "true" to enable a failover session every time you make a connection.
Use the REQUEST_HA_SESSION connection property to indicate that the connecting client wants to begin a failover session with Adaptive Server that is configured for failover. Setting this property to true instructs jConnect to attempt a failover login. If you do not set this connection property, a failover session does not start, even if the server is configured correctly. The default value for REQUEST_HA_SESSION is false.
Set the connection property like any other connection property. You cannot reset the property once a connection has been made.
If you want more flexibility for requesting failover sessions, code the client application to set REQUEST_HA_SESSION at runtime.The following example shows connection information entered for the database server “SYBASE11” under an LDAP directory service, where “tahiti” is the primary server, and “moorea” is the secondary companion server:
dn: servername=SYBASE11,o=MyCompany,c=US 1.3.6.1.4.1.897.4.2.5:TCP#1#tahiti 3456 1.3.6.1.4.1.897.4.2.10:REPEAT_READ=false&PACKETSIZE=1024 1.3.6.1.4.1.897.4.2.10:CONNECTION_FAILOVER=false 1.3.6.1.4.1.897.4.2.11:pubs2 1.3.6.1.4.1.897.4.2.9:Tds 1.3.6.1.4.1.897.4.2.15:servername=SECONDARY 1.3.6.1.4.1.897.4.2.10:REQUEST_HA_SESSION=true
dn:servername=SECONDARY, o=MyCompany, c=US 1.3.6.1.4.1.897.4.2.5:TCP#1#moorea 6000
Request a connection using JNDI and LDAP:
jConnect uses the directory of the LDAP server to determine the name and location of the primary and secondary servers:
/* get the connection */
Connection con = DriverManager.getConnection
("jdbc:sybase:jndi:ldap://ldap_server1:389" +
"/servername=Sybase11,o=MyCompany,c=US",props);
or
Specify a searchbase:
props.put(Context.PROVIDER_URL, "ldap://ldap_server1:389/ o=MyCompany, c=US");
Connection con=DriverManager.getConnection
("jdbc:sybase:jndi:servername=Sybase11", props);
If an Adaptive Server is not configured for failover or cannot grant a failover session, the client cannot log in, and the following warning displays:
'The server denied your request to use the high- availability feature. Please reconfigure your database, or do not request a high-availability session.'
When failover occurs, the SQL exception JZ0F2 is thrown:
‘Sybase high-availability failover has occurred. The current transaction is aborted, but the connection is still usable. Retry your transaction.’
The client then automatically reconnects to the secondary database using JNDI.
Note that:
The identity of the database to which the client was connected and any committed transactions are retained.
Partially read result sets, cursors, and stored procedure invocations are lost.
When failover occurs, your application may need to restart a procedure or go back to the last completed transaction or activity.
At some point, the client fails back from the secondary server to the primary server. When failback occurs is determined by the System Administrator who issues sp_failback on the secondary server. Afterward, the client can expect the same behavior and results on the primary server as documented in “Failing over to the secondary server”.
