jakarta.servlet.http.HttpServletMapping Maven / Gradle / Ivy
/*
* Copyright (c) 2017, 2023 Oracle and/or its affiliates and others.
* 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 jakarta.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/index.html"
* ""
* /
* DEFAULT
*
*
* "/MyServlet"
* MyServlet
* /MyServlet
* EXACT
*
*
* "MyServlet/foo"
* ""
* /
* DEFAULT
*
*
* "/foo.extension"
* foo
* *.extension
* EXTENSION
*
*
* "/bar/foo.extension"
* bar/foo
* *.extension
* EXTENSION
*
*
* "/path/foo"
* foo
* /path/*
* PATH
*
*
* "/path/foo/bar"
* foo/bar
* /path/*
* PATH
*
*
*
*
* @since Servlet 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 '*' excluding any leading '/'. See the class javadoc for examples.
*
*
* @return the match.
*/
String getMatchValue();
/**
*
* Return the String representation for the {@code url-pattern} for this mapping. 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.
*/
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 default servlet, which is container specific.
*
*
* @return the String representation for the {@code servlet-name} for this mapping.
*/
String getServletName();
/**
*
* Return the {@link MappingMatch} for this instance.
*
*
* @return the {@code MappingMatch} for this instance.
*/
MappingMatch getMappingMatch();
}