Routing Requests

Let’s look at some real-world examples for the most common ways to process (part of) the path:

Traversing the model graph
- Getter: /log/… → Jenkins#getLog()
- Getter with argument: /job/foo/… → Hudson#getJob("foo")
- Dynamic getter: /job/foo/1/… → Job#getDynamic("1" …)
Rendering views
- Index view: /job/foo*/* → index.jelly of Job (or other TopLevelItem implementations)
- Named view: /job/foo/changes → changes.jelly of Job
Action methods
- Action method
  - /job/foo/1/artifact → Run#doArtifact(…)
  - /job.foo/config.xml → @WebMethod("config.xml") doConfigDotXml(…)
- Index action method
  - /search → Search#doIndex(…)

Additionally, objects can implement several interfaces to further control how Stapler processes URLs:

org.kohsuke.stapler.StaplerProxy allows delegating the processing of a URL to another object. So, for /foo/bar, if getFoo() returns an object x that implements StaplerProxy’s `getTarget() method, Stapler will call x.getTarget() and continue using that to process the rest of the URL (bar). This has the highest priority among all possible URL processing options. getTarget() may also return this, for example to implement permission checks: No getters or views of x will be available to anyone who doesn’t have the necessary permissions via URLs.
org.kohsuke.stapler.StaplerOverridable is an interface allowing designated objects to selectively override URL mappings. If the designated override objects do not have a handler for the request, the host object (that implements StaplerOverridable) will handle the request.
org.kohsuke.stapler.StaplerFallback allows delegating the processing of a URL to another object, similar to StaplerProxy, but has the lowest priority among all possible URL processing options.

For more information on how Stapler binds (or staples) a Java Object Model to a URL hierarchy, see the Stapler Reference Documentation.

Since Jenkins 2.138.4 and 2.154, Jenkins places restrictions not inherent to Stapler on which methods and fields are eligible for routing. Learn more

Debugging hints

The following static fields can be set to true (e.g. via Script Console) while Jenkins is running to enable various debugging aids:

org.kohsuke.stapler.Dispatcher.TRACE: Stapler responses will include X-Stapler-Trace-… headers that explain how the corresponding request was routed. Additionally, the 404 error page will also include this information, as well as alternative routes for the last path component (which resulted in the 404 error). The corresponding Java system property is stapler.trace. This is enabled by default if Jenkins is run using mvn -pl war jetty:run (core) or mvn hpi:run (plugins).
org.kohsuke.stapler.Dispatcher.TRACE_PER_REQUEST: As above, but only for requests that have the X-Stapler-Trace header. The corresponding Java system property is stapler.trace.per-request.