add more documentation

src/main/java/com/notnoop/mpns/DeliveryClass.java

@@ -30,6 +30,29 @@
  */
 package com.notnoop.mpns;
 
+/**
+ * Determines the batch interval indicating when the push notification
+ * should be sent to the application.
+ *
+ * The default value, for a new notification is {@code IMMEDIATELY}.
+ *
+ */
 public enum DeliveryClass {
-    IMMEDIATELY, WITHIN_450, WITHIN_900;
+
+    /**
+     * Indicates that the push notification should be delivered immediately
+     */
+    IMMEDIATELY,
+
+    /**
+     * Indicates that the push notification should be delivered within 450
+     * seconds (7.5 minutes)
+     */
+    WITHIN_450,
+
+    /**
+     * Indicates that the push notification should be delivered within 900
+     * seconds (15 minutes)
+     */
+    WITHIN_900;
 }

src/main/java/com/notnoop/mpns/MpnsNotificationBuilder.java

@@ -34,17 +34,39 @@
 import com.notnoop.mpns.notifications.TileNotification;
 import com.notnoop.mpns.notifications.ToastNotification;
 
+/**
+ * Represents a builder for constructing the notifications requests,
+ * as specified by
+ * <a href="http://msdn.microsoft.com/en-us/library/ff402558(v=vs.92).aspx">
+ * Microsoft Push Notification Guide</a>:
+ *
+ */
 public class MpnsNotificationBuilder {
     public MpnsNotificationBuilder() {}
 
+    /**
+     * Sets the notification type to a Tile notification
+     *
+     * @return  a tile notification builder
+     */
     public TileNotification.Builder tile() {
         return new TileNotification.Builder();
     }
 
+    /**
+     * Sets the notification type to a Toast notification
+     *
+     * @return a toast notification builder
+     */
     public ToastNotification.Builder toast() {
         return new ToastNotification.Builder();
     }
 
+    /**
+     * Sets the notification type to a Raw notification
+     *
+     * @return  a row notification builder
+     */
     public RawNotification.Builder raw() {
         return new RawNotification.Builder();
     }

src/main/java/com/notnoop/mpns/MpnsService.java

@@ -36,14 +36,12 @@
 import com.notnoop.mpns.exceptions.NetworkIOException;
 
 /**
- * Represents the connection and interface to the Apple APNS servers.
+ * Represents the connection and interface to the Microsoft MPNS servers.
  *
- * The service is created by {@link ApnsServiceBuilder} like:
+ * The service is created by {@link MpnsServiceBuilder} like:
  *
  * <pre>
- *   ApnsService = APNS.newService()
- *                  .withCert("/path/to/certificate.p12", "MyCertPassword")
- *                  .withSandboxDestination()
+ *   MpnsService service = MPNS.newService()
  *                  .build()
  * </pre>
  */

src/main/java/com/notnoop/mpns/MpnsServiceBuilder.java

@@ -42,20 +42,18 @@
 import com.notnoop.mpns.internal.*;
 
 /**
- * The class is used to create instances of {@link ApnsService}.
+ * The class is used to create instances of {@link MpnsService}.
  *
  * Note that this class is not synchronized.  If multiple threads access a
- * {@code ApnsServiceBuilder} instance concurrently, and at least on of the
+ * {@code MpnsServiceBuilder} instance concurrently, and at least on of the
  * threads modifies one of the attributes structurally, it must be
  * synchronized externally.
  *
- * Starting a new {@code ApnsService} is easy:
+ * Starting a new {@code MpnsService} is easy:
  *
  * <pre>
- *   ApnsService = APNS.newService()
- *    .withCert("/path/to/certificate.p12", "MyCertPassword")
- *    .withSandboxDestination()
- *    .build()
+ *   MpnsService service = MPNS.newService()
+ *                  .build()
  * </pre>
  */
 public class MpnsServiceBuilder {
@@ -66,7 +64,7 @@ public class MpnsServiceBuilder {
     private Proxy proxy = null;
 
     /**
-     * Constructs a new instance of {@code ApnsServiceBuilder}
+     * Constructs a new instance of {@code MpnsServiceBuilder}
      */
     public MpnsServiceBuilder() { }
 
@@ -93,7 +91,7 @@ public MpnsServiceBuilder withSocksProxy(String host, int port) {
 
     /**
      * Specify the proxy to be used to establish the connections
-     * to Apple Servers
+     * to Microsoft Servers
      *
      * <p>Read the <a href="http://java.sun.com/javase/6/docs/technotes/guides/net/proxies.html">
      * Java Networking and Proxies</a> guide to understand the
@@ -110,11 +108,6 @@ public MpnsServiceBuilder withProxy(Proxy proxy) {
     /**
      * Constructs a pool of connections to the notification servers.
      *
-     * Apple servers recommend using a pooled connection up to
-     * 15 concurrent persistent connections to the gateways.
-     *
-     * Note: This option has no effect when using non-blocking
-     * connections.
      */
     public MpnsServiceBuilder asPool(int maxConnections) {
         return asPool(Executors.newFixedThreadPool(maxConnections), maxConnections);
@@ -123,12 +116,6 @@ public MpnsServiceBuilder asPool(int maxConnections) {
     /**
      * Constructs a pool of connections to the notification servers.
      *
-     * Apple servers recommend using a pooled connection up to
-     * 15 concurrent persistent connections to the gateways.
-     *
-     * Note: This option has no effect when using non-blocking
-     * connections.
-     *
      * Note: The maxConnections here is used as a hint to how many connections
      * get created.
      */
@@ -150,10 +137,10 @@ public MpnsServiceBuilder asQueued() {
     }
 
     /**
-     * Returns a fully initialized instance of {@link ApnsService},
+     * Returns a fully initialized instance of {@link MpnsService},
      * according to the requested settings.
      *
-     * @return  a new instance of ApnsService
+     * @return  a new instance of MpnsService
      */
     public MpnsService build() {
         checkInitialization();

src/main/java/com/notnoop/mpns/notifications/AbstractNotificationBuilder.java

@@ -35,33 +35,86 @@
 import java.util.Map.Entry;
 
 import com.notnoop.mpns.DeliveryClass;
+import com.notnoop.mpns.MpnsNotification;
 import com.notnoop.mpns.internal.Pair;
 
+/**
+ * An abstract notification builder for the common header settings
+ *
+ * @param <A>   the concrete type of the builder
+ * @param <B>   the type of the generated message
+ */
 @SuppressWarnings("unchecked")
-abstract class AbstractNotificationBuilder<A extends AbstractNotificationBuilder<A, B>, B> {
+/*package-protected*/ abstract class AbstractNotificationBuilder<A extends AbstractNotificationBuilder<A, B>, B extends MpnsNotification> {
     protected List<Entry<String, String>> headers = new ArrayList<Entry<String, String>>();
 
+    protected AbstractNotificationBuilder(String type) {
+        notificationType(type);
+    }
+
+    /**
+     * Sets the message UUID.
+     *
+     * The message UUID is optional application-specific identifier for
+     * book-keeping and associate it with the response.
+     *
+     * @param messageId notification message ID
+     * @return  this
+     */
     public A messageId(String messageId) {
         this.headers.add(Pair.of("X-MessageId", messageId));
         return (A)this;
     }
 
+    /**
+     * Sets the notification batching interval, indicating when the notification
+     * should be delivered to the device
+     *
+     * @param delivery  batching interval
+     * @return  this
+     */
     public A notificationClass(DeliveryClass delivery) {
         this.headers.add(Pair.of("X-NotificationClass", String.valueOf(deliveryValueOf(delivery))));
         return (A)this;
     }
 
+
+    /**
+     * Sets the type of the push notification being sent.
+     *
+     * As of Windows Phone OS 7.0, the supported types are:
+     * <ul>
+     *  <li>token (for Tile messages)</li>
+     *  <li>toast</li>
+     *  <li>raw</li>
+     * </ul>
+     *
+     * This method should probably not be called directly, as the concrete
+     * builder class will set the appropriate notification type.
+     *
+     * @param type  the notification type
+     * @return  this
+     */
     public A notificationType(String type) {
         this.headers.add(Pair.of("X-WindowsPhone-Target", type));
         return (A)this;
     }
 
+    /**
+     * Sets the notification channel URI that the registered callback message
+     * will be sent to.
+     *
+     * When using an authenticated web service, this parameter is required.
+     *
+     * @param callbackUri   the notification channel URI
+     * @return  this
+     */
     public A callbackUri(String callbackUri) {
         this.headers.add(Pair.of("X-CallbackURI", callbackUri));
         return (A)this;
     }
 
     protected abstract int deliveryValueOf(DeliveryClass delivery);
 
-    protected abstract B build();
+    public abstract B build();
 }

src/main/java/com/notnoop/mpns/notifications/RawNotification.java

@@ -61,8 +61,7 @@ public static class Builder extends AbstractNotificationBuilder<Builder, RawNoti
         private String xml;
 
         public Builder() {
-            super();
-            this.notificationType("raw");
+            super("raw");
         }
 
         public Builder xml(String xml) {
@@ -82,7 +81,7 @@ protected int deliveryValueOf(DeliveryClass delivery) {
         }
 
         @Override
-        protected RawNotification build() {
+        public RawNotification build() {
             return new RawNotification(xml, headers);
         }
     }

src/main/java/com/notnoop/mpns/notifications/TileNotification.java

@@ -91,8 +91,7 @@ public static class Builder extends AbstractNotificationBuilder<Builder, TileNot
         private int count;
 
         public Builder() {
-            super();
-            this.notificationType("token"); // TODO: Check whether it is "tile"
+            super("token"); // TODO: Check whether it is "tile"
         }
 
         public Builder backgroundImage(String backgroundImage) {
@@ -137,7 +136,7 @@ protected int deliveryValueOf(DeliveryClass delivery) {
         }
 
         @Override
-        protected TileNotification build() {
+        public TileNotification build() {
             return new TileNotification(backgroundImage, title, count,
                     backBackgroundImage, backTitle, backContent,headers);
         }

src/main/java/com/notnoop/mpns/notifications/ToastNotification.java

@@ -78,8 +78,7 @@ public static class Builder extends AbstractNotificationBuilder<Builder, ToastNo
         private String title, subtitle, parameter;
 
         public Builder() {
-            super();
-            this.notificationType("toast");
+            super("toast");
         }
 
         public Builder title(String title) {
@@ -109,7 +108,7 @@ protected int deliveryValueOf(DeliveryClass delivery) {
         }
 
         @Override
-        protected ToastNotification build() {
+        public ToastNotification build() {
             return new ToastNotification(title, subtitle, parameter, headers);
         }
     }