You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pivot.apache.org by rw...@apache.org on 2015/09/30 22:00:13 UTC
svn commit: r1706150 - in /pivot/trunk:
web-server/src/org/apache/pivot/web/server/ web/src/org/apache/pivot/web/
Author: rwhitcomb
Date: Wed Sep 30 20:00:13 2015
New Revision: 1706150
URL: http://svn.apache.org/viewvc?rev=1706150&view=rev
Log:
PIVOT-976: More Javadoc corrections (warnings found by Java 8) in the "web" files.
Still many, many more Javadoc warnings left to fix.
Modified:
pivot/trunk/web-server/src/org/apache/pivot/web/server/QueryServlet.java
pivot/trunk/web/src/org/apache/pivot/web/PostQuery.java
pivot/trunk/web/src/org/apache/pivot/web/PutQuery.java
pivot/trunk/web/src/org/apache/pivot/web/Query.java
pivot/trunk/web/src/org/apache/pivot/web/QueryListener.java
Modified: pivot/trunk/web-server/src/org/apache/pivot/web/server/QueryServlet.java
URL: http://svn.apache.org/viewvc/pivot/trunk/web-server/src/org/apache/pivot/web/server/QueryServlet.java?rev=1706150&r1=1706149&r2=1706150&view=diff
==============================================================================
--- pivot/trunk/web-server/src/org/apache/pivot/web/server/QueryServlet.java (original)
+++ pivot/trunk/web-server/src/org/apache/pivot/web/server/QueryServlet.java Wed Sep 30 20:00:13 2015
@@ -143,6 +143,7 @@ public abstract class QueryServlet exten
/**
* Gets the host name that was requested.
+ * @return The host name from the request.
*/
public String getHostname() {
return hostname.get();
@@ -151,6 +152,7 @@ public abstract class QueryServlet exten
/**
* Returns the Internet Protocol (IP) port number of the interface on which
* the request was received.
+ * @return The port number from the request.
*/
public int getPort() {
return port.get().intValue();
@@ -158,6 +160,7 @@ public abstract class QueryServlet exten
/**
* Returns the portion of the request URL representing the context path.
+ * @return The context path from the request URL.
*/
public String getContextPath() {
return contextPath.get();
@@ -165,6 +168,7 @@ public abstract class QueryServlet exten
/**
* Returns the portion of the request URL representing the servlet path.
+ * @return The servlet path parsed out of the request URL.
*/
public String getServletPath() {
return servletPath.get();
@@ -172,6 +176,8 @@ public abstract class QueryServlet exten
/**
* Tells whether the request has been encrypted over HTTPS.
+ * @return {@code true} if the request was sent over HTTPS, {@code false} otherwise
+ * (regular HTTP).
*/
public boolean isSecure() {
return secure.get().booleanValue();
@@ -179,6 +185,8 @@ public abstract class QueryServlet exten
/**
* Returns the name of the HTTP protocol that the request is using.
+ * @return The {@code "http"} or {@code "https"} protocol string depending
+ * on the {@link #isSecure} setting.
*/
public String getProtocol() {
return isSecure() ? HTTPS_PROTOCOL : HTTP_PROTOCOL;
@@ -186,6 +194,7 @@ public abstract class QueryServlet exten
/**
* Returns the location of this servlet.
+ * @return The {@link URL} associated with this servlet.
*/
public URL getLocation() {
URL location;
@@ -202,6 +211,7 @@ public abstract class QueryServlet exten
/**
* Returns the servlet's parameter dictionary, which holds the values passed
* in the HTTP request query string.
+ * @return The set of parameters passed in this query.
*/
public QueryDictionary getParameters() {
return parameters.get();
@@ -210,6 +220,7 @@ public abstract class QueryServlet exten
/**
* Returns the servlet's request header dictionary, which holds the HTTP
* request headers.
+ * @return The set of request headers set in this query.
*/
public QueryDictionary getRequestHeaders() {
return requestHeaders.get();
@@ -218,6 +229,7 @@ public abstract class QueryServlet exten
/**
* Returns the servlet's response header dictionary, which holds the HTTP
* response headers that will be sent back to the client.
+ * @return The current set of response headers to return to the client.
*/
public QueryDictionary getResponseHeaders() {
return responseHeaders.get();
@@ -228,7 +240,7 @@ public abstract class QueryServlet exten
* immediately prior to the {@link #validate(Query.Method, Path)} method.
* <p> The default implementation is a no-op.
*
- * @throws ServletException
+ * @throws ServletException on any kind of error.
*/
protected void prepare() throws ServletException {
// No-op
@@ -239,7 +251,7 @@ public abstract class QueryServlet exten
* guaranteed to be called even if the HTTP handler method throws. <p> The
* default implementation is a no-op.
*
- * @throws ServletException
+ * @throws ServletException on any kind of error.
*/
protected void dispose() throws ServletException {
// No-op
@@ -250,9 +262,9 @@ public abstract class QueryServlet exten
* immediately prior to the HTTP handler method. <p> The default
* implementation is a no-op.
*
- * @param method
- * @param path
- * @throws QueryException
+ * @param method The type of query this is.
+ * @param path The path to the server resources.
+ * @throws QueryException if there is a problem, Houston.
*/
protected void validate(Query.Method method, Path path) throws QueryException {
// No-op
@@ -262,9 +274,9 @@ public abstract class QueryServlet exten
* Handles an HTTP GET request. The default implementation throws an HTTP
* 405 query exception.
*
- * @param path
+ * @param path The request path.
* @return The result of the GET.
- * @throws QueryException
+ * @throws QueryException on any error.
*/
protected Object doGet(Path path) throws QueryException {
throw new QueryException(Query.Status.METHOD_NOT_ALLOWED);
@@ -274,11 +286,11 @@ public abstract class QueryServlet exten
* Handles an HTTP POST request. The default implementation throws an HTTP
* 405 query exception.
*
- * @param path
- * @param value
+ * @param path The path of this request.
+ * @param value The value parsed from the POST request data.
* @return A URL containing the location of the created resource, or
* <tt>null</tt> if operation did not result in the creation of a resource.
- * @throws QueryException
+ * @throws QueryException on errors.
*/
protected URL doPost(Path path, Object value) throws QueryException {
throw new QueryException(Query.Status.METHOD_NOT_ALLOWED);
@@ -288,22 +300,22 @@ public abstract class QueryServlet exten
* Handles an HTTP GET request. The default implementation throws an HTTP
* 405 query exception.
*
- * @param path
- * @param value
+ * @param path The server path for this request.
+ * @param value The value parsed from the PUT request data.
* @return <tt>true</tt> if the operation resulted in the creation of a
* resource; <tt>false</tt>, otherwise.
- * @throws QueryException
+ * @throws QueryException on any error.
*/
protected boolean doPut(Path path, Object value) throws QueryException {
throw new QueryException(Query.Status.METHOD_NOT_ALLOWED);
}
/**
- * Handles an HTTP GET request. The default implementation throws an HTTP
+ * Handles an HTTP DELETE request. The default implementation throws an HTTP
* 405 query exception.
*
- * @param path
- * @throws QueryException
+ * @param path The server path for this request.
+ * @throws QueryException if there was a problem.
*/
protected void doDelete(Path path) throws QueryException {
throw new QueryException(Query.Status.METHOD_NOT_ALLOWED);
@@ -313,9 +325,10 @@ public abstract class QueryServlet exten
* Creates a serializer that will be used to serialize the current request
* data.
*
- * @param method
- * @param path
- * @throws QueryException
+ * @param method Type of query this serializer will apply to.
+ * @param path The server path this is intended for.
+ * @return The newly created serializer for this request.
+ * @throws QueryException if there is a problem.
*/
protected abstract Serializer<?> createSerializer(Query.Method method, Path path)
throws QueryException;
Modified: pivot/trunk/web/src/org/apache/pivot/web/PostQuery.java
URL: http://svn.apache.org/viewvc/pivot/trunk/web/src/org/apache/pivot/web/PostQuery.java?rev=1706150&r1=1706149&r2=1706150&view=diff
==============================================================================
--- pivot/trunk/web/src/org/apache/pivot/web/PostQuery.java (original)
+++ pivot/trunk/web/src/org/apache/pivot/web/PostQuery.java Wed Sep 30 20:00:13 2015
@@ -49,6 +49,7 @@ public class PostQuery extends Query<URL
/**
* Returns the value that will be POSTed to the server when the query is
* executed.
+ * @return The value to send.
*/
public Object getValue() {
return value;
Modified: pivot/trunk/web/src/org/apache/pivot/web/PutQuery.java
URL: http://svn.apache.org/viewvc/pivot/trunk/web/src/org/apache/pivot/web/PutQuery.java?rev=1706150&r1=1706149&r2=1706150&view=diff
==============================================================================
--- pivot/trunk/web/src/org/apache/pivot/web/PutQuery.java (original)
+++ pivot/trunk/web/src/org/apache/pivot/web/PutQuery.java Wed Sep 30 20:00:13 2015
@@ -47,6 +47,7 @@ public class PutQuery extends Query<Bool
/**
* Returns the value that will be PUT to the server when the query is
* executed.
+ * @return The value to send.
*/
public Object getValue() {
return value;
Modified: pivot/trunk/web/src/org/apache/pivot/web/Query.java
URL: http://svn.apache.org/viewvc/pivot/trunk/web/src/org/apache/pivot/web/Query.java?rev=1706150&r1=1706149&r2=1706150&view=diff
==============================================================================
--- pivot/trunk/web/src/org/apache/pivot/web/Query.java (original)
+++ pivot/trunk/web/src/org/apache/pivot/web/Query.java Wed Sep 30 20:00:13 2015
@@ -158,10 +158,12 @@ public abstract class Query<V> extends I
/**
* Creates a new web query.
*
- * @param hostname
- * @param port
- * @param path
- * @param secure
+ * @param hostname Name of the host to contact for this web query.
+ * @param port Port number on that host.
+ * @param path The resource path on the host that is the target of this query.
+ * @param secure A flag to say whether to use {@code http} or {@code https} as the protocol.
+ * @param executorService The executor to use for running the query (in the background).
+ * @throws IllegalArgumentException if the {@code URL} cannot be constructed.
*/
public Query(String hostname, int port, String path, boolean secure, ExecutorService executorService) {
super(executorService);
@@ -255,6 +257,7 @@ public abstract class Query<V> extends I
/**
* Returns the web query's parameter dictionary. Parameters are passed via
* the query string of the web query's URL.
+ * @return The current set of query parameters.
*/
public QueryDictionary getParameters() {
return parameters;
@@ -263,6 +266,7 @@ public abstract class Query<V> extends I
/**
* Returns the web query's request header dictionary. Request headers are
* passed via HTTP headers when the query is executed.
+ * @return The current set of request headers.
*/
public QueryDictionary getRequestHeaders() {
return requestHeaders;
@@ -271,6 +275,7 @@ public abstract class Query<V> extends I
/**
* Returns the web query's response header dictionary. Response headers are
* returned via HTTP headers when the query is executed.
+ * @return The current set of response headers.
*/
public QueryDictionary getResponseHeaders() {
return responseHeaders;
@@ -288,6 +293,7 @@ public abstract class Query<V> extends I
/**
* Returns the serializer used to stream the value passed to or from the web
* query. By default, an instance of {@link JSONSerializer} is used.
+ * @return The current serializer.
*/
public Serializer<?> getSerializer() {
return serializer;
@@ -298,6 +304,7 @@ public abstract class Query<V> extends I
* query.
*
* @param serializer The serializer (must be non-null).
+ * @throws IllegalArgumentException if the input is {@code null}.
*/
public void setSerializer(Serializer<?> serializer) {
if (serializer == null) {
@@ -316,6 +323,8 @@ public abstract class Query<V> extends I
* {@link QueryListener#requestSent(Query) requestSent} phases of the
* <tt>QueryListener</tt> lifecycle methods. Interested listeners can poll
* for this value during that phase.
+ * @return Number of bytes sent by POST or PUT requests, or 0 for GET and
+ * DELETE.
*/
public long getBytesSent() {
return bytesSent;
@@ -330,6 +339,7 @@ public abstract class Query<V> extends I
* {@link QueryListener#responseReceived(Query) responseReceived} phases of
* the <tt>QueryListener</tt> lifecycle methods. Interested listeners can
* poll for this value during that phase.
+ * @return The number of bytes received.
*/
public long getBytesReceived() {
return bytesReceived;
@@ -344,6 +354,7 @@ public abstract class Query<V> extends I
* the server did not specify a <tt>Content-Length</tt> HTTP response
* header, a value of <tt>-1</tt> will be returned to indicate that this
* value is unknown.
+ * @return The expected number of bytes to received based on the content length.
*/
public long getBytesExpected() {
return bytesExpected;
@@ -461,7 +472,7 @@ public abstract class Query<V> extends I
}
/**
- * Returns the query listener list.
+ * @return The query listener list.
*/
public ListenerList<QueryListener<V>> getQueryListeners() {
return queryListeners;
Modified: pivot/trunk/web/src/org/apache/pivot/web/QueryListener.java
URL: http://svn.apache.org/viewvc/pivot/trunk/web/src/org/apache/pivot/web/QueryListener.java?rev=1706150&r1=1706149&r2=1706150&view=diff
==============================================================================
--- pivot/trunk/web/src/org/apache/pivot/web/QueryListener.java (original)
+++ pivot/trunk/web/src/org/apache/pivot/web/QueryListener.java Wed Sep 30 20:00:13 2015
@@ -49,7 +49,7 @@ public interface QueryListener<V> {
* Called when a query has connected to the server but the request has not
* yet been sent.
*
- * @param query
+ * @param query The query that has just connected.
*/
public void connected(Query<V> query);
@@ -57,21 +57,21 @@ public interface QueryListener<V> {
* Called when the request has been sent to the server but the response has
* not yet been received.
*
- * @param query
+ * @param query The query whose request has been sent.
*/
public void requestSent(Query<V> query);
/**
* Called when a response has been received from the server.
*
- * @param query
+ * @param query The query whose response has just been received.
*/
public void responseReceived(Query<V> query);
/**
- * Called when an error has occurred
+ * Called when an error has occurred.
*
- * @param query
+ * @param query The query that has failed.
*/
public void failed(Query<V> query);
}