{title:'Path Patterns', updated:'9.0.0'}

The {@link oajr.annotation.RestOp#path() @RestOp(path)} annotation allows you to define URL path patterns to match against. These patterns can contain variables of the form "{xxx}" that can be passed in directly to the Java methods as extra parameters.

In the following example, 3 separate GET request handlers are defined with different path patterns. Note how the variables are passed in as additional arguments on the method, and how those arguments are automatically converted to the specified class type...

| // Default method | @RestGet(path="/*") | public void doGetDefault() { | ... | } | | // Method with path pattern | @RestGet(path="/xxx") | public void doGetNoArgs(...) { | ... | } | | // Method with path pattern with arguments | @RestGet(path="/xxx/{foo}/{bar}/{baz}/{bing}") | public void doGetWithArgs( | @Path("foo") String foo, | @Path("bar") int bar, | @Path("baz") MyEnum baz, | @Path("bing") UUID qux | ) { | ... | }

By default, path patterns are matched using a best-match heuristic. When overlaps occur, URLs are matched from most-specific to most-general order:

| // Try first | @RestGet("/foo/bar") | public void method1() { | ... | } | | // Try second | @RestGet("/foo/{bar}") | public void method2(...) { | ... | } | | // Try third | @RestGet("/foo/*") | public void method3(...) { | ... | } | | // Try last | @RestGet("/*") | public void method4(...) { | ... | }

Paths that end with "/*" will do a prefix match on the incoming URL. Any remainder after the match can be accessed through {@link oajr.httppart.RequestPathParams#getRemainder()} or parameters with the @Path("/*") annotation. On the other hand, paths that don't end with "/*" (e.g. "/" or "/foo") will require an exact URL match, and if any remainder exists, a 404 (not found) error will be thrown.

The following example shows the distinction.

| @RestGet("/*") | public void doGet(@Path("/*") String remainder) { | // URL path pattern can have remainder accessible through req.getRemainder(). | } | | @RestPut("/") | public void doPut() { | // URL path pattern must match exactly and will cause a 404 error if a remainder exists. | }