URL Dispatching

Owned by John Ousterhout
Last updated: Jul 08, 2009Version comment
4 min read

When an HTTP request arrives at the Tomcat server containing a Fiz application, it can be handled in one of three ways, described in the sections below.

Interactor method invocation

In the most common case, Fiz intercepts the request and dispatches it to a method in an interactor class in the application, based on the URL in the request; the method then generates a response to the request, such as an HTML page. Fiz currently uses a very simple mechanism where URLs are expected to have the following form:

http://www.mycompany.com/class/method

The class field selects an interactor class and must start with a lower-case letter: if class is xyz then Fiz will look for a Java class named XyzInteractor; this class must be a subclass of Interactor. There must be a public method in the selected class named method, and it must take a single argument that is a subclass of ClientRequest. Thus, for example, the URL http://www.mycompany.com/blog/create will be dispatched to a method named create in a class named BlogInteractor. This method is called an entry method, since it provides the top-level entry point into the application's code.

Fiz will create an instance of an Interactor class during the first request that references that class; the instance is retained by Fiz and used for all future requests for the class. Fiz also invokes the init method in the Interactor class immediately after creating an instance and before invoking the first entry method. Fiz creates a ClientRequest object that includes all of the information about the incoming request (and the eventual response) and passes it to the entry method.

Note: any public method of an Interactor that takes a single ClientRequest argument is exposed to the public, in that it can be invoked directly by anyone on the Internet who can reach your Web server with an HTTP request. Thus, all of your entry methods should not carry out any sensitive actions without first performing appropriate permissions checks.

Static objects

The mechanism above is used for pages and other objects that are generated dynamically. However, an application typically includes many objects that are static, such as images and Javascript files. These objects are referenced with URLs like the following:

http://www.mycompany.com/static/fiz/images/folder.gif

The first name in the hierarchical portion of the URL must be static to indicate that this is a static object. The object in the example above will be read from the file static/fiz/images/folder.gif in the directory for the application.

Static entry methods

Fiz also supports a second method of dispatching to a method. This approach is provided so that sections can handle incoming requests directly, without any involvement by an interactor (typically the requests are Ajax requests to update the section). The URL for this form of dispatching has the same form as for interactor method invocation above:

http://www.mycompany.com/class/method

However, in this case class is the full name of a Java class and must start with a capital letter. Fiz looks up class, searches for a static method in the class named method and taking a single ClientRequest argument, and invokes that method. For example, the URL http://www.mycompany.com/TreeSection/ajaxExpand will invoke the method ajaxExpand in the class TreeSection.

Although this approach is intended primarily for use by sections handling private Ajax requests, it can be used to invoke any static method in any class, as long as that method takes a single ClientRequest argument. In order to minimize the security risks associated with this exposure, the class must indicate its willingness to accept incoming requests by implementing the DirectAjax interface (there are no methods in this interface; all that's needed is the implements DirectAjax declaration in the class declaration for the class.

Additional URL information

URLs that Fiz dispatches to an entry method may contain additional information after the class and method names. Additional fields in the hierarchical portion of the URL are ignored by Fiz and may be parsed by the application if it wishes. Query values in the URL are parsed automatically by Fiz and included in the main dataset for the request. For example, consider the following URL

http://www.mycompany.com/blog/view/994?userid=casey

Fiz will use the blog/view portion of the URL to dispatch to the entry method view in class BlogInteractor. It will create an entry in the main dataset with name userid and value casey. Fiz will ignore the /994 portion of the URL; the entry method can retrieve the URL from the ClientRequest object (cr.getServletRequest.getPathInfo) if it wishes to use this information.

Limitations

The Fiz dispatching mechanism currently has the following limitations:

  • URLs must have one of the forms defined above: Fiz doesn't currently support customized URL forms such as those provided by routes in Ruby on Rails.
  • Fiz applications normally run as root Tomcat applications: URLs have the form /class/method, not /appName/class/method. This means it isn't possible for a single Tomcat server to support multiple Fiz applications. It is possible for you to add an application-specific prefix on all the URLs for your application, which would allow multiple applications to share a single Tomcat server, but Fiz does not provide any particular support for this: your application will need to make sure all of its URLs have the correct form.