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 |