This proposal has been deferred. The motivation stems simplifying (manual) development of resource handlers. Current work is focused on model-driven resources (Zero Resource Model), which encourages a more structured set of collection/member URIs -- such as in the current implementation. We'll defer this proposal until we see how ZRM plays out.
Proposal: A new URI mapping file that will provide more options when designing RESTful resources
Currently, programmers can create hierarchical resources in Zero using .bnd files. The .bnd syntax is a set of valid paths, one per line, with no variables:
blogs/posts
posts
There is one .bnd file for each resource that is not a
top-level resource (it is not at the root of the resource hierarchy). Authors of .bnd files may reference any resource type that is included in their application in the first N - 1 segments of a .bnd path, but the last segment must always be the resource for which the file is named (e.g., entries in
posts.bnd must always end in
/posts).
In this system, variables (named groups) are limited to those values that come between resource names and any data that is leftover after the last resource name has been identified. These values are identified as
{resource}Id and
event.pathInfo, respectively. The user cannot change these names or create additional variables in more complex URI patterns.
Our proposal is to replace .bnd files with a file named
uri.mappings. Like .bnd files, the uri.mapping file will contain one path per line; unlike .bnd files, there is a new (but familiar) syntax for describing the URI patterns.
The new URI syntax is just like the selector syntax that is found in zero.config files. The resource that will handle the request is the one whose name is the last non-optional segment of the URI; for example, a URI pattern of blogs/{blogName}/posts[/{postID}] would go to
posts.groovy or
posts.php because
posts is the last required segment.
Optional parts of a URI are marked with square brackets (
[]), restrictions on type are done with
:type, and the pipe (
|) can be used to match anything at the end of a URI (more info on the selector syntax is available
here).
Most importantly, programmers now have control over what their variables are named, how many variables they have, and where they are located. This is best illustrated through examples:
/blogs[/{blogName}]
/blogs/{blogName}/posts[/{postID}]
/posts[/{postID}]
/blogs/{blogName}/posts/{postID}/comments[/{commentNumber}]
The examples below show the use of multiple optional parts, arbitrary prefixes and suffixes, and type restrictions:
/blogger/{userName}/blogs[/{theBlog}]
/blogs[/{blogName}[/archives/{year:digit}/{month:digit}]]
/file_shares/{userID}|
Each Zero component may have its own uri.mappings file, so there will never be a monolithic file that must be updated as new dependencies are added. Our code looks through each dependency's uri.mappings file until it finds a match; this is similar to how .bnd file processing is done today, except there is one file per dependency rather than N.
Trying the new code
If you wish to try this new take on URI definitions, follow these steps:
- Add the following dependency to your project's ivy.xml file: zero:zero.core.trial (1.0.0)
- Download the upgrade tool from SVN: https://www.projectzero.org/svn/zero/trunk/CORE/zero.core.trial/upgrade-tool.jar
- Run the tool like so: java -jar upgrade-tool.jar. You can also double-click on the JAR. The default behavior is to convert your .bnd files to uri.mapping, leaving the old .bnd files in place. Run the tool with the -help flag for more options.
- If any of your resources use event.pathInfo, you will need to go into the uri.mapping file and add the | character manually.
-- danjemiolo - 06 Sep 2007
