javax.servlet.http.ServletMapping Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
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 immetable and are
* returned from {@link HttpServletRequest#getServletMapping}.
*
* 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 ServletMapping {
/**
* Return the portion of the URI path that caused this request to
* be matched or the empty String if not known or not knowable. 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 or the empty String if not known or not
* knowable. 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 or the empty String if not known
* or not knowable.
*
* @since 4.0
*/
public String getPattern();
/**
* Return the String representation for the
* {@code servlet-name} for this mapping or the empty String if not known
* or not knowable.
*
* @return the String representation for the
* {@code servlet-name} for this mapping or the empty String if not known
* or not knowable.
*
* @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();
}