Implementing Failover in jConnect

Set:

REQUEST_HA_SESSION to true.
SECONDARY_SERVER_HOSTPORT to the host name and port number where your secondary server is listening.

Use JNDI to connect to the server. 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) – 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) – 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 – 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

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 doses 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.

This example shows connection information entered for the database server SYBASE1 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:

Use 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);

Failover process allows:

Logging in to the primary server – if an Adaptive Server is not configured for failover or cannot grant a failover session, the client cannot log in.
```
'The server denied your request to use the high-
availability feature.

Please reconfigure your database, or do not request a
high-availability session.'
```
Failing over to secondary server – 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 automatically reconnects to the secondary database using JNDI and lets you:
- Identity 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.
- Restart your application with a procedure or return to the last completed transaction or activity.
Failing back to primary server – the system administrator determines the timing of failback, by issuing sp_failback on the secondary server. The client fails back from the secondary server to the primary server.
After failback, the client can expect the same behavior and results on the primary server during failover to the secondary server.