From cd6f355037e5ea86b52b428e3af0e1945f73d0e0 Mon Sep 17 00:00:00 2001 From: Mark Thomas Date: Fri, 9 Oct 2015 13:31:39 +0000 Subject: [PATCH] Javadoc improvements. Use inherited Javadoc since it generally has more information. Fill in gaps using implementation Javadoc where available. git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1707724 13f79535-47bb-0310-9956-ffa450edef68 --- java/javax/servlet/ServletContext.java | 39 +++++---- .../catalina/core/ApplicationContext.java | 80 ++----------------- 2 files changed, 32 insertions(+), 87 deletions(-) diff --git a/java/javax/servlet/ServletContext.java b/java/javax/servlet/ServletContext.java index 99cd0dedc7e1..bee6a5ef8eb9 100644 --- a/java/javax/servlet/ServletContext.java +++ b/java/javax/servlet/ServletContext.java @@ -573,8 +573,7 @@ public interface ServletContext { * use this method. * @since Servlet 3.0 */ - public ServletRegistration.Dynamic addServlet(String servletName, - String className); + public ServletRegistration.Dynamic addServlet(String servletName, String className); /** * Register a servlet instance for use in this ServletContext. @@ -592,14 +591,15 @@ public ServletRegistration.Dynamic addServlet(String servletName, * use this method. * @since Servlet 3.0 */ - public ServletRegistration.Dynamic addServlet(String servletName, - Servlet servlet); + public ServletRegistration.Dynamic addServlet(String servletName, Servlet servlet); /** - * TODO SERVLET3 - Add comments - * @param servletName TODO - * @param servletClass TODO - * @return TODO + * Add servlet to context. + * @param servletName Name of servlet to add + * @param servletClass Class of servlet to add + * @return null if the servlet has already been fully defined, + * else a {@link javax.servlet.ServletRegistration.Dynamic} object + * that can be used to further configure the servlet * @throws IllegalStateException * If the context has already been initialised * @throws UnsupportedOperationException If called from a @@ -667,7 +667,6 @@ public T createServlet(Class c) */ public Map getServletRegistrations(); - /** /** * Add filter to context. * @param filterName Name of filter to add @@ -788,8 +787,9 @@ public FilterRegistration.Dynamic addFilter(String filterName, public SessionCookieConfig getSessionCookieConfig(); /** - * TODO SERVLET3 - Add comments - * @param sessionTrackingModes TODO + * Configures the available session tracking modes for this web application. + * @param sessionTrackingModes The session tracking modes to use for this + * web application * @throws IllegalArgumentException * If sessionTrackingModes specifies * {@link SessionTrackingMode#SSL} in combination with any other @@ -809,8 +809,15 @@ public void setSessionTrackingModes( Set sessionTrackingModes); /** - * TODO SERVLET3 - Add comments - * @return TODO + * Obtains the default session tracking modes for this web application. + * By default {@link SessionTrackingMode#URL} is always supported, {@link + * SessionTrackingMode#COOKIE} is supported unless the cookies + * attribute has been set to false for the context and {@link + * SessionTrackingMode#SSL} is supported if at least one of the connectors + * used by this context has the attribute secure set to + * true. + * @return The set of default session tracking modes for this web + * application * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a @@ -823,8 +830,10 @@ public void setSessionTrackingModes( public Set getDefaultSessionTrackingModes(); /** - * TODO SERVLET3 - Add comments - * @return TODO + * Obtains the currently enabled session tracking modes for this web + * application. + * @return The value supplied via {@link #setSessionTrackingModes(Set)} if + * one was previously set, else return the defaults * @throws UnsupportedOperationException If called from a * {@link ServletContextListener#contextInitialized(ServletContextEvent)} * method of a {@link ServletContextListener} that was not defined in a diff --git a/java/org/apache/catalina/core/ApplicationContext.java b/java/org/apache/catalina/core/ApplicationContext.java index 369e31f0fab1..2e1bffa31e67 100644 --- a/java/org/apache/catalina/core/ApplicationContext.java +++ b/java/org/apache/catalina/core/ApplicationContext.java @@ -806,72 +806,25 @@ public FilterRegistration getFilterRegistration(String filterName) { } - /** - * Add servlet to context. - * @param servletName Name of servlet to add - * @param servletClass Name of servlet class - * @return null if the servlet has already been fully defined, - * else a {@link javax.servlet.ServletRegistration.Dynamic} object - * that can be used to further configure the servlet - * @throws IllegalStateException if the context has already been initialised - * @throws UnsupportedOperationException - if this context was passed to the - * {@link ServletContextListener#contextInitialized(javax.servlet.ServletContextEvent)} - * method of a {@link ServletContextListener} that was not declared - * in web.xml, a web-fragment or annotated with - * {@link javax.servlet.annotation.WebListener}. - */ @Override - public ServletRegistration.Dynamic addServlet(String servletName, - String servletClass) throws IllegalStateException { - - return addServlet(servletName, servletClass, null); + public ServletRegistration.Dynamic addServlet(String servletName, String className) { + return addServlet(servletName, className, null); } - /** - * Add servlet to context. - * @param servletName Name of servlet to add - * @param servlet Servlet instance to add - * @return null if the servlet has already been fully defined, - * else a {@link javax.servlet.ServletRegistration.Dynamic} object - * that can be used to further configure the servlet - * @throws IllegalStateException if the context has already been initialised - * @throws UnsupportedOperationException - if this context was passed to the - * {@link ServletContextListener#contextInitialized(javax.servlet.ServletContextEvent)} - * method of a {@link ServletContextListener} that was not declared - * in web.xml, a web-fragment or annotated with - * {@link javax.servlet.annotation.WebListener}. - */ @Override - public ServletRegistration.Dynamic addServlet(String servletName, - Servlet servlet) throws IllegalStateException { - + public ServletRegistration.Dynamic addServlet(String servletName, Servlet servlet) { return addServlet(servletName, null, servlet); } - /** - * Add servlet to context. - * @param servletName Name of servlet to add - * @param servletClass Class of servlet to add - * @return null if the servlet has already been fully defined, - * else a {@link javax.servlet.ServletRegistration.Dynamic} object - * that can be used to further configure the servlet - * @throws IllegalStateException if the context has already been initialised - * @throws UnsupportedOperationException - if this context was passed to the - * {@link ServletContextListener#contextInitialized(javax.servlet.ServletContextEvent)} - * method of a {@link ServletContextListener} that was not declared - * in web.xml, a web-fragment or annotated with - * {@link javax.servlet.annotation.WebListener}. - */ @Override public ServletRegistration.Dynamic addServlet(String servletName, - Class servletClass) - throws IllegalStateException { - + Class servletClass) { return addServlet(servletName, servletClass.getName(), null); } + private ServletRegistration.Dynamic addServlet(String servletName, String servletClass, Servlet servlet) throws IllegalStateException { @@ -951,19 +904,12 @@ public ServletRegistration getServletRegistration(String servletName) { } - /** - * By default {@link SessionTrackingMode#URL} is always supported, {@link - * SessionTrackingMode#COOKIE} is supported unless the cookies - * attribute has been set to false for the context and {@link - * SessionTrackingMode#SSL} is supported if at least one of the connectors - * used by this context has the attribute secure set to - * true. - */ @Override public Set getDefaultSessionTrackingModes() { return defaultSessionTrackingModes; } + private void populateSessionTrackingModes() { // URL re-writing is always enabled by default defaultSessionTrackingModes = EnumSet.of(SessionTrackingMode.URL); @@ -987,10 +933,7 @@ private void populateSessionTrackingModes() { } } - /** - * Return the supplied value if one was previously set, else return the - * defaults. - */ + @Override public Set getEffectiveSessionTrackingModes() { if (sessionTrackingModes != null) { @@ -1006,15 +949,8 @@ public SessionCookieConfig getSessionCookieConfig() { } - /** - * @throws IllegalStateException if the context has already been initialised - * @throws IllegalArgumentException If SSL is requested in combination with - * anything else or if an unsupported - * tracking mode is requested - */ @Override - public void setSessionTrackingModes( - Set sessionTrackingModes) { + public void setSessionTrackingModes(Set sessionTrackingModes) { if (!context.getState().equals(LifecycleState.STARTING_PREP)) { throw new IllegalStateException(