Class Servlets
- Direct Known Subclasses:
Https
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interfaceA plugin used to provide additional browser information forgetBrowser(jakarta.servlet.ServletRequest, java.lang.String). -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intWhether to append params if both uri and params contain the same parameter.static final intWhether to ignore params if both uri and params contain the same parameter.static final intWhether to overwrite uri if both uri and params contain the same parameter.static final intWhether the specified parameters shall be passed thru the request attribute called arg. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic final ExtendletContextaddExtendletContext(jakarta.servlet.ServletContext ctx, String name, ExtendletContext extctx) Adds an extended context.static final voidforward(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, String uri) A shortcut of forward(request, response, uri, null, 0).static final voidforward(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, String uri, Map params, int mode) Forward to the specified URI.static final StringgenerateURI(String uri, Map params, int mode) Generates URI by appending the parameters.static StringgetBrowser(String userAgent) Returns the name of the browser, or null if not identifiable.static DoublegetBrowser(String userAgent, String name) Returns the version of the given browser name, or null if the client is not the given browsers.static StringgetBrowser(jakarta.servlet.ServletRequest request) Returns the name of the browser, or null if not identifiable.static DoublegetBrowser(jakarta.servlet.ServletRequest request, String name) Returns the version of the given browser name, or null if the client is not the given browsers.static Servlets.ClientIdentifierReturns the client identifier, or null if no such plugin.Returns a list of context paths (e.g., "/abc") that this application has.static StringgetDetail(jakarta.servlet.ServletRequest request) Returns the request detail information.static final ExtendletContextgetExtendletContext(jakarta.servlet.ServletContext ctx, String name) Returns the extended context of the specified name.static final StringgetExtension(String path) Returns the file/path extension of the specified path (excluding dot), or null if no extension at all.static final StringgetExtension(String path, boolean lastOnly) Returns the file/path extension of the specified path (excluding dot), or null if no extension at all.static final StringReturns a token to represent a limit-time offer.static StringgetNormalPath(String path) Returns the normal path; that is, will elminate the double dots ".."static final jakarta.servlet.RequestDispatchergetRequestDispatcher(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, String uri, Map params, int mode) Returns the request dispatch of the specified URI.static final URLgetResource(jakarta.servlet.ServletContext ctx, String uri) Returns the resource of the specified uri.static final InputStreamgetResourceAsStream(jakarta.servlet.ServletContext ctx, String uri) Returns the resource stream of the specified uri.static final StringgetUserAgent(jakarta.servlet.ServletRequest req) Returns the user-agent header, which indicates what the client is, or an empty string if not available.static final voidinclude(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, String uri) A shortcut of include(request, response, uri, null, 0).static final voidinclude(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, String uri, Map params, int mode) Includes the resource at the specified URI.static booleanReturns whether the user agent is a browser of the specified type.static booleanReturns whether the client is a browser of the specified type.static final booleanisForwarded(jakarta.servlet.ServletRequest request) Tests whether this page is forwarded by another page.static final booleanisIncluded(jakarta.servlet.ServletRequest request) Tests whether this page is included by another page.static final booleanisOfferExpired(String lto, int timeout) Returns whether a token returned by getLimitTimeOffer expired.static final booleanReturns whether the current Web server supports Servlet 2.3 or above.static final booleanReturns whether the current Web server supports Servlet 2.4 or above.static final booleanReturns whether the current Web server supports Servlet 3.0 or above.static final booleanisUniversalURL(String uri) Returns whether a URL starts with xxx://, mailto:, about:, javascript:, data:, //static final Stringlocate(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, String pgpath, org.zkoss.util.resource.Locator locator) Locates a page based on the current Locale.static final ExtendletContextremoveExtendletContext(jakarta.servlet.ServletContext ctx, String name) Removes an extended context of the specified name.static voidsetClientIdentifier(Servlets.ClientIdentifier clientId) Sets the client identifier that is used to assistisBrowser(jakarta.servlet.ServletRequest, java.lang.String)to identify a client.
-
Field Details
-
OVERWRITE_URI
public static final int OVERWRITE_URIWhether to overwrite uri if both uri and params contain the same parameter. Used bygenerateURI(java.lang.String, java.util.Map, int)- See Also:
-
IGNORE_PARAM
public static final int IGNORE_PARAMWhether to ignore params if both uri and params contain the same parameter. Used bygenerateURI(java.lang.String, java.util.Map, int)- See Also:
-
APPEND_PARAM
public static final int APPEND_PARAMWhether to append params if both uri and params contain the same parameter. In other words, they both appear as the final query string. Used bygenerateURI(java.lang.String, java.util.Map, int)- See Also:
-
PASS_THRU_ATTR
public static final int PASS_THRU_ATTRWhether the specified parameters shall be passed thru the request attribute called arg.- See Also:
-
-
Constructor Details
-
Servlets
protected Servlets()Utilities; no instantiation required.
-
-
Method Details
-
isUniversalURL
Returns whether a URL starts with xxx://, mailto:, about:, javascript:, data:, // -
isServlet3
public static final boolean isServlet3()Returns whether the current Web server supports Servlet 3.0 or above.- Since:
- 6.0.0
-
isServlet24
public static final boolean isServlet24()Returns whether the current Web server supports Servlet 2.4 or above.- Since:
- 3.0.0
-
isServlet23
public static final boolean isServlet23()Returns whether the current Web server supports Servlet 2.3 or above. Thus, ifisServlet24()returns true,isServlet23()must return true, too.- Since:
- 3.0.0
-
locate
public static final String locate(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, String pgpath, org.zkoss.util.resource.Locator locator) throws jakarta.servlet.ServletException Locates a page based on the current Locale. It never returns null.Notice that it cannot resolve a path starting with '~', and containing '*', because it cannot access the content of the other servlet context.
If an URI contains "*", it will be replaced with a proper Locale. For example, if the current Locale is zh_TW and the resource is named "ab*.cd", then it searches "ab_zh_TW.cd", "ab_zh.cd" and then "ab.cd", until any of them is found.
Note: "*" must be right before ".", or the last character. For example, "ab*.cd" and "ab*" are both correct, while "ab*cd" and "ab*\/cd" are ignored.
If an URI contains two "*", the first "*" will be replaced with a browser code and the second with a proper locale. The browser code depends on what browser the user are used to visit the web site. Currently, the code for Internet Explorer is "ie", Safari is "saf", Opera is "opr" and all others are "moz". Thus, in the above example, if the resource is named "ab**.cd" and Firefox is used, then it searches "abmoz_zh_TW.cd", "abmoz_zh.cd" and then "abmoz.cd", until any of them is found.
Note: it assumes the path as name_lang_cn_var.ext where ".ext" is optional. Example, my_zh_tw.html.jsp.
- Parameters:
ctx- the servlet context to locate pagespgpath- the page path excluding servlet name. It is OK to have the query string. It might contain "*" for current browser code and Locale.locator- the locator used to locate resource. If null, ctx is assumed.- Returns:
- the path that matches the wildcard;
pgpath, otherwise never null - Throws:
jakarta.servlet.ServletException- See Also:
-
Locales.getCurrent()
-
setClientIdentifier
Sets the client identifier that is used to assistisBrowser(jakarta.servlet.ServletRequest, java.lang.String)to identify a client.Notice that the client identifier must be thread-safe.
- Parameters:
clientId- the client identifier. If null, only the default types are recognized.- Since:
- 6.0.0
- See Also:
-
getClientIdentifier
Returns the client identifier, or null if no such plugin.- Since:
- 6.0.0
- See Also:
-
getBrowser
Returns the version of the given browser name, or null if the client is not the given browsers.Notice that, after this method is called, an attribute named zk will be stored to the request, such that you can retrieve the browser information by use of EL, such as
${zk.ff > 5}.- Parameters:
request- the request.name- the browser's name. It includes "ff", "gecko", "webkit", "safari", "opera", "android", "mobile", "ios", "iphone", "ipad" and "ipod". And, "ff" is the same as "gecko", and "webkit" is the same as "safari".- Since:
- 6.0.0
-
getBrowser
Returns the name of the browser, or null if not identifiable.- Since:
- 6.0.0
-
getBrowser
Returns the version of the given browser name, or null if the client is not the given browsers.Notice that, after this method is called, an attribute named zk will be stored to the request, such that you can retrieve the browser information by use of EL, such as
${zk.ff > 5}.- Parameters:
userAgent- the user agent (i.e., the user-agent header in HTTP).name- the browser's name. It includes "ff", "gecko", "webkit", "safari", "opera", "android", "mobile", "ios", "iphone", "ipad" and "ipod". And, "ff" is the same as "gecko", and "webit" is the same as "safari".- Since:
- 6.0.0
-
getBrowser
Returns the name of the browser, or null if not identifiable.- Parameters:
userAgent- the user agent (i.e., the user-agent header in HTTP).- Since:
- 6.0.0
-
isBrowser
Returns whether the client is a browser of the specified type. To more accurately specify the browser, please usegetUserAgent(ServletRequest)instead.- Parameters:
type- the type of the browser. The syntax:<browser-name>[<version-number>][-].
For example, ie9, ios and ie6-. And,ie9means Internet Explorer 9 and later, whileie6-means Internet Explorer 6 (not prior, nor later).- Since:
- 3.5.1
-
isBrowser
Returns whether the user agent is a browser of the specified type. To more accurately specify the browser, please usegetUserAgent(ServletRequest)instead.- Parameters:
userAgent- represents a client. For HTTP clients, It is the user-agent header.type- the type of the browser, or a list of types separated by comma.
The syntax:<browser-name>[<version-number>][-].
For example, ie9, ios and ie6-. And,ie9means Internet Explorer 9 and later, whileie6-means Internet Explorer 6 (not prior, nor later).
If a list of types are specified (such asie6-,ie7-), this method returns true if any of them matches (i.e., OR condition).- Since:
- 3.5.1
-
getUserAgent
Returns the user-agent header, which indicates what the client is, or an empty string if not available.Note: it doesn't return null.
- Since:
- 3.0.2
-
isIncluded
public static final boolean isIncluded(jakarta.servlet.ServletRequest request) Tests whether this page is included by another page. -
isForwarded
public static final boolean isForwarded(jakarta.servlet.ServletRequest request) Tests whether this page is forwarded by another page. -
forward
public static final void forward(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, String uri, Map params, int mode) throws IOException, jakarta.servlet.ServletException Forward to the specified URI. It enhances RequestDispatcher in the following ways.- It handles "~ctx"" where ctx is the context path of the foreign context. It is called foreign URI.
- It detects whether the page calling this method is included by another servlet/page. If so, it uses RequestDispatcher.include() instead of RequestDispatcher.forward().
- The forwarded page could accept additional parameters -- actually converting parameters to a query string and appending it to uri.
- In additions, it does HTTP encoding, i.e., converts '+' and other characters to comply HTTP.
NOTE: don't include query parameters in uri.
- Parameters:
ctx- the servlet context. If null, uri cannot be foreign URI. It is ignored if URI is relevant (neither starts with '/' nor '~').uri- the URI to include. It is OK to relevant (without leading '/'). If starts with "/", the context path of request is assumed. To reference to foreign context, use "~ctx" where ctx is the context path of the foreign context (without leading '/'). If it could be any context path recognized by the Web container or any name registered withaddExtendletContext(jakarta.servlet.ServletContext, java.lang.String, org.zkoss.web.util.resource.ExtendletContext).
Notice that, since 3.6.3,uricould contain '*' (to denote locale and browser). Refer tolocate(jakarta.servlet.ServletContext, jakarta.servlet.ServletRequest, java.lang.String, org.zkoss.util.resource.Locator).params- the parameter map; null to ignoremode- one ofOVERWRITE_URI,IGNORE_PARAM, andAPPEND_PARAM. It defines how to handle if both uri and params contains the same parameter.- Throws:
IOExceptionjakarta.servlet.ServletException
-
forward
public static final void forward(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, String uri) throws IOException, jakarta.servlet.ServletException A shortcut of forward(request, response, uri, null, 0).- Throws:
IOExceptionjakarta.servlet.ServletException
-
include
public static final void include(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, String uri, Map params, int mode) throws IOException, jakarta.servlet.ServletException Includes the resource at the specified URI. It enhances RequestDispatcher to allow the inclusion with a parameter map -- acutually converting parameters to a query string and appending it to uri.NOTE: don't include query parameters in uri.
- Parameters:
ctx- the servlet context. If null, uri cannot be foreign URI. It is ignored if URI is relevant (neither starts with '/' nor '~').uri- the URI to include. It is OK to relevant (without leading '/'). If starts with "/", the context path of request is assumed. To reference to foreign context, use "~ctx/" where ctx is the context path of the foreign context (without leading '/').
Notice that, since 3.6.3,uricould contain '*' (to denote locale and browser). Refer tolocate(jakarta.servlet.ServletContext, jakarta.servlet.ServletRequest, java.lang.String, org.zkoss.util.resource.Locator).params- the parameter map; null to ignoremode- one ofOVERWRITE_URI,IGNORE_PARAM, andAPPEND_PARAM. It defines how to handle if both uri and params contains the same parameter.- Throws:
IOExceptionjakarta.servlet.ServletException
-
include
public static final void include(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, jakarta.servlet.ServletResponse response, String uri) throws IOException, jakarta.servlet.ServletException A shortcut of include(request, response, uri, null, 0).- Throws:
IOExceptionjakarta.servlet.ServletException
-
getRequestDispatcher
public static final jakarta.servlet.RequestDispatcher getRequestDispatcher(jakarta.servlet.ServletContext ctx, jakarta.servlet.ServletRequest request, String uri, Map params, int mode) throws jakarta.servlet.ServletException Returns the request dispatch of the specified URI.- Parameters:
ctx- the servlet context. If null, uri cannot be foreign URI. It is ignored if uri is relevant (neither starts with '/' nor '~').request- the request. If null, uri cannot be relevant. It is used only if uri is relevant.uri- the URI to include. It is OK to relevant (without leading '/'). If starts with "/", the context path of request is assumed. To reference to foreign context, use "~ctx/" where ctx is the context path of the foreign context (without leading '/').params- the parameter map; null to ignoremode- one ofOVERWRITE_URI,IGNORE_PARAM, andAPPEND_PARAM. It defines how to handle if both uri and params contains the same parameter.- Throws:
jakarta.servlet.ServletException
-
getResource
public static final URL getResource(jakarta.servlet.ServletContext ctx, String uri) throws UnsupportedEncodingException Returns the resource of the specified uri. Unlike ServletContext.getResource, it handles "~" likegetRequestDispatcher(jakarta.servlet.ServletContext, jakarta.servlet.ServletRequest, java.lang.String, java.util.Map, int)did.Since 5.0.7, file://, http://, https:// and ftp:// are supported.
- Throws:
UnsupportedEncodingException
-
getResourceAsStream
public static final InputStream getResourceAsStream(jakarta.servlet.ServletContext ctx, String uri) throws IOException Returns the resource stream of the specified uri. Unlike ServletContext.getResource, it handles "~" likegetRequestDispatcher(jakarta.servlet.ServletContext, jakarta.servlet.ServletRequest, java.lang.String, java.util.Map, int)did.Since 5.0.7, file://, http://, https:// and ftp:// are supported.
- Throws:
IOException
-
generateURI
Generates URI by appending the parameters. Note: it doesn't support the ~xxx/ format.- Parameters:
params- the parameters to apend to the query stringmode- one ofOVERWRITE_URI,IGNORE_PARAM,APPEND_PARAMandPASS_THRU_ATTR. It defines how to handle if both uri and params contains the same parameter. mode is used only if both uri contains query string and params is not empty.- See Also:
-
getContextPaths
Returns a list of context paths (e.g., "/abc") that this application has. This implementation parse application.xml. For war that doesn't contain application.xml might have to override this method and parse another file to know what context being loaded. -
getLimitTimeOffer
Returns a token to represent a limit-time offer. It is mainly used as an parameter value (mostlycalled zk_lto), and then you could verify whether it is expired byisOfferExpired(java.lang.String, int). -
isOfferExpired
Returns whether a token returned by getLimitTimeOffer expired.- Parameters:
timeout- how long the office shall expire, unit: seconds.
-
addExtendletContext
public static final ExtendletContext addExtendletContext(jakarta.servlet.ServletContext ctx, String name, ExtendletContext extctx) Adds an extended context.- Returns:
- the previous extended context, if any, associated with the specified name.
-
removeExtendletContext
public static final ExtendletContext removeExtendletContext(jakarta.servlet.ServletContext ctx, String name) Removes an extended context of the specified name. -
getExtendletContext
public static final ExtendletContext getExtendletContext(jakarta.servlet.ServletContext ctx, String name) Returns the extended context of the specified name. -
getExtension
Returns the file/path extension of the specified path (excluding dot), or null if no extension at all.Note: the extension is converted to the lower case.
- Parameters:
path- the path. If path is null, null is returned.- Since:
- 2.4.1
- See Also:
-
getExtension
Returns the file/path extension of the specified path (excluding dot), or null if no extension at all.Note: the extension is converted to the lower case.
The result is the same for both
getExtension(String)andgetExtension(String, boolean), if the path has only one dot. However, if there are more than one dot, e.g., /a/b.c.d, thengetExtension(String)retrieves the last extension, that is, d in this example. On the other hand, if you invoke getExtension(path, false), it returns the complete extension, that is, c.d in this example.- Parameters:
path- the path. If path is null, null is returned.lastOnly- whether to return the last portion of extensioin if there are two or more dots. In other wors, getExtension(path) is the same as getExtension(path, true).- Since:
- 3.5.1
-
getDetail
Returns the request detail information. It is used to log the debug info.- Since:
- 3.0.5
-
getNormalPath
Returns the normal path; that is, will elminate the double dots ".."(parent) and single dot "."(current) in the path as possible. e.g. /abc/../def would be normalized to /def; /abc/./def would be normalized to /abc/def; /abc//def would be normalized to /abc/def.Note that if found no way to navigate the path, it is deemed as an illegal path. e.g. /../abc or /../../abc is deemed as illegal path since we don't know how to continue doing the normalize.
- Since:
- 3.6.2
-