[GATE-24] Updated to handle offline notifications upon disconnect. Also some...

[GATE-24] Updated to handle offline notifications upon disconnect.  Also some documentation updates and such.

git-svn-id: http://svn.igniterealtime.org/svn/repos/wildfire/trunk/src/plugins/gateway@5193 b35dd754-fafc-0310-a699-88a17e54d16e

changelog.html

@@ -28,12 +28,12 @@
         }
       
         TT {
-            font-family : courier new;
+            font-family : courier new, monospace;
             font-weight : bold;
             color : #060;
         }
         PRE {
-            font-family : courier new;
+            font-family : courier new, monospace;
             font-size : 100%;
         }
     </style>
@@ -44,10 +44,10 @@
 IM Gateway Changelog
 </h1>
 
-<p><b>1.0.0</b> -- July X, 2006</p>
+<p><b>0.1</b> -- September 7, 2006</p>
 
 <ul>
-     <li>Initial release.</li>
+     <li>Initial beta release.</li>
 </ul>
 
 

plugin.xml

@@ -8,9 +8,9 @@
     <name>IM Gateway</name>
     <description>Provides gateway connectivity to the other public instant messaging networks</description>
     <author>Daniel Henninger</author>
-    <version>0.0.1</version>
+    <version>0.1</version>
     <date>07/02/2006</date>
-    <minServerVersion>3.0.0</minServerVersion>
+    <minServerVersion>3.1.0</minServerVersion>
     <databaseKey>gateway</databaseKey>
     <databaseVersion>0</databaseVersion>
     <licenseType>gpl</licenseType>

readme.html

@@ -27,12 +27,12 @@
         }
 
         TT {
-            font-family : courier new;
+            font-family : courier new, monospace;
             font-weight : bold;
             color : #060;
         }
         PRE {
-            font-family : courier new;
+            font-family : courier new, monospace;
             font-size : 100%;
         }
     </style>
@@ -45,77 +45,83 @@ IM Gateway Readme
 
 <h2>Overview</h2>
 <p>
-The IM (instant messaging) gateway plugin allows users to log in to and
-communicate through other instant messaging services via their Jabber
-accounts.  The gateway itself provides a number of "transports" to other
-protocols (AIM, ICQ, MSN, Yahoo, etc).
+    The IM (instant messaging) gateway plugin allows users to log in to and
+    communicate through other instant messaging services via their Jabber
+    accounts.  The gateway itself provides a number of "transports" to other
+    protocols (AIM, ICQ, MSN, Yahoo, etc).
 </p>
 
 <h2>Terminology</h2>
 <p>
-To help identify the differences between the plugin as a whole and the
-underlying interfaces to external protocols (AIM, ICQ, etc), we refer
-to the plugin itself as the "gateway" while we refer to the protocol
-handlers as "transports".
+    To help identify the differences between the plugin as a whole and the
+    underlying interfaces to external protocols (AIM, ICQ, etc), we refer
+    to the plugin itself as the "gateway" while we refer to the protocol
+    handlers as "transports".
 </p>
 
 <h2>Installation</h2>
 <p>
-Copy the gateway.jar into the plugins directory of your Wildfire
-installation. The plugin will then be automatically deployed. To upgrade to a
-new version, copy the new gateway.jar file over the existing file.  Please
-be aware that an upgrade will cause all of the users on your server who are
-making use of the plugin to be disconnected from their external IM accounts.
+    Copy the gateway.jar into the plugins directory of your Wildfire
+    installation. The plugin will then be automatically deployed. To upgrade to a
+    new version, copy the new gateway.jar file over the existing file.  Please
+    be aware that an upgrade will cause all of the users on your server who are
+    making use of the plugin to be disconnected from their external IM accounts.
+    Your users should be reconnected after the plugin reloads.
 </p>
 
 <h2>Configuration</h2>
 <p>
-By default, after the plugin has been deployed all of its features are disabled.
-This plugin is configured via the "IM Gateway" sidebar item located under the
-"System" tab in the Wildfire Admin Console.
+    By default, after the plugin has been deployed all of its features are disabled.
+    This plugin is configured via the "Gateways" sidebar item located in the Wildfire
+    Admin Console.  You can enable individual transports via the "Settings" sidebar
+    item, and add new registrations/view existing registrations from the "Registrations"
+    sidebar item.
 </p>
 
 <h2>Using the plugin</h2>
 <p>
-Before going into specifics, there are some important things you need to
-know first.  A user must be registered with a transport in order to make
-use of it.  Registration is the process wherein a user tells a transport
-what username and password will be used with the external service.  This
-process also places the transport JID in their roster to that the
-transport itself can "hear" them come online, and act appropriately (logging
-them in and such).  In this case, we interact with the user's roster directly,
-so there is no need for a flood of subscription requests to the client itself.
-A side effect of this is that only users of the local Wildfire server will
-be able to make use of any transport on the gateway.
+    Before going into specifics, there are some important things you need to
+    know first.  A user must be registered with a transport in order to make
+    use of it.  Registration is the process wherein a user tells a transport
+    what username and password will be used with the external service.  This
+    process also places the transport JID in their roster to that the
+    transport itself can "hear" them come online, and act appropriately (logging
+    them in and such).  In this case, we interact with the user's roster directly,
+    so there is no need for a flood of subscription requests to the client itself.
+    A side effect of this is that only users of the local Wildfire server will
+    be able to make use of any transport on the gateway.  Roster items are created
+    as non-persistent, which means that when the end user logs out or disconnects
+    from the gateway, the associated transport roster items will no longer exist
+    in their roster.
 </p>
 
 <h3>For admins:</h3>
 <p>
-The web interface of the gateway plugin provides a mechanism for setting
-up registrations on a user's behalf, as well as editing and deleting them.
-It also provides tools for monitoring who is using the gateway, their status,
-etc.  In a typical setup, a user will be allowed to register an account
-themselves.  See the next section for details on this.  You can also
-set who has access to the specific transports and even enforce manual
-registrations only.  If a specific transport has any options, they will
-be made available from the web interface.
+    The web interface of the gateway plugin provides a mechanism for setting
+    up registrations on a user's behalf, as well as editing and deleting them.
+    It also provides tools for monitoring who is using the gateway, their status,
+    etc.  In a typical setup, a user will be allowed to register an account
+    themselves.  See the next section for details on this.  You can also
+    set who has access to the specific transports and even enforce manual
+    registrations only.  If a specific transport has any options, they will
+    be made available from the web interface.
 </p>
 
 <h3>For end users:</h3>
 <p>
-Typically, users will use Service Discovery (aka disco) to find out what
-services are available on a server, and then will be provided with a way
-to register with whatever transports are made available.  Some clients
-do not have the functionality to interact with transports.  In this case,
-a server admin will need to register the user on their behalf. (see above)
+    Typically, users will use Service Discovery (aka disco) to find out what
+    services are available on a server, and then will be provided with a way
+    to register with whatever transports are made available.  Some clients
+    do not have the functionality to interact with transports.  In this case,
+    a server admin will need to register the user on their behalf. (see above)
 </p>
 
 <h2>Trouble shooting</h2>
 <p>
-If the plugin behaviour is not as expected you can enable server debug logging.
-This will allow the plugin to start logging.  Server debug logging should only
-be enabled temporarily, as it will generate a lot of additional logging that
-will both slow your server down and consume a lot of disk space.
+    If the plugin behaviour is not as expected you can enable server debug logging.
+    This will allow the plugin to start logging.  Server debug logging should only
+    be enabled temporarily, as it will generate a lot of additional logging that
+    will both slow your server down and consume a lot of disk space.
 </p> 
 </body>
 </html>

src/java/org/jivesoftware/wildfire/gateway/BaseTransport.java

@@ -705,6 +705,7 @@ public abstract class BaseTransport implements Component, RosterEventListener {
         // Disconnect everyone's session
         for (TransportSession session : sessionManager.getSessions()) {
             registrationLoggedOut(session);
+            session.removeAllResources();
         }
         sessionManager.shutdown();
     }
@@ -889,7 +890,7 @@ public abstract class BaseTransport implements Component, RosterEventListener {
      * @param contactjid JID to be removed from roster.
      * @throws UserNotFoundException if userjid not found.
      */
-    void removeFromRoster(JID userjid, JID contactjid) throws UserNotFoundException {
+    public void removeFromRoster(JID userjid, JID contactjid) throws UserNotFoundException {
         // Clean up the user's contact list.
         try {
             Roster roster = rosterManager.getRoster(userjid.getNode());
@@ -1075,7 +1076,7 @@ public abstract class BaseTransport implements Component, RosterEventListener {
     }
 
     /**
-     * Cleans a roster of entries related to this transport.
+     * Cleans a roster of entries related to this transport that are not shared.
      *
      * This function will run through the roster of the specified user and clean up any
      * entries that share the domain of this transport.  This is primarily used during registration
@@ -1111,6 +1112,34 @@ public abstract class BaseTransport implements Component, RosterEventListener {
         }
     }
 
+    /**
+     * Sends offline packets for an entire roster to the target user.
+     *
+     * This function will run through the roster of the specified user and send offline
+     * presence packets for each roster item.   This is typically used when a user logs
+     * off so that all of the associated roster items appear offline.  This also sends
+     * the unavailable presence for the transport itself.
+     *
+     * @param jid JID of user whose roster we want to clean up.
+     * @throws UserNotFoundException if the user is not found.
+     */
+    public void notifyRosterOffline(JID jid) throws UserNotFoundException {
+        try {
+            Roster roster = rosterManager.getRoster(jid.getNode());
+            for (RosterItem ri : roster.getRosterItems()) {
+                if (ri.getJid().getDomain().equals(this.jid.getDomain())) {
+                    Presence p = new Presence(Presence.Type.unavailable);
+                    p.setTo(jid);
+                    p.setFrom(ri.getJid());
+                    sendPacket(p);
+                }
+            }
+        }
+        catch (UserNotFoundException e) {
+            throw new UserNotFoundException("Unable to find roster.");
+        }
+    }
+
     /**
      * Sends a packet through the component manager as the component.
      *

src/java/org/jivesoftware/wildfire/gateway/TransportSession.java

@@ -11,6 +11,8 @@
 package org.jivesoftware.wildfire.gateway;
 
 import org.xmpp.packet.JID;
+import org.jivesoftware.wildfire.user.UserNotFoundException;
+
 import java.util.TreeMap;
 
 /**
@@ -92,11 +94,26 @@ public abstract class TransportSession implements Runnable {
         for (Integer i : resources.keySet()) {
             if (resources.get(i).equals(resource)) {
                 resources.remove(i);
+                try {
+                    getTransport().notifyRosterOffline(new JID(getJID().getNode(),getJID().getDomain(),resource));
+                }
+                catch (UserNotFoundException e) {
+                    // Don't care
+                }
                 break;
             }
         }
     }
 
+    /**
+     * Removes all resources associated with a session.
+     */
+    public void removeAllResources() {
+        for (String resource : resources.values()) {
+            removeResource(resource); 
+        }
+    }
+
     /**
      * Returns the number of active resources.
      *

src/java/org/jivesoftware/wildfire/gateway/TransportSessionManager.java

@@ -14,6 +14,7 @@ import java.util.*;
 
 import org.jivesoftware.util.NotFoundException;
 import org.jivesoftware.wildfire.SessionManager;
+import org.jivesoftware.wildfire.user.UserNotFoundException;
 import org.xmpp.packet.JID;
 
 /**
@@ -108,6 +109,13 @@ public class TransportSessionManager {
      */
     public void removeSession(JID jid) {
         activeSessions.remove(new JID(jid.toBareJID()));
+        try {
+            getTransport().notifyRosterOffline(jid);
+        }
+        catch (UserNotFoundException e) {
+            // Don't care
+        }
+
     }
 
     /**
@@ -143,4 +151,12 @@ public class TransportSessionManager {
         }
     }
 
+    /**
+     * Retrieves the transport this session manager is associated with.
+     *
+     * @return transport associated with this session manager.
+     */
+    public BaseTransport getTransport() {
+        return this.transport;
+    }
 }