Package org.kohsuke.stapler

Interface StaplerRequest2

All Superinterfaces:
jakarta.servlet.http.HttpServletRequest, jakarta.servlet.ServletRequest
All Known Implementing Classes:
RequestImpl, StaplerRequest.StaplerRequest2WrapperImpl
public interface StaplerRequest2 extends jakarta.servlet.http.HttpServletRequest
Defines additional parameters/operations made available by Stapler.
Author:
Kohsuke Kawaguchi
See Also:

  • Method Details

    • getStapler

      Stapler getStapler()
      Gets the Stapler instance that this belongs to.

    • getWebApp

      WebApp getWebApp()
      Short for getStapler().getWebApp()

    • getRestOfPath

      String getRestOfPath()
      Returns the additional URL portion that wasn't used by the stapler, excluding the query string.

      For example, if the requested URL is "foo/bar/zot/abc?def=ghi" and "foo/bar" portion matched bar.jsp, this method returns "/zot/abc".

      If this method is invoked from getters or StaplerProxy.getTarget() during the object traversal, this method returns the path portion that is not yet processed.

      Returns:
      can be empty string, but never null.

    • getOriginalRestOfPath

      String getOriginalRestOfPath()
      Returns the same thing as getRestOfPath() but in the pre-decoded form, so all "%HH"s as present in the request URL is intact.

    • getServletContext

      jakarta.servlet.ServletContext getServletContext()
      Returns the ServletContext object given to the stapler dispatcher servlet.
      Specified by:
      getServletContext in interface jakarta.servlet.ServletRequest

    • getRequestURIWithQueryString

      String getRequestURIWithQueryString()
      HttpServletRequest.getRequestURI() plus additional query string part, if it exists.

    • getRequestURLWithQueryString

      StringBuffer getRequestURLWithQueryString()
      HttpServletRequest.getRequestURL() plus additional query string part, if it exists.

    • getView

      jakarta.servlet.RequestDispatcher getView(Object it, String viewName) throws IOException
      Gets the RequestDispatcher that represents a specific view for the given object. This support both JSP and Jelly.
      Parameters:
      viewName - If this name is relative name like "foo.jsp" or "bar/zot.jelly", then the corresponding "side file" is searched by this name.

      For Jelly, this also accepts absolute path name that starts with '/', such as "/foo/bar/zot.jelly". In this case, it.getClass().getClassLoader() is searched for this script.

      Returns:
      null if neither JSP nor Jelly is not found by the given name.
      Throws:
      IOException

    • getView

      jakarta.servlet.RequestDispatcher getView(Class clazz, String viewName) throws IOException
      Convenience method to call getView(Klass, String) with Class.
      Throws:
      IOException

    • getView

      jakarta.servlet.RequestDispatcher getView(Klass<?> clazz, String viewName) throws IOException
      Gets the RequestDispatcher that represents a specific view for the given class.

      Unlike getView(Object, String), calling this request dispatcher doesn't set the "it" variable, so getView(it.getClass(),viewName) and getView(it,viewName) aren't the same thing.

      Throws:
      IOException

    • getRootPath

      String getRootPath()
      Gets the part of the request URL from protocol up to the context path. So typically it's something like http://foobar:8080/something

    • getReferer

      String getReferer()
      Gets the referer header (like "http://foobar.com/zot") or null. This is just a convenience method.

    • getAncestors

      List<Ancestor> getAncestors()
      Returns a list of ancestor objects that lead to the "it" object. The returned list contains Ancestor objects sorted in the order from root to the "it" object.

      For example, if the URL was "foo/bar/zot" and the "it" object was determined as root.getFoo().getBar("zot"), then this list will contain the following 3 objects in this order:

      1. the root object
      2. root.getFoo() object
      3. root.getFoo().getBar("zot") object (the "it" object)

      Returns:
      list of Ancestors. Can be empty, but always non-null.

    • findAncestor

      Ancestor findAncestor(Class type)
      Finds the nearest ancestor that has the object of the given type, or null if not found.

    • findAncestorObject

      <T> T findAncestorObject(Class<T> type)
      Short for findAncestor(type).getObject(), with proper handling for null de-reference. This version is also type safe.

    • findAncestor

      Ancestor findAncestor(Object o)
      Finds the nearest ancestor whose Ancestor.getObject() matches the given object.

    • hasParameter

      boolean hasParameter(String name)
      Short for getParameter(name)!=null

    • getOriginalRequestURI

      String getOriginalRequestURI()
      Gets the request URI of the original request, so that you can access the value even from JSP.

    • checkIfModified

      boolean checkIfModified(long timestampOfResource, StaplerResponse2 rsp)
      Checks "If-Modified-Since" header and returns false if the resource needs to be served.

      This method can behave in three ways.

      1. If timestampOfResource is 0 or negative, this method just returns false.
      2. If "If-Modified-Since" header is sent and if it's bigger than timestampOfResource, then this method sets HttpServletResponse.SC_NOT_MODIFIED as the response code and returns true.
      3. Otherwise, "Last-Modified" header is added with timestampOfResource value, and this method returns false.

      This method sends out the "Expires" header to force browser to re-validate all the time.

      Parameters:
      timestampOfResource - The time stamp of the resource.
      rsp - This object is updated accordingly to simplify processing.
      Returns:
      false to indicate that the caller has to serve the actual resource. true to indicate that the caller should just quit processing right there (and send back HttpServletResponse.SC_NOT_MODIFIED.

    • checkIfModified

      boolean checkIfModified(Date timestampOfResource, StaplerResponse2 rsp)
      See Also:

    • checkIfModified

      boolean checkIfModified(Calendar timestampOfResource, StaplerResponse2 rsp)
      See Also:

    • checkIfModified

      boolean checkIfModified(long timestampOfResource, StaplerResponse2 rsp, long expiration)
      Parameters:
      expiration - The number of milliseconds until the resource will "expire". Until it expires the browser will be allowed to cache it and serve it without checking back with the server. After it expires, the client will send conditional GET to check if the resource is actually modified or not. If 0, it will immediately expire.
      See Also:

    • bindParameters

      void bindParameters(Object bean)
      Binds form parameters to a bean by using introspection. For example, if there's a parameter called 'foo' that has value 'abc', then bean.setFoo('abc') will be invoked. This will be repeated for all parameters. Parameters that do not have corresponding setters will be simply ignored.

      Values are converted into the right type. See ConvertUtils.convert(String, Class).

      Parameters:
      bean - The object which will be filled out.
      See Also:
      • BeanUtils.setProperty(Object, String, Object)

    • bindParameters

      @Deprecated void bindParameters(Object bean, String prefix)
      Deprecated.
      Instead of using prefix to group object among form parameter names, use structured form submission and bindJSON(Class, JSONObject).
      Binds form parameters to a bean by using introspection. This method works like bindParameters(Object), but it performs a pre-processing on property names. Namely, only property names that start with the given prefix will be used for binding, and only the portion of the property name after the prefix is used. So for example, if the prefix is "foo.", then property name "foo.bar" with value "zot" will invoke bean.setBar("zot").

    • bindParametersToList

      @Deprecated <T> List<T> bindParametersToList(Class<T> type, String prefix)
      Deprecated.
      Instead of using prefix to group object among form parameter names, use structured form submission and bindJSON(Class, JSONObject).
      Binds collection form parameters to beans by using introspection or constructor parameters injection.

      This method works like bindParameters(Object,String) and bindParameters(Class, String), but it assumes that form parameters have multiple-values, and use individual values to fill in multiple beans.

      For example, if getParameterValues("foo")=={"abc","def"} and getParameterValues("bar")=={"5","3"}, then this method will return two objects (the first with "abc" and "5", the second with "def" and "3".)

      Parameters:
      type - Type of the bean to be created. This class must have the default no-arg constructor.
      prefix - See bindParameters(Object, String) for details.
      Returns:
      Can be empty but never null.

    • bindParameters

      @Deprecated <T> T bindParameters(Class<T> type, String prefix)
      Deprecated.
      Instead of using prefix to group object among form parameter names, use structured form submission and bindJSON(Class, JSONObject).
      Instantiates a new object by injecting constructor parameters from the form parameters.

      The given class must have a constructor annotated with '@stapler-constructor', and must be processed by the maven-stapler-plugin, so that the parameter names of the constructor is available at runtime.

      The prefix is used to control the form parameter name. For example, if the prefix is "foo." and if the constructor is define as Foo(String a, String b), then the constructor will be invoked as new Foo(getParameter("foo.a"),getParameter("foo.b")).

    • bindParameters

      @Deprecated <T> T bindParameters(Class<T> type, String prefix, int index)
      Deprecated.
      Instead of using prefix to group object among form parameter names, use structured form submission and bindJSON(Class, JSONObject).
      Works like bindParameters(Class, String) but uses n-th value of all the parameters.

      This is useful for creating multiple instances from repeated form fields.

    • bindJSON

      <T> T bindJSON(Class<T> type, net.sf.json.JSONObject src)
      Data-bind from a JSONObject to the given target type, by using introspection or constructor parameters injection.

      For example, if you have a constructor that looks like the following: 

       class Foo {
   @DataBoundConstructor
   public Foo(Integer x, String y, boolean z, Bar bar) { ... }
 }

 class Bar {
   @DataBoundConstructor
   public Bar(int x, int y) {}
 }
      ... and if JSONObject looks like 
      { y:"text", z:true, bar:{x:1,y:2}}
      then, this method returns 
      new Foo(null,"text",true,new Bar(1,2))

      Sub-typing: In the above example, a new instance of Bar was created, but you can also create a subtype of Bar by having the '$class' property in JSON like this: 

       class BarEx extends Bar {
   @DataBoundConstructor
   public BarEx(int a, int b, int c) {}
 }

 { y:"text", z:true, bar: { $class:"p.k.g.BarEx", a:1, b:2, c:3 } }

      The type that shows up in the constructor (Bar in this case) can be an interface or an abstract class.

    • bindJSON

      <T> T bindJSON(Type genericType, Class<T> erasure, Object json)
      Data-bind from one of the JSON object types (JSONObject, JSONArray, String, Integer, and so on) to the expected type given as an argument.
      Parameters:
      genericType - The generic type of the 'erasure' parameter.
      erasure - The expected type to convert the JSON argument to.
      json - One of the JSON value type.

    • bindJSON

      void bindJSON(Object bean, net.sf.json.JSONObject src)
      Data-binds from JSONObject to the given object.

      This method is bit like bindJSON(Class, JSONObject), except that this method populates an existing object, instead of creating a new instance.

      This method is also bit like bindParameters(Object, String), in that it populates an existing object from a form submission, except that this method obtains data from JSONObject thus more structured, whereas bindParameters(Object, String) uses the map structure of the form submission.

    • bindJSONToList

      <T> List<T> bindJSONToList(Class<T> type, Object src)
      Data-bind from either JSONObject or JSONArray to a list, by using bindJSON(Class, JSONObject) as the lower-level mechanism.

      If the source is JSONObject, the returned list will contain a single item. If it is JSONArray, each item will be bound. If it is null, then the list will be empty.

    • getBindInterceptor

      BindInterceptor getBindInterceptor()
      Gets the BindInterceptor set for this request.
      See Also:

    • setBindListener

      @Deprecated BindInterceptor setBindListener(BindInterceptor bindListener)
      Deprecated.
      Typo. Use setBindInterceptor(BindInterceptor)

    • setBindInterceptpr

      @Deprecated BindInterceptor setBindInterceptpr(BindInterceptor bindListener)
      Deprecated.
      Typo. Use setBindInterceptor(BindInterceptor)

    • setBindInterceptor

      BindInterceptor setBindInterceptor(BindInterceptor bindListener)

    • getSubmittedForm

      net.sf.json.JSONObject getSubmittedForm() throws jakarta.servlet.ServletException
      Gets the content of the structured form submission.
      Throws:
      jakarta.servlet.ServletException
      See Also:

    • getFileItem2

      org.apache.commons.fileupload2.core.FileItem getFileItem2(String name) throws jakarta.servlet.ServletException, IOException
      Obtains a commons-fileupload2 object that represents an uploaded file.
      Returns:
      null if a file of the given form field name doesn't exist. This includes the case where the name corresponds to a simple form field (like textbox, checkbox, etc.)
      Throws:
      jakarta.servlet.ServletException
      IOException

    • getFileItem

      @Deprecated FileItem getFileItem(String name) throws jakarta.servlet.ServletException, IOException
      Deprecated.
      use getFileItem2(String)
      Obtains a commons-fileupload object that represents an uploaded file.
      Returns:
      null if a file of the given form field name doesn't exist. This includes the case where the name corresponds to a simple form field (like textbox, checkbox, etc.)
      Throws:
      jakarta.servlet.ServletException
      IOException

    • isJavaScriptProxyCall

      boolean isJavaScriptProxyCall()
      Returns true if this request represents a server method call to a JavaScript proxy object.

    • getBoundObjectTable

      BoundObjectTable getBoundObjectTable()
      Short cut for obtaining BoundObjectTable associated with this webapp.

    • createJavaScriptProxy

      @Deprecated String createJavaScriptProxy(Object toBeExported)
      Deprecated.
      Use createJavaScriptProxyParameters(Object) and invoke makeStaplerProxy yourself.
      Exports the given Java object as a JavaScript proxy and returns a JavaScript expression to create a proxy on the client side. Short cut for getBoundObjectTable().bind(toBeExported).getProxyScript()

    • createJavaScriptProxyParameters

      StaplerRequest2.RenderOnDemandParameters createJavaScriptProxyParameters(Object toBeExported)
      Exports the given Java object as a JavaScript proxy and returns the parameters needed to call makeStaplerProxy.