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
ofjob
(or otherTopLevelItem
implementations) -
Named view:
/job/foo/changes
→changes.jelly
ofJob
-
-
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:
-
staplerdoc:org.kohsuke.stapler.StaplerProxy
allows delegating the processing of a URL to another object. So, for/foo/bar
, ifgetFoo()
returns an objectx
that implementsStaplerProxy’s `getTarget()
method, Stapler will callx.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 returnthis
, for example to implement permission checks: No getters or views ofx
will be available to anyone who doesn’t have the necessary permissions via URLs. -
staplerdoc: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 implementsStaplerOverridable
) will handle the request. -
staplerdoc:org.kohsuke.stapler.StaplerFallback
allows delegating the processing of a URL to another object, similar toStaplerProxy
, 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 isstapler.trace
. This is enabled by default if Jenkins is run usingmvn -pl war jetty:run
(core) ormvn 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 isstapler.trace.per-request
.