ERXRouteRequestHandler (Project Wonder Reference Documentation)

java.lang.Object
- com.webobjects.appserver.WORequestHandler
- - com.webobjects.appserver._private.WOActionRequestHandler
  - - com.webobjects.appserver._private.WODirectActionRequestHandler
    - - er.rest.routes.ERXRouteRequestHandler

public class ERXRouteRequestHandler
extends com.webobjects.appserver._private.WODirectActionRequestHandler

ERXRouteRequestHandler is the request handler that can process rails-style route mappings and convert them to ERXRestController action methods. in Application:

 ERXRouteRequestHandler routeRequestHandler = new ERXRouteRequestHandler();
 routeRequestHandler.addDefaultRoutes(Person.ENTITY_NAME);
 ERXRouteRequestHandler.register(routeRequestHandler);

 ERXRouteRequestHandler routeRequestHandler = new ERXRouteRequestHandler();
 routeRequestHandler.addRoute(new ERXRoute("/people/{action}", PeopleController.class));
 routeRequestHandler.addRoute(new ERXRoute("/person/{person:Person}", PeopleController.class, "show"));
 ...
 ERXRouteRequestHandler.register(routeRequestHandler);

Note that addDefaultRoutes sets up many routes automatically (not just the 2 that are shown above), and for most cases should be your starting point for adding new entities rather than manually adding them. in PeopleController:

 public class PeopleController extends ERXRouteController {
        public PeopleController(WORequest request) {
                super(request);
        }
 
        public Person person() {
                Person person = (Person) routeObjectForKey("person");
                return person;
        }
 
        public ERXKeyFilter showFilter() {
                ERXKeyFilter filter = ERXKeyFilter.filterWithAttributes();
                filter.include(Person.COMPANY).includeAttributes();
                return filter;
        }
 
        public ERXKeyFilter updateFilter() {
                ERXKeyFilter filter = ERXKeyFilter.filterWithAttributes();
                filter.include(Person.COMPANY);
                return filter;
        }
 
        public WOActionResults createAction() {
                Person person = (Person) create(Person.ENTITY_NAME, updateFilter());
                editingContext().saveChanges();
                return response(person, showFilter());
        }
 
        public WOActionResults updateAction() {
                Person person = person();
                update(person, updateFilter());
                editingContext().saveChanges();
                return response(person, showFilter());
        }
 
        public WOActionResults showAction() {
                return response(person(), showFilter());
        }
 
        public WOActionResults indexAction() {
                NSArray<Person> people = Person.fetchPersons(editingContext(), null, Person.LAST_NAME.asc().then(Person.FIRST_NAME.asc()));
                return response(editingContext(), Person.ENTITY_NAME, people, showFilter());
        }
 }

in browser:

 http://localhost/cgi-bin/WebObjects/YourApp.woa/ra/people.xml
 http://localhost/cgi-bin/WebObjects/YourApp.woa/ra/people.json
 http://localhost/cgi-bin/WebObjects/YourApp.woa/ra/people.plist
 http://localhost/cgi-bin/WebObjects/YourApp.woa/ra/person/100.json
 http://localhost/cgi-bin/WebObjects/YourApp.woa/ra/person/100/edit.json

Author:: mschrag

Properties
Name	Description
`ERXRest.missingControllerName`	(default "ERXMissingRouteController") Allow you to specify which controller to use when a route doesn't exist
`ERXRest.parseUnknownExtensions`	(default "true") If set to "false", will return a 404 status code if the format doesn't exist
`ERXRest.pluralEntityNames`	ERXRest.pluralEntityNames
`ERXRest.routeCase`	ERXRest.routeCase
`ERXRest.lowercaseEntityNames`	ERXRest.lowercaseEntityNames

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class ERXRouteRequestHandler.NameFormat
NameFormat specifies how routes and controller names should be capitalized by default.

Nested Classes
Modifier and Type	Class and Description
`static class`	`ERXRouteRequestHandler.NameFormat` NameFormat specifies how routes and controller names should be capitalized by default.

Field Summary

Fields
Modifier and Type	Field and Description
`static ERXRouteRequestHandler.NameFormat`	`EMBER`
`static String`	`ExtensionKey`
`static String`	`Key`
`static String`	`KeysKey`
`static String`	`PathKey`
`static ERXRouteRequestHandler.NameFormat`	`RAILS` A NameFormat that behaves like Rails -- plural entities, plural routes, lowercase underscore names (names_like_this).
`static String`	`RouteKey`
`static String`	`TypeKey`
`static ERXRouteRequestHandler.NameFormat`	`WO` A NameFormat that behaves like WO -- singular entities, singular routes, camel names (NamesLikeThis).
`static ERXRouteRequestHandler.NameFormat`	`WO_LOWER` A NameFormat that behaves like WO -- singular entities, singular routes, lowercase camel names (namesLikeThis).

Fields inherited from class com.webobjects.appserver._private.WOActionRequestHandler
actionClassClass, actionClassName, CLASS_NOT_FOUND, defaultActionName, INSTANTIATION, INVALID_PATH, INVOCATION, shouldAddToStatistics

Fields inherited from class com.webobjects.appserver.WORequestHandler
DidHandleRequestNotification

Constructor Summary

Constructors
Constructor and Description
`ERXRouteRequestHandler()` Constructs a new ERXRouteRequestHandler with the default entity name format.
`ERXRouteRequestHandler(ERXRouteRequestHandler.NameFormat entityNameFormat)` Constructs a new ERXRouteRequestHandler.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`_clearCaches()` Clears any caches that may exist on ERXRoutes (probably only useful to JRebel, to clear the route parameter method cache).
`void`	`_putComponentsToSleepInContext(WOContext wocontext)`
`protected void`	`addDeclaredRoutes(String entityName, Class<? extends ERXRouteController> routeControllerClass, boolean addDefaultRoutesIfNoDeclaredRoutesFound)`
`void`	`addDefaultRoutes(String entityName)` Adds default routes and maps them to a controller named "[plural entity name]Controller".
`void`	`addDefaultRoutes(String entityName, boolean numericPKs, Class<? extends ERXRouteController> controllerClass)` Adds list and view routes for the given entity.
`void`	`addDefaultRoutes(String entityName, Class<? extends ERXRouteController> controllerClass)` Adds list and view routes for the given entity.
`void`	`addDefaultRoutes(String entityName, String entityType, boolean numericPKs, Class<? extends ERXRouteController> controllerClass)` Adds list and view routes for the given entity.
`void`	`addRoute(ERXRoute route)` Adds a new route to this request handler.
`void`	`addRoutes(Class<? extends ERXRouteController> routeControllerClass)` This method looks for all methods annotated with @Path or @Paths annotations and adds the corresponding routes.
`void`	`addRoutes(String entityName)` Calls the static method 'addRoutes(entityName, routeRequetHandler)' on the route controller for the given entity name, giving it the opportunity to add routes for this entity.
`void`	`addRoutes(String entityName, Class<? extends ERXRouteController> routeControllerClass)` Calls the static method 'addRoutes(entityName, routeRequetHandler)' on the given route controller class, giving it the opportunity to add routes for the given entity.
`<T extends ERXRouteController> T`	`controller(Class<T> controllerClass, WOContext context)` Returns the corresponding controller instance (with no request specified).
`<T extends ERXRouteController> T`	`controller(Class<T> controllerClass, WORequest request, WOContext context)` Returns the corresponding controller instance.
`<T extends ERXRouteController> T`	`controller(String entityName, WORequest request, WOContext context)` Returns the corresponding controller instance.
`String`	`controllerPathForEntityNamed(String entityName)` Return the controller path name for an entity name based on the entity name format.
`WOAction`	`getActionInstance(Class class1, Class[] aclass, Object[] aobj)`
`Object[]`	`getRequestActionClassAndNameForPath(NSArray requestHandlerPath)`
`NSArray<String>`	`getRequestHandlerPathForRequest(WORequest request)`
`void`	`insertRoute(ERXRoute route)` Inserts a route at the beginning of the route list.
`static void`	`register(ERXRouteRequestHandler requestHandler)` Registers an ERXRestRequestHandler with the WOApplication for the handler key "rest".
`void`	`removeRoute(ERXRoute route)` Removes the given route from this request handler.
`Class<? extends ERXRouteController>`	`routeControllerClassForEntityNamed(String entityName)` Returns the default route controller class for the given entity name.
`ERXRoute`	`routeForMethodAndPath(String method, String path, NSMutableDictionary<String,Object> userInfo)` Returns the route that matches the request method and path, storing metadata about the route in the given userInfo dictionary.
`protected ERXRoute`	`routeForMethodAndPattern(ERXRoute.Method method, String urlPattern)`
`NSArray<ERXRoute>`	`routes()` Returns the routes for this request handler.
`NSArray<ERXRoute>`	`routesForControllerClass(Class<? extends ERXRouteController> routeController)` Returns the routes for the given controller class.
`ERXRoute`	`setupRequestWithRouteForMethodAndPath(WORequest request, String method, String path)` Sets up the request userInfo for the given request for a request of the given method and path.
`void`	`setupRouteControllerFromUserInfo(ERXRouteController controller, NSDictionary<String,Object> userInfo)` Sets up a route controller based on a request userInfo that came from routeForMethodAndPath.
`protected void`	`verifyRoute(ERXRoute route)` Checks for an existing route that matches the `ERXRoute.Method` and `ERXRoute.routePattern()` of `route` and yet has a different controller or action mapping.

Methods inherited from class com.webobjects.appserver._private.WODirectActionRequestHandler
allowsContentInputStream, defaultActionClassName, generateErrorResponse, generateRequestRefusal, handler, nullResponse, registerDidHandleActionRequestWithActionNamed, registerWillHandleActionRequest, setAllowsContentInputStream

Methods inherited from class com.webobjects.appserver._private.WOActionRequestHandler
_actionClassForName, _handleRequest, defaultDefaultActionName, defaultShouldAddToStatistics, handleRequest, isSessionIDInRequest, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - RAILS
```
public static ERXRouteRequestHandler.NameFormat RAILS
```
    A NameFormat that behaves like Rails -- plural entities, plural routes, lowercase underscore names (names_like_this).
  - WO
```
public static ERXRouteRequestHandler.NameFormat WO
```
    A NameFormat that behaves like WO -- singular entities, singular routes, camel names (NamesLikeThis).
  - WO_LOWER
```
public static ERXRouteRequestHandler.NameFormat WO_LOWER
```
    A NameFormat that behaves like WO -- singular entities, singular routes, lowercase camel names (namesLikeThis).
  - EMBER
```
public static ERXRouteRequestHandler.NameFormat EMBER
```
  - Key
```
public static final String Key
```
    See Also:
    
    Constant Field Values
  - TypeKey
```
public static final String TypeKey
```
    See Also:
    
    Constant Field Values
  - ExtensionKey
```
public static final String ExtensionKey
```
    See Also:
    
    Constant Field Values
  - PathKey
```
public static final String PathKey
```
    See Also:
    
    Constant Field Values
  - RouteKey
```
public static final String RouteKey
```
    See Also:
    
    Constant Field Values
  - KeysKey
```
public static final String KeysKey
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - ERXRouteRequestHandler
```
public ERXRouteRequestHandler()
```
    Constructs a new ERXRouteRequestHandler with the default entity name format.
  - ERXRouteRequestHandler
```
public ERXRouteRequestHandler(ERXRouteRequestHandler.NameFormat entityNameFormat)
```
    Constructs a new ERXRouteRequestHandler.
    
    Parameters:
    
    entityNameFormat - the format to use for entity names in URLs
- Method Detail
  - insertRoute
```
public void insertRoute(ERXRoute route)
```
    Inserts a route at the beginning of the route list.
    
    Parameters:
    
    route - the route to insert
  - addRoute
```
public void addRoute(ERXRoute route)
```
    Adds a new route to this request handler.
    
    Parameters:
    
    route - the route to add
  - removeRoute
```
public void removeRoute(ERXRoute route)
```
    Removes the given route from this request handler.
    
    Parameters:
    
    route - the route to remove
  - _clearCaches
```
public void _clearCaches()
```
    Clears any caches that may exist on ERXRoutes (probably only useful to JRebel, to clear the route parameter method cache).
  - routes
```
public NSArray<ERXRoute> routes()
```
    Returns the routes for this request handler.
    
    Returns:
    
    the routes for this request handler.
  - routesForControllerClass
```
public NSArray<ERXRoute> routesForControllerClass(Class<? extends ERXRouteController> routeController)
```
    Returns the routes for the given controller class.
    
    Parameters:
    
    routeController - the controller class
    
    Returns:
    
    the routes for the given controller class
  - routeControllerClassForEntityNamed
```
public Class<? extends ERXRouteController> routeControllerClassForEntityNamed(String entityName)
```
    Returns the default route controller class for the given entity name.
    
    Parameters:
    
    entityName - the name of the entity
    
    Returns:
    
    the corresponding route controller
  - addRoutes
```
public void addRoutes(String entityName)
```
    Calls the static method 'addRoutes(entityName, routeRequetHandler)' on the route controller for the given entity name, giving it the opportunity to add routes for this entity. Additionally, this method looks for all methods annotated with @Path or @Paths annotations and adds the corresponding routes. If no addRoutes method is found and no @Path annotated methods exist, it will log a warning and add default routes instead.
    
    Parameters:
    
    entityName - the name of the entity
  - addRoutes
```
public void addRoutes(String entityName,
                      Class<? extends ERXRouteController> routeControllerClass)
```
    Calls the static method 'addRoutes(entityName, routeRequetHandler)' on the given route controller class, giving it the opportunity to add routes for the given entity. Additionally, this method looks for all methods annotated with @Path or @Paths annotations and adds the corresponding routes. If no addRoutes method is found and no @Path annotated methods exist, it will log a warning and add default routes instead.
    
    Parameters:
    
    entityName - the name of the entity
    
    routeControllerClass - the name of the route controller
  - addRoutes
```
public void addRoutes(Class<? extends ERXRouteController> routeControllerClass)
```
    This method looks for all methods annotated with @Path or @Paths annotations and adds the corresponding routes. If no addRoutes method is found and no @Path annotated methods exist, it will log a warning and add default routes instead. This is the variant to use if you have a controller that has no logical entity associated with it.
    
    Parameters:
    
    routeControllerClass - the name of the route controller
  - addDeclaredRoutes
```
protected void addDeclaredRoutes(String entityName,
                                 Class<? extends ERXRouteController> routeControllerClass,
                                 boolean addDefaultRoutesIfNoDeclaredRoutesFound)
```
  - addDefaultRoutes
```
public void addDefaultRoutes(String entityName)
```
    Adds default routes and maps them to a controller named "[plural entity name]Controller". For instance, if the entity name is "Person" it would make a controller named "PeopleController".
    
    Parameters:
    
    entityName - the name of the entity to create routes for
  - addDefaultRoutes
```
public void addDefaultRoutes(String entityName,
                             Class<? extends ERXRouteController> controllerClass)
```
    Adds list and view routes for the given entity. For instance, if you provide the entity name "Reminder" you will get the routes:
```
 /reminders
 /reminders/{action}
 /reminder/{reminder:Reminder}
 /reminder/{reminder:Reminder}/{action}
 
```
    Parameters:
    
    entityName - the entity name to route with
    
    controllerClass - the controller class
  - controllerPathForEntityNamed
```
public String controllerPathForEntityNamed(String entityName)
```
    Return the controller path name for an entity name based on the entity name format.
    
    Parameters:
    
    entityName - the entity name
    
    Returns:
    
    the controller identifier part of the path (the "companies" part in "/companies/1000");
  - addDefaultRoutes
```
public void addDefaultRoutes(String entityName,
                             boolean numericPKs,
                             Class<? extends ERXRouteController> controllerClass)
```
    Adds list and view routes for the given entity. For instance, if you provide the entity name "Reminder" you will get the routes:
```
 /reminders
 /reminders/{action}
 /reminder/{reminder:Reminder}
 /reminder/{reminder:Reminder}/{action}
 
```
    Parameters:
    
    entityName - the entity name to route with
    
    numericPKs - if true, routes can assume numeric PK's and add some extra convenience routes
    
    controllerClass - the controller class
  - addDefaultRoutes
```
public void addDefaultRoutes(String entityName,
                             String entityType,
                             boolean numericPKs,
                             Class<? extends ERXRouteController> controllerClass)
```
    Adds list and view routes for the given entity. For instance, if you provide the entity name "Reminder" you will get the routes:
```
 /reminders
 /reminders/{action}
 /reminder/{reminder:Reminder}
 /reminder/{reminder:Reminder}/{action}
 
```
    Parameters:
    
    entityName - the entity name to route with
    
    entityType - the type of the enity
    
    numericPKs - if true, routes can assume numeric PK's and add some extra convenience routes
    
    controllerClass - the controller class
  - routeForMethodAndPath
```
public ERXRoute routeForMethodAndPath(String method,
                                      String path,
                                      NSMutableDictionary<String,Object> userInfo)
```
    Returns the route that matches the request method and path, storing metadata about the route in the given userInfo dictionary.
    
    Parameters:
    
    method - the request method
    
    path - the request path
    
    userInfo - a mutable userInfo
    
    Returns:
    
    the matching route (or null if one is not found)
  - routeForMethodAndPattern
```
protected ERXRoute routeForMethodAndPattern(ERXRoute.Method method,
                                            String urlPattern)
```
    Parameters:
    
    method - the request method
    
    urlPattern -
    
    Returns:
    
    the first route matching method and pattern.
  - verifyRoute
```
protected void verifyRoute(ERXRoute route)
```
    Checks for an existing route that matches the ERXRoute.Method and ERXRoute.routePattern() of route and yet has a different controller or action mapping.
    
    Parameters:
    
    route -
  - setupRequestWithRouteForMethodAndPath
```
public ERXRoute setupRequestWithRouteForMethodAndPath(WORequest request,
                                                      String method,
                                                      String path)
```
    Sets up the request userInfo for the given request for a request of the given method and path.
    
    Parameters:
    
    request - the request to configure the userInfo on
    
    method - the request method
    
    path - the request path
    
    Returns:
    
    the matching route for this method and path
  - setupRouteControllerFromUserInfo
```
public void setupRouteControllerFromUserInfo(ERXRouteController controller,
                                             NSDictionary<String,Object> userInfo)
```
    Sets up a route controller based on a request userInfo that came from routeForMethodAndPath.
    
    Parameters:
    
    controller - the controller to setup
    
    userInfo - the request userInfo
  - getRequestHandlerPathForRequest
```
public NSArray<String> getRequestHandlerPathForRequest(WORequest request)
```
    Overrides:
    
    getRequestHandlerPathForRequest in class com.webobjects.appserver._private.WODirectActionRequestHandler
  - getRequestActionClassAndNameForPath
```
public Object[] getRequestActionClassAndNameForPath(NSArray requestHandlerPath)
```
    Overrides:
    
    getRequestActionClassAndNameForPath in class com.webobjects.appserver._private.WOActionRequestHandler
  - getActionInstance
```
public WOAction getActionInstance(Class class1,
                                  Class[] aclass,
                                  Object[] aobj)
```
    Overrides:
    
    getActionInstance in class com.webobjects.appserver._private.WOActionRequestHandler
  - controller
```
public <T extends ERXRouteController> T controller(String entityName,
                                                   WORequest request,
                                                   WOContext context)
```
    Returns the corresponding controller instance.
    
    Type Parameters:
    
    T - the type of controller to return
    
    Parameters:
    
    entityName - the entity name of the controller to lookup
    
    request - the current request
    
    context - the current context
    
    Returns:
    
    the created controller
  - controller
```
public <T extends ERXRouteController> T controller(Class<T> controllerClass,
                                                   WOContext context)
```
    Returns the corresponding controller instance (with no request specified).
    
    Type Parameters:
    
    T - the type of controller to return
    
    Parameters:
    
    controllerClass - the controller class to lookup
    
    context - the current context
    
    Returns:
    
    the created controller
  - controller
```
public <T extends ERXRouteController> T controller(Class<T> controllerClass,
                                                   WORequest request,
                                                   WOContext context)
```
    Returns the corresponding controller instance.
    
    Type Parameters:
    
    T - the type of controller to return
    
    Parameters:
    
    controllerClass - the controller class to lookup
    
    request - the current request
    
    context - the current context
    
    Returns:
    
    the created controller
  - _putComponentsToSleepInContext
```
public void _putComponentsToSleepInContext(WOContext wocontext)
```
    Overrides:
    
    _putComponentsToSleepInContext in class com.webobjects.appserver._private.WOActionRequestHandler
  - register
```
public static void register(ERXRouteRequestHandler requestHandler)
```
    Registers an ERXRestRequestHandler with the WOApplication for the handler key "rest".
    
    Parameters:
    
    requestHandler - the rest request handler to register

Class ERXRouteRequestHandler

Nested Class Summary

Field Summary

Fields inherited from class com.webobjects.appserver._private.WOActionRequestHandler

Fields inherited from class com.webobjects.appserver.WORequestHandler

Constructor Summary

Method Summary

Methods inherited from class com.webobjects.appserver._private.WODirectActionRequestHandler

Methods inherited from class com.webobjects.appserver._private.WOActionRequestHandler

Methods inherited from class java.lang.Object

Field Detail

RAILS

WO

WO_LOWER

EMBER

Key

TypeKey

ExtensionKey

PathKey

RouteKey

KeysKey

Constructor Detail

ERXRouteRequestHandler

ERXRouteRequestHandler

Method Detail

insertRoute

addRoute

removeRoute

_clearCaches

routes

routesForControllerClass

routeControllerClassForEntityNamed

addRoutes

addRoutes

addRoutes

addDeclaredRoutes

addDefaultRoutes

addDefaultRoutes

controllerPathForEntityNamed

addDefaultRoutes

addDefaultRoutes

routeForMethodAndPath

routeForMethodAndPattern

verifyRoute

setupRequestWithRouteForMethodAndPath

setupRouteControllerFromUserInfo

getRequestHandlerPathForRequest

getRequestActionClassAndNameForPath

getActionInstance

controller

controller

controller

_putComponentsToSleepInContext

register