Author: [email protected]
Date: Fri Aug 5 10:43:47 2011
New Revision: 1256
Log:
[AMDATUAUTH-68] Added proper javadoc for the REST interface
Modified:
trunk/amdatu-auth/oauth-consumerregistry/src/main/java/org/amdatu/auth/oauth/consumerregistry/OAuthServiceConsumerRegistryREST.java
Modified:
trunk/amdatu-auth/oauth-consumerregistry/src/main/java/org/amdatu/auth/oauth/consumerregistry/OAuthServiceConsumerRegistryREST.java
==============================================================================
---
trunk/amdatu-auth/oauth-consumerregistry/src/main/java/org/amdatu/auth/oauth/consumerregistry/OAuthServiceConsumerRegistryREST.java
(original)
+++
trunk/amdatu-auth/oauth-consumerregistry/src/main/java/org/amdatu/auth/oauth/consumerregistry/OAuthServiceConsumerRegistryREST.java
Fri Aug 5 10:43:47 2011
@@ -13,12 +13,201 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-package org.amdatu.auth.oauth.consumerregistry;
-
-/**
- * Interface for the oAuth service consumer registry REST service.
- *
- * @author ivol
- */
-public interface OAuthServiceConsumerRegistryREST {
-}
+package org.amdatu.auth.oauth.consumerregistry;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.FormParam;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.UriInfo;
+
+import org.amdatu.auth.oauth.consumerregistry.bean.ConsumerBean;
+
+/**
+ * This interface represents the OAuth service consumer registry REST service.
+ *
+ * @author ivol
+ */
+public interface OAuthServiceConsumerRegistryREST {
+ /**
+ * Checks the availability of the OAuth Service Consumer registry REST
service. This is a REST service method, it is
+ * not intended to be invoked from Java. The details of this REST service
method are described below.
+ * <br/><br/>
+ * <table border="1" padding="2px">
+ * <tr><td><b>URI</b></td><td>/rest/oauth/consumers/status</td></tr>
+ * <tr><td><b>Method</b></td><td>GET</td></tr>
+ * <tr><td><b>Supported media types</b></td><td>text/plain</td></tr>
+ * <tr><td><b>Description</b></td><td>Checks the availability of the OAuth
Service Consumer registry REST service.</td></tr>
+ * <tr><td><b>Path parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Querystring parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Body parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Authentication</b></td><td>None</td></tr>
+ * <tr><td><b>Response</b></td><td>200 (OK): returns a status text<br/>
+ * 404 (Not found): The REST service is not available</td></tr>
+ * </table>
+ *
+ * @return String representing the status of this REST service
+ */
+ String status();
+
+ /**
+ * Returns the consumers in the OAuth Service Consumer registry owned by
the authenticated user. This is a REST
+ * service method, it is not intended to be invoked from Java. The details
of this REST service method are described below.
+ * <br/><br/>
+ * <table border="1" padding="2px">
+ * <tr><td><b>URI</b></td><td>/rest/oauth/consumers</td></tr>
+ * <tr><td><b>Method</b></td><td>GET</td></tr>
+ * <tr><td><b>Supported media types</b></td><td>json, xml</td></tr>
+ * <tr><td><b>Description</b></td><td>Returns the consumers in the OAuth
Service Consumer registry owned by the authenticated user.</td></tr>
+ * <tr><td><b>Path parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Querystring parameters</b></td><td>alt (String, optional):
"xml" or "json" (default is "xml")</td></tr>
+ * <tr><td><b>Body parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Authentication</b></td><td>Amdatu site
authentication</td></tr>
+ * <tr><td><b>Response</b></td><td>200 (OK): returns the list of consumers
owned by the authenticated user<br/>
+ * 401 (Unauthorized): The client could not authenticate the user or the
user is not
+ * authorized to invoke this service<br/>
+ * 404 (Not found): The REST service is not available<br/>
+ * 415 (Unsupported Media Type): The requested media type is not supported
by this REST service<br/>
+ * 500 (Internal server error): An unexpected error occurred</td></tr>
+ * </table>
+ *
+ * @return The HTTP response
+ */
+ Response getConsumers(@Context final HttpServletRequest request, @Context
final UriInfo uriInfo);
+
+ /**
+ * Returns a single consumer from the OAuth Service Consumer registry.
This is a REST service method, it is not intended
+ * to be invoked from Java. The details of this REST service method are
described below.
+ * <br/><br/>
+ * <table border="1" padding="2px">
+ * <tr><td><b>URI</b></td><td>/rest/oauth/consumers/{consumerKey}</td></tr>
+ * <tr><td><b>Method</b></td><td>GET</td></tr>
+ * <tr><td><b>Supported media types</b></td><td>json, xml</td></tr>
+ * <tr><td><b>Description</b></td><td>Returns a single consumer from the
OAuth Service Consumer registry.</td></tr>
+ * <tr><td><b>Path parameters</b></td><td>consumerKey: the id of the OAuth
service consumer to retrieve</td></tr>
+ * <tr><td><b>Querystring parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Body parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Authentication</b></td><td>Amdatu site
authentication</td></tr>
+ * <tr><td><b>Response</b></td><td>200 (OK): returns the details of the
requested consumer<br/>
+ * 401 (Unauthorized): The client could not authenticate the user or the
user is not
+ * authorized to invoke this service<br/>
+ * 404 (Not found): The REST service is not available or no consumer
exists with the specified id<br/>
+ * 415 (Unsupported Media Type): The requested media type is not supported
by this REST service<br/>
+ * 500 (Internal server error): An unexpected error occurred</td></tr>
+ * </table>
+ *
+ * @return The HTTP response
+ */
+ Response getConsumer(@Context final HttpServletRequest request,
+ @PathParam("consumerKey") final String consumerKey, @Context final
UriInfo uriInfo);
+
+ /**
+ * Adds a single consumer to the OAuth Service Consumer registry. This is
a REST service method, it is not intended
+ * to be invoked from Java. The details of this REST service method are
described below.
+ * <br/><br/>
+ * <table border="1" padding="2px">
+ * <tr><td><b>URI</b></td><td>/rest/oauth/consumers</td></tr>
+ * <tr><td><b>Method</b></td><td>PUT</td></tr>
+ * <tr><td><b>Supported media types</b></td><td>json, xml</td></tr>
+ * <tr><td><b>Description</b></td><td>Adds a single consumer to the OAuth
Service Consumer registry.</td></tr>
+ * <tr><td><b>Path parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Querystring parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Body parameters</b></td><td>JSON or XML expression
containing the properties of the consumer to add, including the id</td></tr>
+ * <tr><td><b>Authentication</b></td><td>Amdatu site
authentication</td></tr>
+ * <tr><td><b>Response</b></td><td>200 (OK): the consumer has been added
to the OAuth Service consumer registry<br/>
+ * 304 (Not Modified): a consumer with the specified id already existed,
hence the request is ignored
+ * 401 (Unauthorized): The client could not authenticate the user or the
user is not
+ * authorized to invoke this service<br/>
+ * 404 (Not found): The REST service is not available<br/>
+ * 415 (Unsupported Media Type): The requested media type is not supported
by this REST service<br/>
+ * 500 (Internal server error): An unexpected error occurred</td></tr>
+ * </table>
+ *
+ * @return The HTTP response
+ */
+ Response addConsumerJSONXML(@Context final HttpServletRequest request,
final ConsumerBean consumer);
+
+ /**
+ * Creates a new consumer with a generated id and adds it to the OAuth
Service Consumer registry. This is a REST service
+ * method, it is not intended to be invoked from Java. The details of this
REST service method are described below.
+ * <br/><br/>
+ * <table border="1" padding="2px">
+ * <tr><td><b>URI</b></td><td>/rest/oauth/consumers</td></tr>
+ * <tr><td><b>Method</b></td><td>POST</td></tr>
+ * <tr><td><b>Supported media types</b></td><td>json, xml</td></tr>
+ * <tr><td><b>Description</b></td><td>Creates a new consumer with a
generated id and adds it to the OAuth Service Consumer registry.</td></tr>
+ * <tr><td><b>Path parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Querystring parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Body parameters</b></td><td>name (String, optional):
descriptive name to assign to the new consumer <br/>
+ * callbackurl (String, optional): callback url of the new
consumer</td></tr>
+ * <tr><td><b>Authentication</b></td><td>Amdatu site
authentication</td></tr>
+ * <tr><td><b>Response</b></td><td>200 (OK): the consumer has been added
to the OAuth Service consumer registry<br/>
+ * 401 (Unauthorized): The client could not authenticate the user or the
user is not
+ * authorized to invoke this service<br/>
+ * 404 (Not found): The REST service is not available<br/>
+ * 415 (Unsupported Media Type): The requested media type is not supported
by this REST service<br/>
+ * 500 (Internal server error): An unexpected error occurred</td></tr>
+ * </table>
+ *
+ * @return The HTTP response
+ */
+ Response addConsumerFormEncoded(@Context final HttpServletRequest request,
+ @FormParam("name") final String name, @FormParam("callbackurl") final
String callbackUrl);
+
+ /**
+ * Updates the properties of an existing consumer. This is a REST service
+ * method, it is not intended to be invoked from Java. The details of this
REST service method are described below.
+ * <br/><br/>
+ * <table border="1" padding="2px">
+ * <tr><td><b>URI</b></td><td>/rest/oauth/consumers/{consumerKey}</td></tr>
+ * <tr><td><b>Method</b></td><td>PUT</td></tr>
+ * <tr><td><b>Supported media types</b></td><td>json, xml</td></tr>
+ * <tr><td><b>Description</b></td><td>Updates the properties of an
existing consumer.</td></tr>
+ * <tr><td><b>Path parameters</b></td><td>consumerKey: the id of the OAuth
service consumer to update</td></tr>
+ * <tr><td><b>Querystring parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Body parameters</b></td><td>JSON or XML expression
containing the properties of the consumer to update.</td></tr>
+ * <tr><td><b>Authentication</b></td><td>Amdatu site
authentication</td></tr>
+ * <tr><td><b>Response</b></td><td>200 (OK): the consumer has been updated
in the OAuth Service consumer registry<br/>
+ * 401 (Unauthorized): The client could not authenticate the user or the
user is not
+ * authorized to invoke this service<br/>
+ * 404 (Not found): The REST service is not available or no consumer
exists with the specified id<br/>
+ * 415 (Unsupported Media Type): The requested media type is not supported
by this REST service<br/>
+ * 500 (Internal server error): An unexpected error occurred</td></tr>
+ * </table>
+ *
+ * @return The HTTP response
+ */
+ Response updateConsumerWithBean(@Context final HttpServletRequest request,
+ @PathParam("consumerKey") final String consumerKey, final ConsumerBean
consumer);
+
+ /**
+ * Deletes a consumer from the OAuth Service consumer registry. This is a
REST service
+ * method, it is not intended to be invoked from Java. The details of this
REST service method are described below.
+ * <br/><br/>
+ * <table border="1" padding="2px">
+ * <tr><td><b>URI</b></td><td>/rest/oauth/consumers/{consumerKey}</td></tr>
+ * <tr><td><b>Method</b></td><td>DELETE</td></tr>
+ * <tr><td><b>Supported media types</b></td><td>NA</td></tr>
+ * <tr><td><b>Description</b></td><td>Deletes a consumer from the OAuth
Service consumer registry.</td></tr>
+ * <tr><td><b>Path parameters</b></td><td>consumerKey: the id of the OAuth
service consumer to delete</td></tr>
+ * <tr><td><b>Querystring parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Body parameters</b></td><td>-</td></tr>
+ * <tr><td><b>Authentication</b></td><td>Amdatu site
authentication</td></tr>
+ * <tr><td><b>Response</b></td><td>200 (OK): the consumer has been updated
in the OAuth Service consumer registry<br/>
+ * 401 (Unauthorized): The client could not authenticate the user or the
user is not
+ * authorized to invoke this service<br/>
+ * 404 (Not found): The REST service is not available or no consumer
exists with the specified id<br/>
+ * 415 (Unsupported Media Type): The requested media type is not supported
by this REST service<br/>
+ * 500 (Internal server error): An unexpected error occurred</td></tr>
+ * </table>
+ *
+ * @return The HTTP response
+ */
+ @DELETE
+ @Path("{consumerKey}")
+ Response deleteConsumer(@Context final HttpServletRequest request,
+ @PathParam("consumerKey") final String consumerKey);
+}
_______________________________________________
Amdatu-commits mailing list
[email protected]
http://lists.amdatu.org/mailman/listinfo/amdatu-commits
