Improve DeliveryReceipt code, add javadoc

Also make Packet.getExtension() use Generics

smack-core/src/main/java/org/jivesoftware/smack/packet/Packet.java

@@ -240,7 +240,8 @@ public abstract class Packet {
      * @param namespace the XML element namespace of the packet extension.
      * @return the extension, or <tt>null</tt> if it doesn't exist.
      */
-    public PacketExtension getExtension(String elementName, String namespace) {
+    @SuppressWarnings("unchecked")
+    public <PE extends PacketExtension> PE getExtension(String elementName, String namespace) {
         if (namespace == null) {
             return null;
         }
@@ -248,7 +249,7 @@ public abstract class Packet {
             if ((elementName == null || elementName.equals(ext.getElementName()))
                     && namespace.equals(ext.getNamespace()))
             {
-                return ext;
+                return (PE) ext;
             }
         }
         return null;

smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceipt.java

@@ -1,6 +1,6 @@
 /**
  *
- * Copyright the original author or authors
+ * Copyright 2013-2014 the original author or authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@ package org.jivesoftware.smackx.receipts;
 import java.util.List;
 import java.util.Map;
 
+import org.jivesoftware.smack.packet.Packet;
 import org.jivesoftware.smack.packet.PacketExtension;
 import org.jivesoftware.smack.provider.EmbeddedExtensionProvider;
 
@@ -63,6 +64,16 @@ public class DeliveryReceipt implements PacketExtension
         return "<received xmlns='" + NAMESPACE + "' id='" + id + "'/>";
     }
 
+    /**
+     * Get the {@link DeliveryReceipt} extension of the packet, if any.
+     *
+     * @param p the packet
+     * @return the {@link DeliveryReceipt} extension or {@code null}
+     */
+    public static DeliveryReceipt getFrom(Packet p) {
+        return p.getExtension(ELEMENT, NAMESPACE);
+    }
+
     /**
      * This Provider parses and returns DeliveryReceipt packets.
      */

smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceiptManager.java

@@ -1,6 +1,6 @@
 /**
  *
- * Copyright 2013 Georg Lukas
+ * Copyright 2013-2014 Georg Lukas
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,8 +43,7 @@ import org.jivesoftware.smackx.disco.ServiceDiscoveryManager;
  */
 public class DeliveryReceiptManager extends Manager implements PacketListener {
 
-    private static Map<XMPPConnection, DeliveryReceiptManager> instances =
+    private static Map<XMPPConnection, DeliveryReceiptManager> instances = new WeakHashMap<XMPPConnection, DeliveryReceiptManager>();
-            Collections.synchronizedMap(new WeakHashMap<XMPPConnection, DeliveryReceiptManager>());
 
     static {
         XMPPConnection.addConnectionCreationListener(new ConnectionCreationListener() {
@@ -62,7 +61,6 @@ public class DeliveryReceiptManager extends Manager implements PacketListener {
         super(connection);
         ServiceDiscoveryManager sdm = ServiceDiscoveryManager.getInstanceFor(connection);
         sdm.addFeature(DeliveryReceipt.NAMESPACE);
-        instances.put(connection, this);
 
         // register listener for delivery receipts and requests
         connection.addPacketListener(this, new PacketExtensionFilter(DeliveryReceipt.NAMESPACE));
@@ -80,6 +78,7 @@ public class DeliveryReceiptManager extends Manager implements PacketListener {
 
         if (receiptManager == null) {
             receiptManager = new DeliveryReceiptManager(connection);
+            instances.put(connection, receiptManager);
         }
 
         return receiptManager;
@@ -101,20 +100,17 @@ public class DeliveryReceiptManager extends Manager implements PacketListener {
     // handle incoming receipts and receipt requests
     @Override
     public void processPacket(Packet packet) throws NotConnectedException {
-        DeliveryReceipt dr = (DeliveryReceipt)packet.getExtension(
+        DeliveryReceipt dr = DeliveryReceipt.getFrom(packet);
-                DeliveryReceipt.ELEMENT, DeliveryReceipt.NAMESPACE);
         if (dr != null) {
             // notify listeners of incoming receipt
             for (ReceiptReceivedListener l : receiptReceivedListeners) {
                 l.onReceiptReceived(packet.getFrom(), packet.getTo(), dr.getId());
             }
-
         }
 
         // if enabled, automatically send a receipt
         if (auto_receipts_enabled) {
-            DeliveryReceiptRequest drr = (DeliveryReceiptRequest)packet.getExtension(
+            DeliveryReceiptRequest drr = DeliveryReceiptRequest.getFrom(packet);
-                    DeliveryReceiptRequest.ELEMENT, DeliveryReceipt.NAMESPACE);
             if (drr != null) {
                 XMPPConnection connection = connection();
                 Message ack = new Message(packet.getFrom(), Message.Type.normal);
@@ -182,8 +178,7 @@ public class DeliveryReceiptManager extends Manager implements PacketListener {
      * @return true if a delivery receipt was requested
      */
     public static boolean hasDeliveryReceiptRequest(Packet p) {
-        return (p.getExtension(DeliveryReceiptRequest.ELEMENT,
+        return (DeliveryReceiptRequest.getFrom(p) != null);
-                    DeliveryReceipt.NAMESPACE) != null);
     }
 
     /**
@@ -193,8 +188,10 @@ public class DeliveryReceiptManager extends Manager implements PacketListener {
      * therefore only allow Message as the parameter type.
      *
      * @param m Message object to add a request to
+     * @return the Message ID which will be used as receipt ID
      */
-    public static void addDeliveryReceiptRequest(Message m) {
+    public static String addDeliveryReceiptRequest(Message m) {
         m.addExtension(new DeliveryReceiptRequest());
+        return m.getPacketID();
     }
 }

smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceiptRequest.java

@@ -1,6 +1,6 @@
 /**
  *
- * Copyright the original author or authors
+ * Copyright 2013-2014 the original author or authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
  */
 package org.jivesoftware.smackx.receipts;
 
+import org.jivesoftware.smack.packet.Packet;
 import org.jivesoftware.smack.packet.PacketExtension;
 import org.jivesoftware.smack.provider.PacketExtensionProvider;
 import org.xmlpull.v1.XmlPullParser;
@@ -45,6 +46,16 @@ public class DeliveryReceiptRequest implements PacketExtension
         return "<request xmlns='" + DeliveryReceipt.NAMESPACE + "'/>";
     }
 
+    /**
+     * Get the {@link DeliveryReceiptRequest} extension of the packet, if any.
+     *
+     * @param p the packet
+     * @return the {@link DeliveryReceiptRequest} extension or {@code null}
+     */
+    public static DeliveryReceiptRequest getFrom(Packet p) {
+        return p.getExtension(ELEMENT, DeliveryReceipt.NAMESPACE);
+    }
+
     /**
      * This Provider parses and returns DeliveryReceiptRequest packets.
      */

smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/ReceiptReceivedListener.java

@@ -1,6 +1,6 @@
 /**
  *
- * Copyright 2013 Georg Lukas
+ * Copyright 2013-2014 Georg Lukas
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,5 +22,16 @@ package org.jivesoftware.smackx.receipts;
  * Implement this and add a listener to get notified. 
  */
 public interface ReceiptReceivedListener {
+    /**
+     * Callback invoked when a new receipt got received.
+     * <p>
+     * {@code receiptId} correspondents to the message ID, which can be obtained with
+     * {@link org.jivesoftware.smack.packet.Packet#getPacketID()}.
+     * </p>
+     * 
+     * @param fromJid the jid that send this receipt
+     * @param toJid the jid which received this receipt
+     * @param receiptId the message ID of the packet which has been received and this receipt is for
+     */
     void onReceiptReceived(String fromJid, String toJid, String receiptId);
 }