javax.servlet.http.HttpServletMapping Maven / Gradle / Ivy
/*
* Copyright (c) 2017, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package javax.servlet.http;
/**
* Allows runtime discovery of the manner in which the {@link
* HttpServlet} for the current {@link HttpServletRequest} was invoked.
* Invoking any of the methods must not block the caller. The
* implementation must be thread safe. Instances are immutable and are
* returned from {@link HttpServletRequest#getHttpServletMapping}.
*
* Following are some illustrative examples for various combinations
* of mappings. Consider the following Servlet declaration:
*
*
* <servlet>
* <servlet-name>MyServlet</servlet-name>
* <servlet-class>MyServlet</servlet-class>
* </servlet>
* <servlet-mapping>
* <servlet-name>MyServlet</servlet-name>
* <url-pattern>/MyServlet</url-pattern>
* <url-pattern>""</url-pattern>
* <url-pattern>*.extension</url-pattern>
* <url-pattern>/path/*</url-pattern>
* </servlet-mapping>
*
*
* The expected values of the properties for various incoming URI
* path values are as shown in this table. The {@code servletName}
* column is omitted as its value is always {@code MyServlet}.
*
*
* Expected values of properties for various URI paths
*
* URI Path (in quotes)
* matchValue
* pattern
* mappingMatch
*
*
* ""
* ""
* ""
* CONTEXT_ROOT
*
*
* "/index.html"
* ""
* /
* DEFAULT
*
*
* "/MyServlet"
* MyServlet
* /MyServlet
* EXACT
*
*
* "/foo.extension"
* foo
* *.extension
* EXTENSION
*
*
* "/path/foo"
* foo
* /path/*
* PATH
*
*
*
*
* @since 4.0
*/
public interface HttpServletMapping {
/**
* Return the portion of the URI path that caused this request to
* be matched. If the {@link getMappingMatch} value is {@code
* CONTEXT_ROOT} or {@code DEFAULT}, this method must return the
* empty string. If the {@link getMappingMatch} value is {@code
* EXACT}, this method must return the portion of the path that
* matched the servlet, omitting any leading slash. If the {@link
* getMappingMatch} value is {@code EXTENSION} or {@code PATH}, this
* method must return the value that matched the '*'. See the class
* javadoc for examples.
*
* @return the match.
*
* @since 4.0
*/
public String getMatchValue();
/**
* Return the String representation for the {@code url-pattern}
* for this mapping. If the {@link getMappingMatch} value is {@code
* CONTEXT_ROOT} or {@code DEFAULT}, this method must return the
* empty string. If the {@link getMappingMatch} value is {@code
* EXTENSION}, this method must return the pattern, without any
* leading slash. Otherwise, this method returns the pattern
* exactly as specified in the descriptor or Java configuration.
*
* @return the String representation for the
* {@code url-pattern} for this mapping.
*
* @since 4.0
*/
public String getPattern();
/**
* Return the String representation for the {@code servlet-name}
* for this mapping. If the Servlet providing the response is the
* default servlet, the return from this method is the name of the
* defautl servlet, which is container specific.
*
* @return the String representation for the {@code servlet-name}
* for this mapping.
*
* @since 4.0
*/
public String getServletName();
/**
* Return the {@link MappingMatch} for this
* instance
*
* @return the {@code MappingMatch} for this instance.
*
* @since 4.0
*/
public MappingMatch getMappingMatch();
}