title: How do I use openWithFailover() on a Lotus Domino database?
body: <p>I've got some Java code that uses the Java Domino API (using the NCSO.jar) to connect with Domino databases over IIOP. A new requirement now is that if the server being connected to is clustered, it should be possible to take advantage of this and switch to a failover server in the cluster should the one currently connected to fail.</p>
  
  <p>Unfortunately the Domino Java API is downright arcane, with subtle differences between using the API locally and remotely over IIOP, few really clear explanations and weird differences depending on the arguments that you feed the methods.</p>
  
  <p>Some information I managed to glean from here...
  <a href="http://www.poweroftheschwartz.com/web/blog/poweroftheschwartz.nsf/d6plinks/RSCZ-8HWT27" rel="nofollow">Does the openWithFailoverMethod work?</a></p>
  
  <p>I've also checked the documentation on the IBM infocenter.</p>
  
  <p>First thing I tried was this:</p>
  
  <pre><code>Session session = NotesFactory.createSession(host + ":" + port, user, password);
  Database db = session.getDatabase(null, databaseName, false);
  db.openWithFailover(host, databaseName);
  </code></pre>
  
  <p>The first argument of <code>getDatabase</code>, the server name, apparently must be null for IIOP operations. I was rather mystified by how it would be necessary to specify the server name again in the <code>openWithFailover</code> method when it's already in the session, but I suppose you can connecto to a cluster with the session and then specify the primary server in the open method. Why you needed to provide a database name twice wasn't quite clear, however. That last argument states the database should not be created if it can't be accessed (omit that and it's default true; how wonderful).</p>
  
  <p>Unfortunately this spat the exception <code>NotesException: This database object is already open as E:\Lotus\Domino\data\mail-in\EDITEST.nsf</code> in my face. It occurs on the line with the <code>openWithFailover</code> method.</p>
  
  <p>So apparently that first call to <code>getDatabase</code> already opens it, and there's no close method or an option to only get the object without actually opening it.
  The <code>Database</code> class is an interface, so no static methods to obtain such an object or a way of instantiating it otherwise. I checked around and the only alternative I find is using <code>openDatabase</code> in class <code>DbDirectory</code>. Guess what that does. Now that method does have an alternative with a boolean that states if you wish to use failover, but according <a href="http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=/com.ibm.designer.domino.main.doc/H_OPEN_METHOD_JAVA.html" rel="nofollow">to the documentation</a> it is always false for IIOP oprations.</p>
  
  <p>According to <a href="http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=/com.ibm.designer.domino.main.doc/H_OPENING_AND_CLOSING_A_DATABASE_JAVA.html" rel="nofollow">this page</a>, you can get an empty <code>Database</code> object by calling <code>getDatabase</code> with two null arguments. So I tried this:</p>
  
  <pre><code>Session session = NotesFactory.createSession(host + ":" + port, user, password);
  Database db = session.getDatabase(null, null, false);
  db.openWithFailOver(host, databaseName);
  </code></pre>
  
  <p>Which prompty gives me exception <code>NotesException: A database name must be provided</code>.
  Changing the second line to <code>Database db = session.getDatabase(null, null);</code> doesn't make a difference.</p>
  
  <p>I can only assume that a database name is mandatory for remote operations? But then how can failover be used at all when connecting remotely? Or am I doing this incorrectly? Maybe I should connect to the cluster instead of the server itself and the failover gets handled automatically? Or is failover plainly impossible for remote connections? The Notes client can do it, so I'd expect it to be possible in your own Java code.</p>
  
  <p>Somebody please help me out here, because the documentation just doesn't provide enough info.</p>