Revamped the basic Presents client to support attempts to connect to the server

on multiple ports, falling back from one to the next as appropriate.


git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@4158 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/java/com/threerings/presents/client/ClientObserver.java

@@ -1,5 +1,5 @@
 //
-// $Id: ClientObserver.java,v 1.9 2004/08/27 02:20:18 mdb Exp $
+// $Id$
 //
 // Narya library - tools for developing networked games
 // Copyright (C) 2002-2004 Three Rings Design, Inc., All Rights Reserved
@@ -53,6 +53,14 @@ public interface ClientObserver extends SessionObserver
      * Called if anything fails during the logon attempt. This could be a
      * network failure, authentication failure or otherwise. The exception
      * provided will indicate the cause of the failure.
+     *
+     * @param cause an exception indicating the cause of the logon failure.
+     * <em>Note:</em> this may be a {@link LogonException} and if so, the
+     * caller <em>must</em> check {@link LogonException#isStillInProgress} to
+     * find out if the logon process has totally failed or if we are simply
+     * reporting intermediate status (we might be falling back to an
+     * alternative port or delaying our auto-retry attempt due to server
+     * overload).
      */
     public void clientFailedToLogon (Client client, Exception cause);