This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/7.0.x by this push:
new 1d9d105 Update Javadoc for building with later Java versions / align
with 8.5.x
1d9d105 is described below
commit 1d9d105010f7481c0be289aef84a275728ea6205
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Tue Jan 21 15:26:08 2020 +0000
Update Javadoc for building with later Java versions / align with 8.5.x
---
java/org/apache/catalina/InstanceEvent.java | 42 +++++-----------
java/org/apache/catalina/Manager.java | 6 +--
java/org/apache/catalina/Pipeline.java | 2 +-
java/org/apache/catalina/Realm.java | 70 +++++++++++++++-----------
java/org/apache/catalina/Role.java | 6 +--
java/org/apache/catalina/Server.java | 26 +++++-----
java/org/apache/catalina/Service.java | 2 +-
java/org/apache/catalina/Session.java | 40 ++++++++-------
java/org/apache/catalina/startup/Catalina.java | 46 ++++++++---------
9 files changed, 119 insertions(+), 121 deletions(-)
diff --git a/java/org/apache/catalina/InstanceEvent.java
b/java/org/apache/catalina/InstanceEvent.java
index 513ee93..69aeea4 100644
--- a/java/org/apache/catalina/InstanceEvent.java
+++ b/java/org/apache/catalina/InstanceEvent.java
@@ -358,75 +358,59 @@ public final class InstanceEvent extends EventObject {
/**
- * Return the exception that occurred during the processing
+ * @return the exception that occurred during the processing
* that was reported by this event.
*/
public Throwable getException() {
-
- return (this.exception);
-
+ return this.exception;
}
/**
- * Return the filter instance for which this event occurred.
+ * @return the filter instance for which this event occurred.
*/
public Filter getFilter() {
-
- return (this.filter);
-
+ return this.filter;
}
/**
- * Return the servlet request for which this event occurred.
+ * @return the servlet request for which this event occurred.
*/
public ServletRequest getRequest() {
-
- return (this.request);
-
+ return this.request;
}
/**
- * Return the servlet response for which this event occurred.
+ * @return the servlet response for which this event occurred.
*/
public ServletResponse getResponse() {
-
- return (this.response);
-
+ return this.response;
}
/**
- * Return the servlet instance for which this event occurred.
+ * @return the servlet instance for which this event occurred.
*/
public Servlet getServlet() {
-
- return (this.servlet);
-
+ return this.servlet;
}
/**
- * Return the event type of this event.
+ * @return the event type of this event.
*/
public String getType() {
-
- return (this.type);
-
+ return this.type;
}
/**
- * Return the Wrapper managing the servlet instance for which this
+ * @return the Wrapper managing the servlet instance for which this
* event occurred.
*/
public Wrapper getWrapper() {
-
return (Wrapper) getSource();
-
}
-
-
}
diff --git a/java/org/apache/catalina/Manager.java
b/java/org/apache/catalina/Manager.java
index 3f02f6e..9a5dc19 100644
--- a/java/org/apache/catalina/Manager.java
+++ b/java/org/apache/catalina/Manager.java
@@ -63,7 +63,7 @@ public interface Manager {
/**
- * Return the distributable flag for the sessions supported by
+ * @return the distributable flag for the sessions supported by
* this Manager.
*
* @deprecated Ignored. {@link Context#getDistributable()} always takes
@@ -88,7 +88,7 @@ public interface Manager {
/**
- * Return descriptive information about this Manager implementation and
+ * @return descriptive information about this Manager implementation and
* the corresponding version number, in the format
* <code><description>/<version></code>.
*/
@@ -96,7 +96,7 @@ public interface Manager {
/**
- * Return the default maximum inactive interval (in seconds)
+ * @return the default maximum inactive interval (in seconds)
* for Sessions created by this Manager.
*
* @deprecated Ignored. {@link Context#getSessionTimeout()} always takes
diff --git a/java/org/apache/catalina/Pipeline.java
b/java/org/apache/catalina/Pipeline.java
index eef24a9..e61e176 100644
--- a/java/org/apache/catalina/Pipeline.java
+++ b/java/org/apache/catalina/Pipeline.java
@@ -123,7 +123,7 @@ public interface Pipeline {
/**
- * Return the Container with which this Pipeline is associated.
+ * @return the Container with which this Pipeline is associated.
*/
public Container getContainer();
diff --git a/java/org/apache/catalina/Realm.java
b/java/org/apache/catalina/Realm.java
index b2d07cf..b9797a4 100644
--- a/java/org/apache/catalina/Realm.java
+++ b/java/org/apache/catalina/Realm.java
@@ -14,8 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
-
package org.apache.catalina;
import java.beans.PropertyChangeListener;
@@ -27,6 +25,7 @@ import org.apache.catalina.connector.Request;
import org.apache.catalina.connector.Response;
import org.apache.catalina.deploy.SecurityConstraint;
import org.ietf.jgss.GSSContext;
+
/**
* A <b>Realm</b> is a read-only facade for an underlying security realm
* used to authenticate individual users, and identify the security roles
@@ -41,9 +40,8 @@ public interface Realm {
// ------------------------------------------------------------- Properties
-
/**
- * Return the Container with which this Realm has been associated.
+ * @return the Container with which this Realm has been associated.
*/
public Container getContainer();
@@ -57,7 +55,7 @@ public interface Realm {
/**
- * Return descriptive information about this Realm implementation and
+ * @return descriptive information about this Realm implementation and
* the corresponding version number, in the format
* <code><description>/<version></code>.
*/
@@ -66,7 +64,6 @@ public interface Realm {
// --------------------------------------------------------- Public Methods
-
/**
* Add a property change listener to this component.
*
@@ -76,37 +73,44 @@ public interface Realm {
/**
- * Return the Principal associated with the specified username, if there
- * is one; otherwise return <code>null</code>.
+ * Try to authenticate with the specified username.
*
* @param username Username of the Principal to look up
+ * @return the associated principal, or <code>null</code> if none is
+ * associated.
*/
public Principal authenticate(String username);
/**
- * Return the Principal associated with the specified username and
- * credentials, if there is one; otherwise return <code>null</code>.
+ * Try to authenticate using the specified username and
+ * credentials.
*
* @param username Username of the Principal to look up
* @param credentials Password or other credentials to use in
- * authenticating this username
+ * authenticating this username
+ * @return the associated principal, or <code>null</code> if there is none
*/
public Principal authenticate(String username, String credentials);
/**
- * Return the Principal associated with the specified username, which
+ * Try to authenticate with the specified username, which
* matches the digest calculated using the given parameters using the
- * method described in RFC 2069; otherwise return <code>null</code>.
+ * method described in RFC 2617 (which is a superset of RFC 2069).
*
* @param username Username of the Principal to look up
* @param digest Digest which has been submitted by the client
* @param nonce Unique (or supposedly unique) token which has been used
* for this request
+ * @param nc the nonce counter
+ * @param cnonce the client chosen nonce
+ * @param qop the "quality of protection" (<code>nc</code> and
<code>cnonce</code>
+ * will only be used, if <code>qop</code> is not <code>null</code>).
* @param realm Realm name
* @param md5a2 Second MD5 digest used to calculate the digest :
* MD5(Method + ":" + uri)
+ * @return the associated principal, or <code>null</code> if there is none.
*/
public Principal authenticate(String username, String digest,
String nonce, String nc, String cnonce,
@@ -115,22 +119,22 @@ public interface Realm {
/**
- * Return the Principal associated with the specified {@link GSSContext}.
- * If there is none, return <code>null</code>.
+ * Try to authenticate using a {@link GSSContext}
*
* @param gssContext The gssContext processed by the {@link Authenticator}.
* @param storeCreds Should the realm attempt to store the delegated
* credentials in the returned Principal?
+ * @return the associated principal, or <code>null</code> if there is none
*/
public Principal authenticate(GSSContext gssContext, boolean storeCreds);
/**
- * Return the Principal associated with the specified chain of X509
- * client certificates. If there is none, return <code>null</code>.
+ * Try to authenticate using {@link X509Certificate}s
*
* @param certs Array of client certificates, with the first one in
* the array being the certificate of the client itself.
+ * @return the associated principal, or <code>null</code> if there is none
*/
public Principal authenticate(X509Certificate certs[]);
@@ -144,10 +148,13 @@ public interface Realm {
/**
- * Return the SecurityConstraints configured to guard the request URI for
- * this request, or <code>null</code> if there is no such constraint.
+ * Find the SecurityConstraints configured to guard the request URI for
+ * this request.
*
* @param request Request we are processing
+ * @param context {@link Context} for this request
+ * @return the configured {@link SecurityConstraint}, of <code>null</code>
+ * if there is none
*/
public SecurityConstraint [] findSecurityConstraints(Request request,
Context context);
@@ -155,13 +162,13 @@ public interface Realm {
/**
* Perform access control based on the specified authorization constraint.
- * Return <code>true</code> if this constraint is satisfied and processing
- * should continue, or <code>false</code> otherwise.
*
* @param request Request we are processing
* @param response Response we are creating
* @param constraint Security constraint we are enforcing
* @param context The Context to which client of this class is attached.
+ * @return <code>true</code> if this constraint is satisfied and processing
+ * should continue, or <code>false</code> otherwise
*
* @exception IOException if an input/output error occurs
*/
@@ -173,25 +180,29 @@ public interface Realm {
/**
- * Return <code>true</code> if the specified Principal has the specified
- * security role, within the context of this Realm; otherwise return
- * <code>false</code>.
+ * Check if the specified Principal has the specified
+ * security role, within the context of this Realm.
*
* @param wrapper wrapper context for evaluating role
* @param principal Principal for whom the role is to be checked
* @param role Security role to be checked
+ * @return <code>true</code> if the specified Principal has the specified
+ * security role, within the context of this Realm; otherwise
return
+ * <code>false</code>.
*/
public boolean hasRole(Wrapper wrapper, Principal principal, String role);
- /**
+
+ /**
* Enforce any user data constraint required by the security constraint
- * guarding this request URI. Return <code>true</code> if this constraint
- * was not violated and processing should continue, or <code>false</code>
- * if we have created a response already.
+ * guarding this request URI.
*
* @param request Request we are processing
* @param response Response we are creating
* @param constraint Security constraint being checked
+ * @return <code>true</code> if this constraint
+ * was not violated and processing should continue, or
<code>false</code>
+ * if we have created a response already.
*
* @exception IOException if an input/output error occurs
*/
@@ -200,12 +211,11 @@ public interface Realm {
SecurityConstraint []constraint)
throws IOException;
+
/**
* Remove a property change listener from this component.
*
* @param listener The listener to remove
*/
public void removePropertyChangeListener(PropertyChangeListener listener);
-
-
}
diff --git a/java/org/apache/catalina/Role.java
b/java/org/apache/catalina/Role.java
index ac7c78f..ee18e68 100644
--- a/java/org/apache/catalina/Role.java
+++ b/java/org/apache/catalina/Role.java
@@ -36,7 +36,7 @@ public interface Role extends Principal {
/**
- * Return the description of this role.
+ * @return the description of this role.
*/
public String getDescription();
@@ -50,7 +50,7 @@ public interface Role extends Principal {
/**
- * Return the role name of this role, which must be unique
+ * @return the role name of this role, which must be unique
* within the scope of a {@link UserDatabase}.
*/
public String getRolename();
@@ -66,7 +66,7 @@ public interface Role extends Principal {
/**
- * Return the {@link UserDatabase} within which this Role is defined.
+ * @return the {@link UserDatabase} within which this Role is defined.
*/
public UserDatabase getUserDatabase();
diff --git a/java/org/apache/catalina/Server.java
b/java/org/apache/catalina/Server.java
index cfc4953..e880785 100644
--- a/java/org/apache/catalina/Server.java
+++ b/java/org/apache/catalina/Server.java
@@ -46,12 +46,10 @@ import org.apache.catalina.startup.Catalina;
*/
public interface Server extends Lifecycle {
-
// ------------------------------------------------------------- Properties
-
/**
- * Return descriptive information about this Server implementation and
+ * @return descriptive information about this Server implementation and
* the corresponding version number, in the format
* <code><description>/<version></code>.
*/
@@ -59,7 +57,7 @@ public interface Server extends Lifecycle {
/**
- * Return the global naming resources.
+ * @return the global naming resources.
*/
public NamingResources getGlobalNamingResources();
@@ -74,13 +72,13 @@ public interface Server extends Lifecycle {
/**
- * Return the global naming resources context.
+ * @return the global naming resources context.
*/
public javax.naming.Context getGlobalNamingContext();
/**
- * Return the port number we listen to for shutdown commands.
+ * @return the port number we listen to for shutdown commands.
*/
public int getPort();
@@ -94,7 +92,7 @@ public interface Server extends Lifecycle {
/**
- * Return the address on which we listen to for shutdown commands.
+ * @return the address on which we listen to for shutdown commands.
*/
public String getAddress();
@@ -108,7 +106,7 @@ public interface Server extends Lifecycle {
/**
- * Return the shutdown command string we are waiting for.
+ * @return the shutdown command string we are waiting for.
*/
public String getShutdown();
@@ -122,7 +120,7 @@ public interface Server extends Lifecycle {
/**
- * Return the parent class loader for this component. If not set, return
+ * @return the parent class loader for this component. If not set, return
* {@link #getCatalina()} {@link Catalina#getParentClassLoader()}. If
* catalina has not been set, return the system class loader.
*/
@@ -138,12 +136,14 @@ public interface Server extends Lifecycle {
/**
- * Return the outer Catalina startup/shutdown component if present.
+ * @return the outer Catalina startup/shutdown component if present.
*/
public Catalina getCatalina();
/**
* Set the outer Catalina startup/shutdown component if present.
+ *
+ * @param catalina the outer Catalina component
*/
public void setCatalina(Catalina catalina);
@@ -165,16 +165,16 @@ public interface Server extends Lifecycle {
/**
- * Return the specified Service (if it exists); otherwise return
- * <code>null</code>.
+ * Find the specified Service
*
* @param name Name of the Service to be returned
+ * @return the specified Service, or <code>null</code> if none exists.
*/
public Service findService(String name);
/**
- * Return the set of Services defined within this Server.
+ * @return the set of Services defined within this Server.
*/
public Service[] findServices();
diff --git a/java/org/apache/catalina/Service.java
b/java/org/apache/catalina/Service.java
index 04234b4..7eeae55 100644
--- a/java/org/apache/catalina/Service.java
+++ b/java/org/apache/catalina/Service.java
@@ -49,7 +49,7 @@ public interface Service extends Lifecycle {
public void setContainer(Container container);
/**
- * Return descriptive information about this Service implementation and
+ * @return descriptive information about this Service implementation and
* the corresponding version number, in the format
* <code><description>/<version></code>.
*/
diff --git a/java/org/apache/catalina/Session.java
b/java/org/apache/catalina/Session.java
index bba9c99..57af0e2 100644
--- a/java/org/apache/catalina/Session.java
+++ b/java/org/apache/catalina/Session.java
@@ -66,7 +66,7 @@ public interface Session {
/**
- * Return the authentication type used to authenticate our cached
+ * @return the authentication type used to authenticate our cached
* Principal, if any.
*/
public String getAuthType();
@@ -82,13 +82,13 @@ public interface Session {
/**
- * Return the creation time for this session.
+ * @return the creation time for this session.
*/
public long getCreationTime();
/**
- * Return the creation time for this session, bypassing the session
validity
+ * @return the creation time for this session, bypassing the session
validity
* checks.
*/
public long getCreationTimeInternal();
@@ -104,13 +104,13 @@ public interface Session {
/**
- * Return the session identifier for this session.
+ * @return the session identifier for this session.
*/
public String getId();
/**
- * Return the session identifier for this session.
+ * @return the session identifier for this session.
*/
public String getIdInternal();
@@ -136,7 +136,7 @@ public interface Session {
/**
- * Return descriptive information about this Session implementation and
+ * @return descriptive information about this Session implementation and
* the corresponding version number, in the format
* <code><description>/<version></code>.
*/
@@ -144,7 +144,7 @@ public interface Session {
/**
- * Return the last time the client sent a request associated with this
+ * @return the last time the client sent a request associated with this
* session, as the number of milliseconds since midnight, January 1, 1970
* GMT. Actions that your application takes, such as getting or setting
* a value associated with the session, do not affect the access time.
@@ -153,13 +153,13 @@ public interface Session {
public long getThisAccessedTime();
/**
- * Return the last client access time without invalidation check
+ * @return the last client access time without invalidation check
* @see #getThisAccessedTime()
*/
public long getThisAccessedTimeInternal();
/**
- * Return the last time the client sent a request associated with this
+ * @return the last time the client sent a request associated with this
* session, as the number of milliseconds since midnight, January 1, 1970
* GMT. Actions that your application takes, such as getting or setting
* a value associated with the session, do not affect the access time.
@@ -168,13 +168,13 @@ public interface Session {
public long getLastAccessedTime();
/**
- * Return the last client access time without invalidation check
+ * @return the last client access time without invalidation check
* @see #getLastAccessedTime()
*/
public long getLastAccessedTimeInternal();
/**
- * Return the Manager within which this Session is valid.
+ * @return the Manager within which this Session is valid.
*/
public Manager getManager();
@@ -188,7 +188,7 @@ public interface Session {
/**
- * Return the maximum time interval, in seconds, between client requests
+ * @return the maximum time interval, in seconds, between client requests
* before the servlet container will invalidate the session. A negative
* time indicates that the session should never time out.
*/
@@ -214,7 +214,7 @@ public interface Session {
/**
- * Return the authenticated Principal that is associated with this Session.
+ * @return the authenticated Principal that is associated with this
Session.
* This provides an <code>Authenticator</code> with a means to cache a
* previously authenticated Principal, and avoid potentially expensive
* <code>Realm.authenticate()</code> calls on every request. If there
@@ -235,7 +235,7 @@ public interface Session {
/**
- * Return the <code>HttpSession</code> for which this object
+ * @return the <code>HttpSession</code> for which this object
* is the facade.
*/
public HttpSession getSession();
@@ -250,7 +250,7 @@ public interface Session {
/**
- * Return the <code>isValid</code> flag for this session.
+ * @return <code>true</code> if the session is still valid
*/
public boolean isValid();
@@ -268,6 +268,9 @@ public interface Session {
/**
* Add a session event listener to this component.
+ *
+ * @param listener the SessionListener instance that should be notified
+ * for session events
*/
public void addSessionListener(SessionListener listener);
@@ -286,7 +289,7 @@ public interface Session {
/**
- * Return the object bound with the specified name to the internal notes
+ * @return the object bound with the specified name to the internal notes
* for this session, or <code>null</code> if no such binding exists.
*
* @param name Name of the note to be returned
@@ -295,7 +298,7 @@ public interface Session {
/**
- * Return an Iterator containing the String names of all notes bindings
+ * @return an Iterator containing the String names of all notes bindings
* that exist for this session.
*/
public Iterator<String> getNoteNames();
@@ -319,6 +322,9 @@ public interface Session {
/**
* Remove a session event listener from this component.
+ *
+ * @param listener remove the session listener, which will no longer be
+ * notified
*/
public void removeSessionListener(SessionListener listener);
diff --git a/java/org/apache/catalina/startup/Catalina.java
b/java/org/apache/catalina/startup/Catalina.java
index a58921e..20f1a95 100644
--- a/java/org/apache/catalina/startup/Catalina.java
+++ b/java/org/apache/catalina/startup/Catalina.java
@@ -39,6 +39,8 @@ import org.apache.catalina.Server;
import org.apache.catalina.core.StandardContext;
import org.apache.catalina.security.SecurityConfig;
import org.apache.juli.ClassLoaderLogManager;
+import org.apache.juli.logging.Log;
+import org.apache.juli.logging.LogFactory;
import org.apache.tomcat.util.ExceptionUtils;
import org.apache.tomcat.util.digester.Digester;
import org.apache.tomcat.util.digester.Rule;
@@ -159,6 +161,7 @@ public class Catalina {
// ------------------------------------------------------------- Properties
/**
+ * @param file The configuration file
* @deprecated Use {@link #setConfigFile(String)}
*/
@Deprecated
@@ -198,7 +201,7 @@ public class Catalina {
public ClassLoader getParentClassLoader() {
if (parentClassLoader != null) {
- return (parentClassLoader);
+ return parentClassLoader;
}
return ClassLoader.getSystemClassLoader();
}
@@ -214,10 +217,10 @@ public class Catalina {
/**
- * Return true if naming is enabled.
+ * @return <code>true</code> if naming is enabled.
*/
public boolean isUseNaming() {
- return (this.useNaming);
+ return this.useNaming;
}
@@ -242,11 +245,10 @@ public class Catalina {
/**
- * Process the specified command line arguments, and return
- * <code>true</code> if we should continue processing; otherwise
- * return <code>false</code>.
+ * Process the specified command line arguments.
*
* @param args Command line arguments to process
+ * @return <code>true</code> if we should continue processing
*/
protected boolean arguments(String args[]) {
@@ -254,7 +256,7 @@ public class Catalina {
if (args.length < 1) {
usage();
- return (false);
+ return false;
}
for (int i = 0; i < args.length; i++) {
@@ -264,10 +266,10 @@ public class Catalina {
} else if (args[i].equals("-config")) {
isConfig = true;
} else if (args[i].equals("-nonaming")) {
- setUseNaming( false );
+ setUseNaming(false);
} else if (args[i].equals("-help")) {
usage();
- return (false);
+ return false;
} else if (args[i].equals("start")) {
starting = true;
stopping = false;
@@ -279,17 +281,17 @@ public class Catalina {
stopping = true;
} else {
usage();
- return (false);
+ return false;
}
}
- return (true);
-
+ return true;
}
/**
* Return a File object representing our configuration file.
+ * @return the main configuration file
*/
protected File configFile() {
@@ -297,13 +299,14 @@ public class Catalina {
if (!file.isAbsolute()) {
file = new File(System.getProperty(Globals.CATALINA_BASE_PROP),
configFile);
}
- return (file);
+ return file;
}
/**
* Create and configure the Digester we will be using for startup.
+ * @return the main digester to parse server.xml
*/
protected Digester createStartDigester() {
long t1=System.currentTimeMillis();
@@ -407,7 +410,7 @@ public class Catalina {
if (log.isDebugEnabled()) {
log.debug("Digester for server.xml created " + ( t2-t1 ));
}
- return (digester);
+ return digester;
}
@@ -435,6 +438,7 @@ public class Catalina {
/**
* Create and configure the Digester we will be using for shutdown.
+ * @return the digester to process the stop operation
*/
protected Digester createStopDigester() {
@@ -451,7 +455,7 @@ public class Catalina {
"setServer",
"org.apache.catalina.Server");
- return (digester);
+ return digester;
}
@@ -467,7 +471,7 @@ public class Catalina {
}
Server s = getServer();
- if( s == null ) {
+ if (s == null) {
// Create and execute our Digester
Digester digester = createStopDigester();
File file = configFile();
@@ -562,7 +566,6 @@ public class Catalina {
initDirs();
// Before digester - it may be needed
-
initNaming();
// Create and execute our Digester
@@ -664,14 +667,12 @@ public class Catalina {
} else {
log.error("Catalina.start", e);
}
-
}
long t2 = System.nanoTime();
if(log.isInfoEnabled()) {
log.info("Initialization processed in " + ((t2 - t1) / 1000000) +
" ms");
}
-
}
@@ -860,11 +861,9 @@ public class Catalina {
}
String temp = System.getProperty("java.io.tmpdir");
- if (temp == null || (!(new File(temp)).exists())
- || (!(new File(temp)).isDirectory())) {
+ if (temp == null || (!(new File(temp)).isDirectory())) {
log.error(sm.getString("embedded.notmp", temp));
}
-
}
@@ -944,8 +943,7 @@ public class Catalina {
}
- private static final org.apache.juli.logging.Log log=
- org.apache.juli.logging.LogFactory.getLog( Catalina.class );
+ private static final Log log = LogFactory.getLog(Catalina.class);
}
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
