jakarta.servlet.http.HttpServletMapping Maven / Gradle / Ivy
/*
* Copyright (c) 2017, 2019 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"
* 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}, 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 default 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();
}