Routing Engine

Orb provides a routing engine that enables associating a class with a path to dynamically respond to web requests using Jade methods. The class must implement the IOrbRoute interface, which specifies the execute and render methods (for details, see "IOrbRoute Interface", elsewhere in this document).

When a request is received by an Orb application, if there is a class associated with the HTTP request method and path, a transient instance of that class is created. Properties of the class are populated with data from the query string or HTTP POST data. The execute method on the instance is called, and the Integer result is passed to the render method. The Binary result of the render method is sent to the requesting web browser. After the request is finished, the transient instance of the route class is deleted.

Orb API methods can be called in the execute and render methods to retrieve information about the request, or to affect the response that is sent to the requesting browser.

The execute and render methods can also perform any operations or logic relevant to your system.

The return value of the render method is typically the result of expanding a template, with the bind method and related methods.

A route can be associated with a class using the addRoute method, for example:

addRoute("GET", "/", MainRoute);

This adds a route that responds to GET requests for the root "/" path. When a browser requests this path, an instance of MainRoute is created, its execute method called, the render method called, the result sent to the browser, and then the instance is deleted.

The following is another example of using the addRoute method to associate a route with a class.

addRoute("GET", "/accounts", AccountsRoute);

The methods on AccountsRoute could be as follows.

execute(): Integer updating;
vars
   user : UserAccount;
begin
   if not Orb@sessionData(user) then
       return Failure;
   endif;
   self.userAccount := user;
   return Success;
end;
render(executeResult: Integer): Binary;
begin
   switch executeResult do
      case Success:   return Orb@bind("accounts", self.userAccount);
      case Failure:   return Orb@redirect("/login");
      default:        return Orb@bind("error", null);
   endswitch;
end;

In this example, when the /accounts path is requested by a browser, an instance of the AccountsRoute class is created.

The execute method is called, it checks if the requesting browser has an active session, and if not, it returns a constant value representing Failure. Otherwise, it saves a reference to the session data object to a reference on the AccountsRoute instance, and returns a constant value representing Success.

The result returned by the execute method is passed to the render method. If the result is: