Author: ivol37 at gmail.com
Date: Thu Dec 2 11:34:00 2010
New Revision: 470
Log:
[AMDATU-181] javadoc improvements
Added:
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/OAuthServerConfig.java
Modified:
trunk/amdatu-authentication/oauth-api/src/main/java/org/amdatu/authentication/oauth/api/OAuthServiceConsumer.java
trunk/amdatu-authentication/oauth-api/src/main/java/org/amdatu/authentication/oauth/api/OAuthServiceProvider.java
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/ConsumerAlreadyExistsException.java
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/ConsumerNotFoundException.java
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/service/OAuthServiceProviderImpl.java
Modified:
trunk/amdatu-authentication/oauth-api/src/main/java/org/amdatu/authentication/oauth/api/OAuthServiceConsumer.java
==============================================================================
---
trunk/amdatu-authentication/oauth-api/src/main/java/org/amdatu/authentication/oauth/api/OAuthServiceConsumer.java
(original)
+++
trunk/amdatu-authentication/oauth-api/src/main/java/org/amdatu/authentication/oauth/api/OAuthServiceConsumer.java
Thu Dec 2 11:34:00 2010
@@ -25,33 +25,44 @@
* consumer key and secret.
* The callback URL is the URL to which the client is redirected to authorize
a request token received earlier
* in the process and to exchange it for an access token.
+ *
* @author ivol
- *
*/
public interface OAuthServiceConsumer {
- /**
- * Returns a descriptive name of this consumer. The name is used on the
authorization page on which
- * the user must allow this consumer to access its protected resource.
- * @return name of this consumer.
- */
- String getName();
+ /**
+ * Returns a descriptive name of this consumer. The name is used on the
authorization page on which
+ * the user must allow this consumer to access its protected resource. The
name is by no means used
+ * as identifier.
+ *
+ * @return a descriptive name of this service consumer.
+ */
+ String getName();
/**
* Returns the consumer key. The consumer key is used by a consumer to
identify itself to the
- * service provider.
- * @return
+ * service provider. The consumer key is unique in the oAuth server that
supports this consumer.
+ *
+ * @return A public key that identifies this consumer.
*/
String getConsumerKey();
/**
- * Returns the consumer secret. The consumer secret is used by the
Consumer to establish
- * ownership of the Consumer Key.
- * @return
+ * Returns the consumer secret. The consumer secret is used by the
consumer to establish
+ * ownership of the consumer key. While the consumer key is public and
known to everyone, the
+ * secret is only known by the service consumer and the service provider.
The consumer and provider
+ * exchange this secret when communicating with each other to ensure the
identity of the service
+ * consumer.
+ *
+ * @return The consumer secret, a private key only known by the service
consumer and service provider.
*/
String getConsumerSecret();
/**
* Returns the URL to which users should be redirected after a request
token has been authorized by this user.
+ * The callback allows the service consumer to exchange its previous
acquired request token for an
+ * access token by the service provider. Exchanging this token can only
succeed after the user having
+ * authorized the request token (in three-legged oAuth that is).
+ *
* @return The URL to which a user will be redirected after a request
token has been authorized.
*/
String getCallbackUrl();
Modified:
trunk/amdatu-authentication/oauth-api/src/main/java/org/amdatu/authentication/oauth/api/OAuthServiceProvider.java
==============================================================================
---
trunk/amdatu-authentication/oauth-api/src/main/java/org/amdatu/authentication/oauth/api/OAuthServiceProvider.java
(original)
+++
trunk/amdatu-authentication/oauth-api/src/main/java/org/amdatu/authentication/oauth/api/OAuthServiceProvider.java
Thu Dec 2 11:34:00 2010
@@ -18,25 +18,32 @@
/**
* This class represents an oAuth service provider. An oAuth service provider
provides the three endpoints of
- * an oAuth server; request token, authorize token and access token.
+ * an oAuth server; request token, authorize token and access token needed to
complete the oAuth dance.
+ *
* @author ivol
*/
public interface OAuthServiceProvider {
- /**
- * Returns the URL of the oAuth server endpoint that generates the
request tokens.
- * @return The URL of the request token endpoint.
- */
+ /**
+ * Returns the absolute URL of the oAuth server endpoint that generates
the request tokens.
+ * For more information about oAuth request tokens, see
http://oauth.net/core/1.0/
+ *
+ * @return The absolute URL of the request token endpoint.
+ */
String getRequestTokenURL();
-
- /**
- * Returns the URL of the oAuth server endpoint that authorizes request
tokens.
- * @return The URL of the authorize token endpoint.
- */
+
+ /**
+ * Returns the absolute URL of the oAuth server endpoint that authorizes
request tokens.
+ * For more information about authorizing oAuth request tokens, see
http://oauth.net/core/1.0/
+ *
+ * @return The absolute URL of the authorize token endpoint.
+ */
String getAuthorizeTokenURL();
-
- /**
- * Returns the URL of the oAuth server endpoint that exchanges request
tokens for access tokens.
- * @return The URL of the access token endpoint.
- */
+
+ /**
+ * Returns the absolute URL of the oAuth server endpoint that exchanges
request tokens for access tokens.
+ * For more information about oAuth access tokens, see
http://oauth.net/core/1.0/
+ *
+ * @return The absolute URL of the access token endpoint.
+ */
String getAccessTokenURL();
}
Modified:
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/ConsumerAlreadyExistsException.java
==============================================================================
---
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/ConsumerAlreadyExistsException.java
(original)
+++
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/ConsumerAlreadyExistsException.java
Thu Dec 2 11:34:00 2010
@@ -16,9 +16,21 @@
*/
package org.amdatu.authentication.oauth.server;
+/**
+ * Exception class thrown by consumer management services to indicate that a
customer already exists
+ * while this was not expected.
+ *
+ * @author ivol
+ */
public class ConsumerAlreadyExistsException extends Exception {
+ // The serial version UID of this exception class
private static final long serialVersionUID = -3147082163353782694L;
-
+
+ /**
+ * Constructs a new consumer already exists exception.
+ *
+ * @param msg An error message providing more information about the cause
of the error.
+ */
public ConsumerAlreadyExistsException(String msg) {
super(msg);
}
Modified:
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/ConsumerNotFoundException.java
==============================================================================
---
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/ConsumerNotFoundException.java
(original)
+++
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/ConsumerNotFoundException.java
Thu Dec 2 11:34:00 2010
@@ -16,8 +16,21 @@
*/
package org.amdatu.authentication.oauth.server;
+/**
+ * Exception class thrown by consumer management services to indicate that a
customer was not found
+ * while this was expected.
+ *
+ * @author ivol
+ */
public class ConsumerNotFoundException extends Exception {
+ // The serial version UID of this exception class
private static final long serialVersionUID = -6602963888588386204L;
+
+ /**
+ * Constructs a new consumer not found exception.
+ *
+ * @param msg An error message providing more information about the cause
of the error.
+ */
public ConsumerNotFoundException(String msg) {
super(msg);
}
Added:
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/OAuthServerConfig.java
==============================================================================
--- (empty file)
+++
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/OAuthServerConfig.java
Thu Dec 2 11:34:00 2010
@@ -0,0 +1,38 @@
+/*
+ Copyright (C) 2010 Amdatu.org
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.amdatu.authentication.oauth.server;
+
+public class OAuthServerConfig {
+ /**
+ * The PID of the configuration of this service.
+ */
+ public final static String PID = "org.amdatu.authentication.oauth.server";
+
+ /**
+ * The hostname property name of the configuration properties.
+ */
+ public final static String HOSTNAME = "hostname";
+
+ /**
+ * The portnr property name of the configuration properties.
+ */
+ public final static String PORTNR = "portnr";
+
+ // Mark the constructor private since this class intends to provide only
static fields.
+ private OAuthServerConfig() {
+ }
+}
Modified:
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/service/OAuthServiceProviderImpl.java
==============================================================================
---
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/service/OAuthServiceProviderImpl.java
(original)
+++
trunk/amdatu-authentication/oauth-server/src/main/java/org/amdatu/authentication/oauth/server/service/OAuthServiceProviderImpl.java
Thu Dec 2 11:34:00 2010
@@ -25,11 +25,6 @@
import org.osgi.service.cm.ManagedService;
public class OAuthServiceProviderImpl implements OAuthServiceProvider,
ManagedService {
- // The PID and configuration properties
- public final static String PID = "org.amdatu.authentication.oauth.server";
- private final static String HOSTNAME = "hostname";
- private final static String PORTNR = "portnr";
-
private String m_hostName, m_portNr;
public String getRequestTokenURL() {
