Widening.

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

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

@@ -22,67 +22,56 @@
 package com.threerings.presents.client;
 
 /**
- * A client observer is a more detailed version of the {@link
+ * A client observer is a more detailed version of the {@link SessionObserver} for entities that
- * SessionObserver} for entities that are interested in more detail about
+ * are interested in more detail about the logon/logoff process.
- * the logon/logoff process.
  *
- * <p> In the normal course of affairs, <code>clientDidLogon</code> will
+ * <p> In the normal course of affairs, {@link #clientDidLogon} will be called after the client
- * be called after the client successfully logs on to the server and
+ * successfully logs on to the server and {@link #clientDidLogoff} will be called after the client
- * <code>clientDidLogoff</code> will be called after the client logs off
+ * logs off of the server. If logon fails for any reson, {@link #clientFailedToLogon} will be
- * of the server. If logon fails for any reson,
+ * called to explain the failure.
- * <code>clientFailedToLogon</code> will be called to explain the failure.
  *
- * <p> <code>clientWillLogoff</code> will only be called when an abortable
+ * <p> {@link #clientWillLogoff} will only be called when an abortable logoff is requested (like
- * logoff is requested (like when the user clicks on a logoff button of
+ * when the user clicks on a logoff button of some sort). It will not be called during
- * some sort). It will not be called during non-abortable logoff requests
+ * non-abortable logoff requests (like when the browser calls stop on the applet and is about to
- * (like when the browser calls stop on the applet and is about to yank
+ * yank the rug out from under us). If an observer aborts the logoff request, it should notify the
- * the rug out from under us). If an observer aborts the logoff request,
+ * user in some way why the request was aborted (<em>but it shouldn't do so on the thread that
- * it should notify the user in some way why the request was aborted
+ * calls {@link #clientWillLogoff}</em>).
- * (<em>but it shouldn't do so on the thread that calls
- * <code>clientWillLogoff</code></em>).
  *
- * <p> If the client connection fails unexpectedly,
+ * <p> If the client connection fails unexpectedly, {@link #clientConnectionFailed} will be called
- * <code>clientConnectionFailed</code> will be called to let the
+ * to let the observers know that we lost our connection to the server. {@link #clientDidLogoff}
- * observers know that we lost our connection to the
+ * will be called immediately afterwards as a normal logoff procedure is effected.
- * server. <code>clientDidLogoff</code> will be called immediately
- * afterwards as a normal logoff procedure is effected.
  */
 public interface ClientObserver extends SessionObserver
 {
     /**
-     * Called if anything fails during the logon attempt. This could be a
+     * Called if anything fails during the logon attempt. This could be a network failure,
-     * network failure, authentication failure or otherwise. The exception
+     * authentication failure or otherwise. The exception provided will indicate the cause of the
-     * provided will indicate the cause of the failure.
+     * failure.
      *
-     * @param cause an exception indicating the cause of the logon failure.
+     * @param cause an exception indicating the cause of the logon failure.  <em>Note:</em> this
-     * <em>Note:</em> this may be a {@link LogonException} and if so, the
+     * may be a {@link LogonException} and if so, the caller <em>must</em> check {@link
-     * caller <em>must</em> check {@link LogonException#isStillInProgress} to
+     * LogonException#isStillInProgress} to find out if the logon process has totally failed or if
-     * find out if the logon process has totally failed or if we are simply
+     * we are simply reporting intermediate status (we might be falling back to an alternative port
-     * reporting intermediate status (we might be falling back to an
+     * or delaying our auto-retry attempt due to server overload).
-     * alternative port or delaying our auto-retry attempt due to server
-     * overload).
      */
     public void clientFailedToLogon (Client client, Exception cause);
 
     /**
-     * Called when the connection to the server went away for some
+     * Called when the connection to the server went away for some unexpected reason. This will be
-     * unexpected reason. This will be followed by a call to
+     * followed by a call to {@link #clientDidLogoff}.
-     * <code>clientDidLogoff</code>.
      */
     public void clientConnectionFailed (Client client, Exception cause);
 
     /**
-     * Called when an abortable logoff request is made. If the observer
+     * Called when an abortable logoff request is made. If the observer returns false from this
-     * returns false from this method, the client will abort the logoff
+     * method, the client will abort the logoff request.
-     * request.
      */
     public boolean clientWillLogoff (Client client);
 
     /**
-     * Called after the client is completely logged off from a successful
+     * Called after the client is completely logged off from a successful session and is ready to
-     * session and is ready to reconnect to a new server if desired. This will
+     * reconnect to a new server if desired. This will only be called after an active session was
-     * only be called after an active session was terminated, not after a logon
+     * terminated, not after a logon attempt failed as that failure will be reported by {@link
-     * attempt failed as that failure will be reported by {@link
      * #clientFailedToLogon}.
      */
     public void clientDidClear (Client client);

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

@@ -22,9 +22,8 @@
 package com.threerings.presents.client;
 
 /**
- * A session observer is registered with the client instance to be
+ * A session observer is registered with the client instance to be notified when the client
- * notified when the client establishes and ends their session with the
+ * establishes and ends their session with the server.
- * server.
  *
  * @see ClientObserver
  */
@@ -36,23 +35,20 @@ public interface SessionObserver
     public void clientWillLogon (Client client);
 
     /**
-     * Called after the client successfully connected to and authenticated
+     * Called after the client successfully connected to and authenticated with the server. The
-     * with the server. The entire object system is up and running by the
+     * entire object system is up and running by the time this method is called.
-     * time this method is called.
      */
     public void clientDidLogon (Client client);
 
     /**
-     * For systems that allow switching screen names after logon, this
+     * For systems that allow switching screen names after logon, this method is called whenever a
-     * method is called whenever a screen name change takes place to
+     * screen name change takes place to report that the client object has been replaced to
-     * report that the client object has been replaced to potential
+     * potential client-side subscribers.
-     * client-side subscribers.
      */
     public void clientObjectDidChange (Client client);
 
     /**
-     * Called after the client has been logged off of the server and has
+     * Called after the client has been logged off of the server and has disconnected.
-     * disconnected.
      */
     public void clientDidLogoff (Client client);
 }