Skip to content

Commit

Permalink
Javadoc improvements.
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@markt-asf
markt-asf committed Oct 9, 2015
1 parent a3446bd commit cd6f355
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 87 deletions.
39 changes: 24 additions & 15 deletions java/javax/servlet/ServletContext.java
View file
Expand Up @@ -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.
Expand All @@ -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 <code>null</code> 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
Expand Down Expand Up @@ -667,7 +667,6 @@ public <T extends Servlet> T createServlet(Class<T> c)
*/
public Map<String, ? extends ServletRegistration> getServletRegistrations();

/**
/**
* Add filter to context.
* @param filterName Name of filter to add
Expand Down Expand Up @@ -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
Expand All @@ -809,8 +809,15 @@ public void setSessionTrackingModes(
Set<SessionTrackingMode> 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 <code>cookies</code>
* attribute has been set to <code>false</code> for the context and {@link
* SessionTrackingMode#SSL} is supported if at least one of the connectors
* used by this context has the attribute <code>secure</code> set to
* <code>true</code>.
* @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
Expand All @@ -823,8 +830,10 @@ public void setSessionTrackingModes(
public Set<SessionTrackingMode> 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
Expand Down
80 changes: 8 additions & 72 deletions java/org/apache/catalina/core/ApplicationContext.java
View file
Expand Up @@ -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 <code>null</code> 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 <code>null</code> 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 <code>null</code> 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<? extends Servlet> servletClass)
throws IllegalStateException {

Class<? extends Servlet> servletClass) {
return addServlet(servletName, servletClass.getName(), null);
}


private ServletRegistration.Dynamic addServlet(String servletName,
String servletClass, Servlet servlet) throws IllegalStateException {

Expand Down Expand Up @@ -951,19 +904,12 @@ public ServletRegistration getServletRegistration(String servletName) {
}


/**
* By default {@link SessionTrackingMode#URL} is always supported, {@link
* SessionTrackingMode#COOKIE} is supported unless the <code>cookies</code>
* attribute has been set to <code>false</code> for the context and {@link
* SessionTrackingMode#SSL} is supported if at least one of the connectors
* used by this context has the attribute <code>secure</code> set to
* <code>true</code>.
*/
@Override
public Set<SessionTrackingMode> getDefaultSessionTrackingModes() {
return defaultSessionTrackingModes;
}


private void populateSessionTrackingModes() {
// URL re-writing is always enabled by default
defaultSessionTrackingModes = EnumSet.of(SessionTrackingMode.URL);
Expand All @@ -987,10 +933,7 @@ private void populateSessionTrackingModes() {
}
}

/**
* Return the supplied value if one was previously set, else return the
* defaults.
*/

@Override
public Set<SessionTrackingMode> getEffectiveSessionTrackingModes() {
if (sessionTrackingModes != null) {
Expand All @@ -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<SessionTrackingMode> sessionTrackingModes) {
public void setSessionTrackingModes(Set<SessionTrackingMode> sessionTrackingModes) {

if (!context.getState().equals(LifecycleState.STARTING_PREP)) {
throw new IllegalStateException(
Expand Down

0 comments on commit cd6f355

Please sign in to comment.