Skip to content
Browse files

add more documentation

  • Loading branch information...
1 parent 4efea97 commit 6ca8624e9fc23e38226023a038b909fb7500a415 @notnoop committed
View
25 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;
}
View
22 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();
}
View
8 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>
*/
View
31 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 @@
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();
View
57 src/main/java/com/notnoop/mpns/notifications/AbstractNotificationBuilder.java
@@ -35,27 +35,80 @@
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;
@@ -63,5 +116,5 @@ public A callbackUri(String callbackUri) {
protected abstract int deliveryValueOf(DeliveryClass delivery);
- protected abstract B build();
+ public abstract B build();
}
View
5 src/main/java/com/notnoop/mpns/notifications/RawNotification.java
@@ -61,8 +61,7 @@ public String getRequestBody() {
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);
}
}
View
5 src/main/java/com/notnoop/mpns/notifications/TileNotification.java
@@ -91,8 +91,7 @@ public String getRequestBody() {
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);
}
View
5 src/main/java/com/notnoop/mpns/notifications/ToastNotification.java
@@ -78,8 +78,7 @@ public String getRequestBody() {
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);
}
}

0 comments on commit 6ca8624

Please sign in to comment.
Something went wrong with that request. Please try again.