From ed67ed8e113a5097f76b35ac551bf03dec6b58bf Mon Sep 17 00:00:00 2001
From: Florian Schmaus
Date: Sun, 18 Jan 2015 20:42:27 +0100
Subject: [PATCH] SASL, username and password related javadoc improvements
---
.../org/jivesoftware/smack/AbstractXMPPConnection.java | 4 ++--
.../org/jivesoftware/smack/ConnectionConfiguration.java | 7 ++++---
.../java/org/jivesoftware/smack/sasl/SASLMechanism.java | 7 +++++--
.../jivesoftware/smack/sasl/core/SASLXOauth2Mechanism.java | 6 +++---
4 files changed, 14 insertions(+), 10 deletions(-)
diff --git a/smack-core/src/main/java/org/jivesoftware/smack/AbstractXMPPConnection.java b/smack-core/src/main/java/org/jivesoftware/smack/AbstractXMPPConnection.java
index 321afa016..ffc18fc80 100644
--- a/smack-core/src/main/java/org/jivesoftware/smack/AbstractXMPPConnection.java
+++ b/smack-core/src/main/java/org/jivesoftware/smack/AbstractXMPPConnection.java
@@ -424,8 +424,8 @@ public abstract class AbstractXMPPConnection implements XMPPConnection {
}
/**
- * Login with the given username. You may omit the password if a callback handler is used. If
- * resource is null, then the server will generate one.
+ * Login with the given username (authorization identity). You may omit the password if a callback handler is used.
+ * If resource is null, then the server will generate one.
*
* @param username
* @param password
diff --git a/smack-core/src/main/java/org/jivesoftware/smack/ConnectionConfiguration.java b/smack-core/src/main/java/org/jivesoftware/smack/ConnectionConfiguration.java
index deca8b440..fe269bc40 100644
--- a/smack-core/src/main/java/org/jivesoftware/smack/ConnectionConfiguration.java
+++ b/smack-core/src/main/java/org/jivesoftware/smack/ConnectionConfiguration.java
@@ -419,11 +419,12 @@ public abstract class ConnectionConfiguration {
/**
* Set the XMPP entities username and password.
*
- * The username is the localpart of the entities JID, e.g. localpart@example.org
.
+ * The username is usually the localpart of the clients JID. But some SASL mechanisms or services may require a different
+ * format (e.g. the full JID) as used authorization identity.
*
*
- * @param username
- * @param password
+ * @param username the username or authorization identity
+ * @param password the password or token used to authenticate
* @return a reference to this builder.
*/
public B setUsernameAndPassword(String username, String password) {
diff --git a/smack-core/src/main/java/org/jivesoftware/smack/sasl/SASLMechanism.java b/smack-core/src/main/java/org/jivesoftware/smack/sasl/SASLMechanism.java
index 735c817f5..eba0d7045 100644
--- a/smack-core/src/main/java/org/jivesoftware/smack/sasl/SASLMechanism.java
+++ b/smack-core/src/main/java/org/jivesoftware/smack/sasl/SASLMechanism.java
@@ -91,9 +91,12 @@ public abstract class SASLMechanism implements Comparable {
protected XMPPConnection connection;
/**
- * authcid, i.e. the username (localpart) of the XMPP connection trying to authenticated.
+ * Then authentication identity (authcid). RFC 6120 § 6.3.7 informs us that some SASL mechanisms use this as a
+ * "simple user name". But the exact form is a matter of the mechanism and that it does not necessarily map to an
+ * localpart. But it usually is the localpart of the client JID, although sometimes other formats are used (e.g. the
+ * full JID).
*
- * Not to be confused with the authzid.
+ * Not to be confused with the authzid (see RFC 6120 § 6.3.8).
*
*/
protected String authenticationId;
diff --git a/smack-core/src/main/java/org/jivesoftware/smack/sasl/core/SASLXOauth2Mechanism.java b/smack-core/src/main/java/org/jivesoftware/smack/sasl/core/SASLXOauth2Mechanism.java
index d8e04800a..1387fad90 100644
--- a/smack-core/src/main/java/org/jivesoftware/smack/sasl/core/SASLXOauth2Mechanism.java
+++ b/smack-core/src/main/java/org/jivesoftware/smack/sasl/core/SASLXOauth2Mechanism.java
@@ -1,6 +1,6 @@
/**
*
- * Copyright 2014 Florian Schmaus
+ * Copyright 2014-2015 Florian Schmaus
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -30,8 +30,8 @@ import org.jivesoftware.smack.util.stringencoder.Base64;
* The given password will be used as OAUTH token.
*
*
- * Note that X-OAUTH2 is experimental in Smack. This is because Google defined, besides being a bad practice, custom
- * attributes to the 'auth' stanze, as can be seen here
+ * Note that X-OAUTH2 is experimental in Smack. This is because Google defined, besides being a bad practice (XEP-134),
+ * custom attributes to the 'auth' stanza, as can be seen here
*
*
*