Author: berndf
Date: Mon Mar 29 15:12:49 2010
New Revision: 928803
URL: http://svn.apache.org/viewvc?rev=928803&view=rev
Log:
VYSPER-191, javadoc for the whole roster package
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/AskSubscriptionType.java
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/MutableRoster.java
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/Roster.java
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterGroup.java
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterItem.java
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterStanzaUtils.java
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterSubscriptionMutator.java
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterUtils.java
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/AskSubscriptionType.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/AskSubscriptionType.java?rev=928803&r1=928802&r2=928803&view=diff
==============================================================================
---
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/AskSubscriptionType.java
(original)
+++
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/AskSubscriptionType.java
Mon Mar 29 15:12:49 2010
@@ -20,13 +20,22 @@
package org.apache.vysper.xmpp.modules.roster;
/**
- *
+ * type of pending subscriptions
* @author The Apache MINA Project ([email protected])
*/
public enum AskSubscriptionType {
+ /**
+ * no pending subscriptions
+ */
NOT_SET(null),
+ /**
+ * new subscription request to be confirmed by the contact
+ */
ASK_SUBSCRIBE("subscribe"),
+ /**
+ * confirmed subscription request
+ */
ASK_SUBSCRIBED("subscribed");
private final String value;
@@ -39,4 +48,4 @@ public enum AskSubscriptionType {
return value;
}
-}
\ No newline at end of file
+}
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/MutableRoster.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/MutableRoster.java?rev=928803&r1=928802&r2=928803&view=diff
==============================================================================
---
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/MutableRoster.java
(original)
+++
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/MutableRoster.java
Mon Mar 29 15:12:49 2010
@@ -26,6 +26,7 @@ import java.util.LinkedHashMap;
import java.util.Map;
/**
+ * a mutable roster implementation
*
* @author The Apache MINA Project ([email protected])
*/
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/Roster.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/Roster.java?rev=928803&r1=928802&r2=928803&view=diff
==============================================================================
---
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/Roster.java
(original)
+++
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/Roster.java
Mon Mar 29 15:12:49 2010
@@ -24,7 +24,8 @@ import org.apache.vysper.xmpp.addressing
import java.util.Iterator;
/**
- * a whole roster for a user
+ * the whole roster for a user. contains all the user's contacts, with both
pending and established subscriptions.
+ * the roster is persisted on the server and requested by the client with
every login.
*
* @author The Apache MINA Project ([email protected])
*/
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterGroup.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterGroup.java?rev=928803&r1=928802&r2=928803&view=diff
==============================================================================
---
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterGroup.java
(original)
+++
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterGroup.java
Mon Mar 29 15:12:49 2010
@@ -20,6 +20,8 @@
package org.apache.vysper.xmpp.modules.roster;
/**
+ * groups contacts under a user-chosen descriptive name, for example, group
"family" could
+ * contain contacts "mum" and "dad".
*
* @author The Apache MINA Project ([email protected])
*/
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterItem.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterItem.java?rev=928803&r1=928802&r2=928803&view=diff
==============================================================================
---
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterItem.java
(original)
+++
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterItem.java
Mon Mar 29 15:12:49 2010
@@ -28,16 +28,37 @@ import java.util.ArrayList;
import java.util.Collections;
/**
- * one contact in the roster
+ * one contact in the roster of a user, the subscription can either be
pending, or established, depending on the values
+ * of the subscriptionType and askSubscriptionType fields.
*
* @author The Apache MINA Project ([email protected])
*/
public class RosterItem {
+ /**
+ * the contact's JID, eg. "[email protected]"
+ */
private Entity jid;
+
+ /**
+ * a user-chosen, descriptive, often short name ('nick'), eg. "Frank
Zappa", or "Frank"
+ */
private String name;
+
+ /**
+ * all the groups the item is displayed under. this list can be empty.
+ */
private final List<RosterGroup> groups = new ArrayList<RosterGroup>();
+
+ /**
+ * type of subscription either FROM, TO or both. depending on the value of
askSubscriptionType, FROM or TO
+ * subscriptions might be still pending and awaiting approval
+ */
private SubscriptionType subscriptionType;
+
+ /**
+ * records pending subscriptions, awaiting approval
+ */
private AskSubscriptionType askSubscriptionType;
public RosterItem(Entity jid, SubscriptionType subscriptionType) {
@@ -68,17 +89,29 @@ public class RosterItem {
return name;
}
+ /**
+ * sets the user-chosen name for the contact
+ * @param name
+ */
public void setName(String name) {
this.name = name;
}
+ /**
+ * unmodifyable list of groups containing this contact
+ * @return list, containing 0..n groups
+ */
public List<RosterGroup> getGroups() {
return Collections.unmodifiableList(groups);
}
+ /**
+ * the list of groups the contact will be contained in. all previous
groups are replaced by the given list.
+ * @param newGroups 0..n groups
+ */
public void setGroups(List<RosterGroup> newGroups) {
this.groups.clear();
- this.groups.addAll(newGroups);
+ if (newGroups != null) this.groups.addAll(newGroups);
}
public SubscriptionType getSubscriptionType() {
@@ -103,14 +136,23 @@ public class RosterItem {
this.askSubscriptionType = askSubscribe;
}
+ /**
+ * @return TRUE, iff the contact sends presence to the user
+ */
public boolean hasTo() {
return subscriptionType == TO || subscriptionType == BOTH;
}
+ /**
+ * @return TRUE, iff the contact receives presence from the contact
+ */
public boolean hasFrom() {
return subscriptionType == FROM || subscriptionType == BOTH;
}
+ /**
+ * @return TRUE, iff the user and the contact mutually receive each
other's presence
+ */
public boolean isBoth() {
return subscriptionType == BOTH;
}
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterStanzaUtils.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterStanzaUtils.java?rev=928803&r1=928802&r2=928803&view=diff
==============================================================================
---
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterStanzaUtils.java
(original)
+++
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterStanzaUtils.java
Mon Mar 29 15:12:49 2010
@@ -29,11 +29,16 @@ import java.util.List;
import java.util.ArrayList;
/**
+ * factory methods for roster related stanzas
*
* @author The Apache MINA Project ([email protected])
*/
public class RosterStanzaUtils {
+ /**
+ * creates IQ stanza containing the given roster items.
+ * the server returns this stanza when the client requests or changes the
roster
+ */
public static StanzaBuilder createRosterItemsIQ(Entity to, String id,
IQStanzaType type, Iterable<RosterItem> rosterItems) {
StanzaBuilder stanzaBuilder = StanzaBuilder.createIQStanza(null, to,
type, id).
startInnerElement("query", NamespaceURIs.JABBER_IQ_ROSTER);
@@ -47,16 +52,27 @@ public class RosterStanzaUtils {
return stanzaBuilder;
}
+ /**
+ * create IQ stanza for pushing a roster item update to the client
+ */
public static Stanza createRosterItemPushIQ(Entity to, String id,
RosterItem rosterItem) {
return createRosterItemIQ(to, id, IQStanzaType.SET, rosterItem);
}
+ /**
+ * general purpose factory method to create a roster IQ stanza for sending
roster item information to the client
+ */
public static Stanza createRosterItemIQ(Entity to, String id, IQStanzaType
iqStanzaType, RosterItem rosterItem) {
List<RosterItem> itemList = new ArrayList<RosterItem>();
itemList.add(rosterItem);
return createRosterItemsIQ(to, id, iqStanzaType, itemList).build();
}
+ /**
+ * adds the given roster item to the roster stanza in creation
+ * @param stanzaBuilder represents the stanza in creation
+ * @param rosterItem the added roster item
+ */
public static void createRosterItem(StanzaBuilder stanzaBuilder,
RosterItem rosterItem) {
stanzaBuilder.startInnerElement("item",
NamespaceURIs.JABBER_IQ_ROSTER).
addAttribute("jid",
rosterItem.getJid().getFullQualifiedName());
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterSubscriptionMutator.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterSubscriptionMutator.java?rev=928803&r1=928802&r2=928803&view=diff
==============================================================================
---
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterSubscriptionMutator.java
(original)
+++
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterSubscriptionMutator.java
Mon Mar 29 15:12:49 2010
@@ -37,9 +37,13 @@ public class RosterSubscriptionMutator {
}
public enum Result {
+ /** the type was added to the subscription state**/
OK,
+ /** an illegal type was supplied **/
ILLEGAL_ARGUMENT,
+ /** the type was already present **/
ALREADY_SET,
+ /** the type was not added **/
FAILED
}
Modified:
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterUtils.java
URL:
http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterUtils.java?rev=928803&r1=928802&r2=928803&view=diff
==============================================================================
---
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterUtils.java
(original)
+++
mina/sandbox/vysper/trunk/server/core/src/main/java/org/apache/vysper/xmpp/modules/roster/RosterUtils.java
Mon Mar 29 15:12:49 2010
@@ -40,10 +40,15 @@ import java.util.List;
import java.util.Map;
/**
- *
+ * some roster logic
* @author The Apache MINA Project ([email protected])
*/
public class RosterUtils {
+
+ /**
+ * takes the roster of a user and groups items by subscription state. this
is helpful when all FROM items
+ * are needed and then all TO items - but the roster is only iterated
once.
+ */
public static Map<SubscriptionType, List<RosterItem>>
getRosterItemsByState(RosterManager rosterManager, Entity user) {
Map<SubscriptionType, List<RosterItem>> rosterItemMap = new
HashMap<SubscriptionType, List<RosterItem>>();
@@ -69,14 +74,23 @@ public class RosterUtils {
return rosterItemMap;
}
+ /**
+ * extracts a roster item from the given stanza
+ */
public static RosterItem parseRosterItem(IQStanza stanza) throws
RosterBadRequestException, RosterNotAcceptableException {
return parseRosterItem(stanza, false); // do not read subscription
types (except 'remove')
}
+ /**
+ * extracts a roster item from the given stanza, with relaxed semantical
checks for testing
+ */
public static RosterItem parseRosterItemForTesting(IQStanza stanza) throws
RosterBadRequestException, RosterNotAcceptableException {
return parseRosterItem(stanza, true); // do also parse subscription
types
}
+ /**
+ * extracts a roster item from the stanza and checks for integrity
according to the XMPP spec
+ */
@SpecCompliance(compliant = {
@SpecCompliant(spec="rfc3921bis-08", section = "2.1.1", status =
FINISHED, coverage = COMPLETE),
@SpecCompliant(spec="rfc3921bis-08", section = "2.1.3", status =
FINISHED,
