er.rest.routes

Class ERXRouteController

java.lang.Object

com.webobjects.appserver.WOAction

com.webobjects.appserver.WODirectAction

er.rest.routes.ERXRouteController

All Implemented Interfaces:

NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions, NSValidation

Direct Known Subclasses:

ERXDefaultRouteController, ERXMissingRouteController, ERXReadOnlyRouteController, SEController

public class ERXRouteController
extends WODirectAction

ERXRouteController is equivalent to a Rails controller class. It's actually a direct action, and has the same naming rules as a direct action, so your controller action methods must end in the name "Action". There are several utility methods for manipulating restful requests and responses (update(..), create(..), requestNode(), response(..), etc) , and it supports multiple formats for you.

Author:

mschrag

Properties

Name	Description
ERXRest.accessControlAllowRequestHeaders	See https://developer.mozilla.org/En/HTTP_access_control#Access-Control-Allow-Headers
ERXRest.accessControlAllowRequestMethods	See https://developer.mozilla.org/En/HTTP_access_control#Access-Control-Allow-Methods
ERXRest.defaultFormat	(default "xml") Allow you to set the default format for all of your REST controllers
ERXRest.strictMode	(default "true") If set to true, status code in the response will be 405 Not Allowed, if set to false, status code will be 404 Not Found
ERXRest.allowWindowNameCrossDomainTransport	ERXRest.allowWindowNameCrossDomainTransport
ERXRest.accessControlMaxAge	(default 1728000) This header indicates how long the results of a preflight request can be cached. See https://developer.mozilla.org/En/HTTP_access_control#Access-Control-Max-Age
ERXRest.accessControlAllowOrigin	Set the value to '*' to enable all origins. See https://developer.mozilla.org/En/HTTP_access_control#Access-Control-Allow-Origin

Nested Class Summary

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding._BooleanFieldBinding, NSKeyValueCoding._BooleanMethodBinding, NSKeyValueCoding._FieldBinding, NSKeyValueCoding._ForwardingBinding, NSKeyValueCoding._KeyBinding, NSKeyValueCoding._KeyBindingCreation, NSKeyValueCoding._MethodBinding, NSKeyValueCoding._NumberFieldBinding, NSKeyValueCoding._NumberMethodBinding, NSKeyValueCoding._ReflectionKeyBindingCreation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.MapImplementation, NSKeyValueCoding.Null<T>, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.ValueAccessor

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSValidation

NSValidation._MethodBinding, NSValidation._ValidationBinding, NSValidation.DefaultImplementation, NSValidation.Utility, NSValidation.ValidationException

Field Summary

Fields inherited from class com.webobjects.appserver.WODirectAction

actionText

Fields inherited from class com.webobjects.appserver.WOAction

_actionClasses, _context

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

_CLASS

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

_CLASS, _KeyPathSeparatorChar, KeyPathSeparator

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSValidation

_CLASS

Constructor Summary

Constructors

Constructor and Description
ERXRouteController(WORequest request) Constructs a new ERXRouteController.

Method Summary

Modifier and Type	Method and Description
protected boolean	_canSetHeaderForActionResults(WOActionResults results) Returns whether or not headers can be added to the given action results.
static NSMutableArray<ERXRouteController>	_controllersForRequest(WORequest request) Returns the controllers that have been used on the given request.
static void	_disposeControllersForRequest(WORequest request) Disposes all of the controllers that were used on the given request.
protected static void	_registerControllerForRequest(ERXRouteController controller, WORequest request) Registers the given controller with the given request, so it can be later disposed.
void	_setContext(WOContext context) WODirectAction doesn't expose API for setting the context, which can be useful for passing data between controller.
void	_setEditingContent(EOEditingContext ec)
void	_setEntityName(String entityName) Sets the entity name for this controller.
void	_setFormat(ERXRestFormat format) Sets the format that will be used by this route controller.
protected void	_setHeaderForActionResults(String value, String key, WOActionResults results) Attempt to set the header for the given results object.
void	_setRequestContent(ERXRestFormat format, String requestContent) Sets the request content that this controller will use for processing.
void	_setRequestContent(String requestContent) Sets the request content that this controller will use for processing -- this requires that a format() is specified.
void	_setRequestHandler(ERXRouteRequestHandler requestHandler) Sets the request handler that processed this route.
void	_setRequestNode(ERXRestRequestNode requestNode) Sets the request node that this controller will use for processing.
void	_setRoute(ERXRoute route) Sets the route that is associated with this request.
void	_setRouteKeys(NSDictionary<ERXRoute.Key,String> routeKeys) Sets the unprocessed keys from the route.
void	_setRouteObjects(NSDictionary<ERXRoute.Key,Object> objects) Sets the processed objects for the current route.
protected void	_takeRouteParametersFromRequest(WOActionResults results) Enumerates the route keys, looks for @ERXRouteParameter annotated methods, and sets the value of the routeKey with the corresponding method if it exists.
protected String	accessControlAllowOrigin() Returns the allowed origin for cross-site requests.
protected NSArray<String>	accessControlAllowRequestHeaders(NSArray<String> requestHeaders) Returns the allowed request headers given the requested headers.Set the property ERXRest.accessControlAllowRequestHeaders to override the default of just returning the requested headers.
protected NSArray<String>	accessControlAllowRequestMethods(String requestMethod) Returns the allowed request methods given the requested method.
protected long	accessControlMaxAage() Returns the maximum age in seconds for the preflight options cache.
protected boolean	allowJSONP() Returns whether or not JSONP (JSON with Padding) is allowed.
protected boolean	allowWindowNameCrossDomainTransport() Returns whether or not the window.name cross-domain transport is allowed.
protected void	checkAccess() Override to provide custom security checks.
boolean	containsRouteKey(String key) Returns whether or not there is a route key with the given name.
<T extends ERXRouteController> T	controller(Class<T> controllerClass) Returns another controller, passing the required state on.
<T extends ERXRouteController> T	controller(String entityName) Returns another controller, passing the required state on.
<T> T	create(ERXKeyFilter filter) Creates a new object from the request data that is of the routed entity name and is filtered with the given filter.
<T> T	create(ERXKeyFilter filter, ERXRestContext restContext) Creates a new object from the request data that is of the routed entity name and is filtered with the given filter.
<T> T	create(String entityName, ERXKeyFilter filter) Creates a new object from the request data that is of the given entity name and is filtered with the given filter.
<T> T	create(String entityName, ERXKeyFilter filter, ERXRestContext restContext) Creates a new object from the request data that is of the given entity name and is filtered with the given filter.
protected ERXRestContext	createRestContext() Creates a new rest context for the controller.
protected ERXRestFormat	defaultFormat() Returns the default format to use if no other format is found, or if the requested format is invalid.
void	dispose() Disposes any resources the route controller may be holding onto (like its editing context).
EOEditingContext	editingContext() The controller maintains an editing context for the duration of the request.
protected String	entityName() Returns the name of the entity that this controller is currently handling.
WOActionResults	errorResponse(int status) Returns an error response with the given HTTP status and without any body content
WOActionResults	errorResponse(String errorMessage, int status) Returns an error response with the given HTTP status.
WOActionResults	errorResponse(Throwable t, int status) Returns an error response with the given HTTP status.
ERXRestFormat	format() Returns the format that the user requested (usually based on the request file extension).
protected ERXRestFormat.Delegate	formatDelegateForFormat(ERXRestFormat format) Returns the default format delegate to use for the given format (defaults to format.delegate()).
protected ERXRestFormat	formatNamed(String type) Returns the format to use for the given type (see ERXRestFormat constants).
WOActionResults	headAction() Returns the response from a HEAD call to this controller.
protected ERXKeyFilter	includeOptional(ERXKey<?> key, ERXKeyFilter filter) Includes the key in the given filter if isKeyPathRequested returns true.
protected boolean	isAutomaticHtmlRoutingEnabled() If this method returns true, all HTML format requests will be automatically routed to the corresponding IERXRouteComponent implementation based on the name returned by pageNameForAction(String).
protected boolean	isKeyPathRequested(ERXKey<?> key) Returns whether or not the prefetchingKeyPaths option includes the given keypath (meaning, the client requested to include the given keypath).
protected boolean	isKeyPathRequested(String keyPath) Returns whether or not the prefetchingKeyPaths option includes the given keypath (meaning, the client requested to include the given keypath).
protected boolean	isSchemaRequest() Returns whether or not this request is for a schema.
WOActionResults	json(EOClassDescription entity, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a JSON response.
WOActionResults	json(EOEditingContext editingContext, String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a JSON response.
WOActionResults	json(Object value, ERXKeyFilter filter) Returns the given object as a JSON response.
WOActionResults	json(String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a JSON response.
protected EOEditingContext	newEditingContext() Creates a new editing context.
protected EOEditingContext	newEditingContext(EOObjectStore objectStore) Creates a new editing context with a parent object store.
<T> T	object(ERXKeyFilter filter) Returns the object from the request data that is of the routed entity name and is filtered with the given filter.
<T> T	object(ERXKeyFilter filter, ERXRestContext restContext) Returns the object from the request data that is of the routed entity name and is filtered with the given filter.
<T> T	object(String entityName, ERXKeyFilter filter) Returns the object from the request data that is of the given entity name and is filtered with the given filter.
<T> T	object(String entityName, ERXKeyFilter filter, ERXRestContext restContext) Returns the object from the request data that is of the given entity name and is filtered with the given filter.
NSKeyValueCoding	options() Returns the options for this controller.
WOActionResults	optionsAction() A default options action that implements access control policy.
protected String	pageNameForAction(String actionName) Returns the name of the page component for this entity and the given action.
<T extends WOComponent> T	pageWithName(Class<T> componentClass) Calls pageWithName.
WOActionResults	performActionNamed(String actionName)
WOActionResults	performActionNamed(String actionName, boolean throwExceptions) Performs the given action, optionally throwing exceptions instead of converting to http response codes.
protected WOActionResults	performActionNamedWithError(String actionName, Throwable t) Called when performing an action fails, giving a chance to return an appropriate error result.
protected WOActionResults	performActionWithAnnotations(Method actionMethod, List<Annotation> parameterAnnotations) Called when performRouteAction dispatches a method that uses parameter annotations.
protected WOActionResults	performActionWithArguments(Method actionMethod, Object... args) Called when an action method is dispatched by performRouteAction in any form.
protected WOActionResults	performHtmlActionNamed(String actionName) If automatic HTML routing is enabled and this request used an HTML format, this method is called to dispatch the HTML action.
protected WOActionResults	performRouteActionNamed(String actionName) If this request is for a normal route action, this method is called to dispatch it.
protected WOActionResults	performUnknownAction(String actionName) Called when no standard action method can be found to handle the requested route.
WOActionResults	plist(EOClassDescription entity, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a JSON response.
WOActionResults	plist(EOEditingContext editingContext, String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a JSON response.
WOActionResults	plist(Object value, ERXKeyFilter filter) Returns the given object as a PList response.
WOActionResults	plist(String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a PList response.
protected WOActionResults	processActionResults(WOActionResults results) Before returning the action results, this method is called to perform any last minute processing.
ERXRouteRequestHandler	requestHandler() Returns the request handler that processed this route.
ERXRestRequestNode	requestNode() Returns the request data in the form of an ERXRestRequestNode (which is a format-independent wrapper around hierarchical data).
WOActionResults	response(EOClassDescription entity, NSArray<?> values, ERXKeyFilter filter) Returns the given array as an response in the format returned from the format() method.
WOActionResults	response(EOEditingContext editingContext, String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as an response in the format returned from the format() method.
WOActionResults	response(ERXRestFetchSpecification<?> fetchSpec, ERXKeyFilter filter) Returns the results of the rest fetch spec as an response in the format returned from the format() method.
WOActionResults	response(ERXRestFormat format, EOClassDescription entity, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a response in the given format.
WOActionResults	response(ERXRestFormat format, EOEditingContext editingContext, String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a response in the given format.
WOActionResults	response(ERXRestFormat format, ERXRestRequestNode responseNode) Returns the given ERXRestRequestNode as a response in the given format.
WOActionResults	response(ERXRestFormat format, Object value, ERXKeyFilter filter) Returns the given object as a WOResponse in the given format.
WOActionResults	response(ERXRestFormat format, String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as a response in the given format.
WOActionResults	response(int status) Returns an response with the given HTTP status and without any body content.
WOActionResults	response(Object value, ERXKeyFilter filter) Returns the given object as a response in the format returned from the format() method.
WOActionResults	response(String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as an response in the format returned from the format() method.
String	responseContentForActionNamed(String actionName) Returns the response content generated from performing the action with the given name.
ERXRestRequestNode	responseNodeForActionNamed(String actionName) Returns the response node generated from performing the action with the given name.
ERXRestContext	restContext() Returns the cached rest context for this controller.
ERXRoute	route() Returns the route associated with this request.
NSDictionary<ERXRoute.Key,String>	routeKeys() Returns the unprocessed keys from the route (the values are the original value from the URL).
<T> T	routeObjectForKey(String key) Returns the processed object from the route keys with the given name.
NSDictionary<ERXRoute.Key,Object>	routeObjects() Returns all the processed objects from the route keys.
NSDictionary<ERXRoute.Key,Object>	routeObjects(ERXRestContext restContext) Returns all the processed objects from the route keys.
String	routeStringForKey(String key) Returns the unprocessed value from the route with the given key name.
protected WOActionResults	schemaResponse(ERXKeyFilter filter) Returns the schema response for the current entity with the given filter.
protected WOActionResults	schemaResponseForEntityNamed(String entityName, ERXKeyFilter filter) Returns the schema response for the given entity with the given filter.
void	setOptions(NSKeyValueCoding options) Sets the options for this controller.
void	setRestContext(ERXRestContext restContext) Sets the rest context for this controller.
protected boolean	shouldFailOnMissingHtmlPage() If automatic html routing is enabled and there is no page component found that matches the current route, should that result in a 404?
WOResponse	stringResponse(String str) Returns the given string wrapped in a WOResponse.
String	toString()
void	update(Object obj, ERXKeyFilter filter) Updates the given object from the request data with the given filter.
void	update(Object obj, ERXKeyFilter filter, ERXRestContext restContext) Updates the given object from the request data with the given filter.
WOActionResults	xml(EOClassDescription entity, NSArray<?> values, ERXKeyFilter filter) Returns the given array as an XML response.
WOActionResults	xml(EOEditingContext editingContext, String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as an XML response.
WOActionResults	xml(Object value, ERXKeyFilter filter) Returns the given object as an XML response.
WOActionResults	xml(String entityName, NSArray<?> values, ERXKeyFilter filter) Returns the given array as an XML response.

Methods inherited from class com.webobjects.appserver.WODirectAction

_componentAction, defaultAction, getSessionIDForRequest, takeFormValueArraysForKeyArray, takeFormValuesForKeyArray

Methods inherited from class com.webobjects.appserver.WOAction

_isActionOnClass, _methodForAction, _preloadAllActionsOnClass, canAccessFieldsDirectly, context, debugString, existingSession, handleQueryWithUnboundKey, handleTakeValueForUnboundKey, initializeRequestSessionIDInContext, languages, logString, pageWithName, request, session, setLanguages, takeValueForKey, takeValueForKeyPath, unableToSetNullForKey, validateTakeValueForKeyPath, validateValueForKey, valueForKey, valueForKeyPath

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

handleQueryWithUnboundKey, handleTakeValueForUnboundKey, unableToSetNullForKey

Methods inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

takeValueForKeyPath, valueForKeyPath

Methods inherited from interface com.webobjects.foundation.NSKeyValueCoding

takeValueForKey, valueForKey

Methods inherited from interface com.webobjects.foundation.NSValidation

validateTakeValueForKeyPath, validateValueForKey

Constructor Detail

ERXRouteController

public ERXRouteController(WORequest request)

Constructs a new ERXRouteController.

Parameters:

request - the request

Method Detail

includeOptional

protected ERXKeyFilter includeOptional(ERXKey<?> key,
                                       ERXKeyFilter filter)

Includes the key in the given filter if isKeyPathRequested returns true.

Parameters:

key - the key to lookup

filter - the filter to include into

Returns:

the nested filter (or null if the key was not requested)

isKeyPathRequested

protected boolean isKeyPathRequested(ERXKey<?> key)

Returns whether or not the prefetchingKeyPaths option includes the given keypath (meaning, the client requested to include the given keypath).

Parameters:

key - the ERXKey to check on

Returns:

true if the keyPath is in the prefetchingKeyPaths option

isKeyPathRequested

protected boolean isKeyPathRequested(String keyPath)

Returns whether or not the prefetchingKeyPaths option includes the given keypath (meaning, the client requested to include the given keypath).

Parameters:

keyPath - the keyPath to check on

Returns:

true if the keyPath is in the prefetchingKeyPaths option

setOptions

public void setOptions(NSKeyValueCoding options)

Sets the options for this controller.

Parameters:

options - options for this controller

options

public NSKeyValueCoding options()

Returns the options for this controller. Options are an abstraction on request form values.

Returns:

the options for this controller (default to be ERXRequestFormValues)

_setContext

public void _setContext(WOContext context)

WODirectAction doesn't expose API for setting the context, which can be useful for passing data between controller.

Parameters:

context - the new context

_setRequestHandler

public void _setRequestHandler(ERXRouteRequestHandler requestHandler)

Sets the request handler that processed this route.

Parameters:

requestHandler - the request handler that processed this route

requestHandler

public ERXRouteRequestHandler requestHandler()

Returns the request handler that processed this route.

Returns:

the request handler that processed this route

checkAccess

protected void checkAccess()
                    throws SecurityException

Override to provide custom security checks. It is not necessary to call super on this method.

Throws:

SecurityException - if the security check fails

_setEditingContent

public void _setEditingContent(EOEditingContext ec)

editingContext

public EOEditingContext editingContext()

The controller maintains an editing context for the duration of the request. The first time you call this method, you will get a new EOEditingContext. Subsequent calls will return the same instance. This makes it a little more convenient when you're using update, create, etc methods.

Returns:

an EOEditingContext

newEditingContext

protected EOEditingContext newEditingContext()

Creates a new editing context.

Returns:

a new editing context

newEditingContext

protected EOEditingContext newEditingContext(EOObjectStore objectStore)

Creates a new editing context with a parent object store.

Parameters:

objectStore - the parent object store

Returns:

a new editing context

_setRoute

public void _setRoute(ERXRoute route)

Sets the route that is associated with this request. This is typically only set by the request handler.

Parameters:

route - the route that is associated with this controller

route

public ERXRoute route()

Returns the route associated with this request.

Returns:

the route associated with this request

_setRouteKeys

public void _setRouteKeys(NSDictionary<ERXRoute.Key,String> routeKeys)

Sets the unprocessed keys from the route.

Parameters:

routeKeys - the parsed keys from the route

routeKeys

public NSDictionary<ERXRoute.Key,String> routeKeys()

Returns the unprocessed keys from the route (the values are the original value from the URL).

Returns:

the unprocessed keys from the route

routeStringForKey

public String routeStringForKey(String key)

Returns the unprocessed value from the route with the given key name.

Parameters:

key - the key name to lookup

Returns:

the unprocessed value from the route with the given key name

containsRouteKey

public boolean containsRouteKey(String key)

Returns whether or not there is a route key with the given name.

Parameters:

key - the key name to lookup

Returns:

whether or not there is a route key with the given name

routeObjectForKey

public <T> T routeObjectForKey(String key)

Returns the processed object from the route keys with the given name. For instance, if your route specifies that you have a {person:Person}, routeObjectForKey("person") will return a Person object.

Parameters:

key - the key name to lookup

Returns:

the processed object from the route keys with the given name

_setRouteObjects

public void _setRouteObjects(NSDictionary<ERXRoute.Key,Object> objects)

Sets the processed objects for the current route. For instance, if your route specifies that you have a {person:Person}, this dictionary should contain a mapping from that route key to a person instance.

Parameters:

objects - the route objects to override

routeObjects

public NSDictionary<ERXRoute.Key,Object> routeObjects()

Returns all the processed objects from the route keys. For instance, if your route specifies that you have a {person:Person}, routeObjectForKey("person") will return a Person object.

Returns:

the processed objects from the route keys

routeObjects

public NSDictionary<ERXRoute.Key,Object> routeObjects(ERXRestContext restContext)

Returns all the processed objects from the route keys. For instance, if your route specifies that you have a {person:Person}, routeObjectForKey("person") will return a Person object. This method does NOT cache the results.

Parameters:

restContext - the delegate to fetch with

Returns:

the processed objects from the route keys

defaultFormat

protected ERXRestFormat defaultFormat()

Returns the default format to use if no other format is found, or if the requested format is invalid.

Returns:

the default format to use if no other format is found, or if the requested format is invalid

_setFormat

public void _setFormat(ERXRestFormat format)

Sets the format that will be used by this route controller.

Parameters:

format - the format to be used by this route controller

format

public ERXRestFormat format()

Returns the format that the user requested (usually based on the request file extension).

Returns:

the format that the user requested

formatNamed

protected ERXRestFormat formatNamed(String type)

Returns the format to use for the given type (see ERXRestFormat constants).

Parameters:

type - the type of format to use

Returns:

the corresponding format

createRestContext

protected ERXRestContext createRestContext()

Creates a new rest context for the controller.

Returns:

a new rest context for the controller

restContext

public ERXRestContext restContext()

Returns the cached rest context for this controller. If a rest context doesn't yet exist, this calls {createRestContext() to create a new instance.

Returns:

the rest context for this controller

setRestContext

public void setRestContext(ERXRestContext restContext)

Sets the rest context for this controller.

Parameters:

restContext - the rest context for this controller

_setRequestContent

public void _setRequestContent(ERXRestFormat format,
                               String requestContent)

Sets the request content that this controller will use for processing.

Parameters:

format - the requested format

requestContent - the content of the incoming request

_setRequestContent

public void _setRequestContent(String requestContent)

Sets the request content that this controller will use for processing -- this requires that a format() is specified.

Parameters:

requestContent - the content of the incoming request

_setRequestNode

public void _setRequestNode(ERXRestRequestNode requestNode)

Sets the request node that this controller will use for processing.

Parameters:

requestNode - the node reprsenting the incoming request

formatDelegateForFormat

protected ERXRestFormat.Delegate formatDelegateForFormat(ERXRestFormat format)

Returns the default format delegate to use for the given format (defaults to format.delegate()).

Parameters:

format - the format to lookup

Returns:

the delegate to use for this format

requestNode

public ERXRestRequestNode requestNode()

Returns the request data in the form of an ERXRestRequestNode (which is a format-independent wrapper around hierarchical data).

Returns:

the request data as an ERXRestRequestNode

object

public <T> T object(ERXKeyFilter filter)

Returns the object from the request data that is of the routed entity name and is filtered with the given filter. This will use the delegate returned from this controller's delegate() method.

Parameters:

filter - the filter to apply to the object for the purposes of updating (or null to not update)

Returns:

the object from the request data

object

public <T> T object(String entityName,
                    ERXKeyFilter filter)

Returns the object from the request data that is of the given entity name and is filtered with the given filter. This will use the delegate returned from this controller's delegate() method.

Parameters:

entityName - the entity name of the object in the request

filter - the filter to apply to the object for the purposes of updating (or null to not update)

Returns:

the object from the request data

object

public <T> T object(ERXKeyFilter filter,
                    ERXRestContext restContext)

Returns the object from the request data that is of the routed entity name and is filtered with the given filter.

Parameters:

filter - the filter to apply to the object for the purposes of updating (or null to not update)

restContext - the delegate to use

Returns:

the object from the request data

object

public <T> T object(String entityName,
                    ERXKeyFilter filter,
                    ERXRestContext restContext)

Returns the object from the request data that is of the given entity name and is filtered with the given filter.

Parameters:

entityName - the entity name of the object in the request

filter - the filter to apply to the object for the purposes of updating (or null to not update)

restContext - the delegate to use

Returns:

the object from the request data

create

public <T> T create(ERXKeyFilter filter)

Creates a new object from the request data that is of the routed entity name and is filtered with the given filter. This will use the delegate returned from this controller's delegate() method.

Parameters:

filter - the filter to apply to the object for the purposes of updating (or null to just create a blank one)

Returns:

the object from the request data

create

public <T> T create(String entityName,
                    ERXKeyFilter filter)

Creates a new object from the request data that is of the given entity name and is filtered with the given filter. This will use the delegate returned from this controller's delegate() method.

Parameters:

entityName - the entity name of the object in the request

filter - the filter to apply to the object for the purposes of updating (or null to just create a blank one)

Returns:

the object from the request data

create

public <T> T create(ERXKeyFilter filter,
                    ERXRestContext restContext)

Creates a new object from the request data that is of the routed entity name and is filtered with the given filter.

Parameters:

filter - the filter to apply to the object for the purposes of updating (or null to just create a blank one)

restContext - the delegate to use

Returns:

the object from the request data

create

public <T> T create(String entityName,
                    ERXKeyFilter filter,
                    ERXRestContext restContext)

Creates a new object from the request data that is of the given entity name and is filtered with the given filter.

Parameters:

entityName - the entity name of the object in the request

filter - the filter to apply to the object for the purposes of updating (or null to just create a blank one)

restContext - the delegate to use

Returns:

the object from the request data

update

public void update(Object obj,
                   ERXKeyFilter filter)

Updates the given object from the request data with the given filter. This will use the delegate returned from this controller's delegate() method.

Parameters:

obj - the object to update

filter - the filter to apply to the object for the purposes of updating (or null to not update)

update

public void update(Object obj,
                   ERXKeyFilter filter,
                   ERXRestContext restContext)

Updates the given object from the request data with the given filter.

Parameters:

obj - object to update

filter - the filter to apply to the object for the purposes of updating (or null to not update)

restContext - delegate to use

stringResponse

public WOResponse stringResponse(String str)

Returns the given string wrapped in a WOResponse.

Parameters:

str - the string to return

Returns:

a WOResponse

json

public WOActionResults json(String entityName,
                            NSArray<?> values,
                            ERXKeyFilter filter)

Returns the given array as a JSON response. This uses the editing context returned by editingContext().

Parameters:

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a JSON WOResponse

json

public WOActionResults json(EOEditingContext editingContext,
                            String entityName,
                            NSArray<?> values,
                            ERXKeyFilter filter)

Returns the given array as a JSON response.

Parameters:

editingContext - the editing context to use

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a JSON WOResponse

json

public WOActionResults json(EOClassDescription entity,
                            NSArray<?> values,
                            ERXKeyFilter filter)

Returns the given array as a JSON response.

Parameters:

entity - the entity type of the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a JSON WOResponse

plist

public WOActionResults plist(String entityName,
                             NSArray<?> values,
                             ERXKeyFilter filter)

Returns the given array as a PList response. This uses the editing context returned by editingContext().

Parameters:

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a PList WOResponse

plist

public WOActionResults plist(EOEditingContext editingContext,
                             String entityName,
                             NSArray<?> values,
                             ERXKeyFilter filter)

Returns the given array as a JSON response.

Parameters:

editingContext - the editing context to use

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a JSON WOResponse

plist

public WOActionResults plist(EOClassDescription entity,
                             NSArray<?> values,
                             ERXKeyFilter filter)

Returns the given array as a JSON response.

Parameters:

entity - the entity type of the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a JSON WOResponse

xml

public WOActionResults xml(String entityName,
                           NSArray<?> values,
                           ERXKeyFilter filter)

Returns the given array as an XML response. This uses the editing context returned by editingContext().

Parameters:

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

an XML WOResponse

xml

public WOActionResults xml(EOEditingContext editingContext,
                           String entityName,
                           NSArray<?> values,
                           ERXKeyFilter filter)

Returns the given array as an XML response.

Parameters:

editingContext - the editing context to use

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

an XML WOResponse

xml

public WOActionResults xml(EOClassDescription entity,
                           NSArray<?> values,
                           ERXKeyFilter filter)

Returns the given array as an XML response.

Parameters:

entity - the entity type of the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

an XML WOResponse

_canSetHeaderForActionResults

protected boolean _canSetHeaderForActionResults(WOActionResults results)

Returns whether or not headers can be added to the given action results.

Parameters:

results - the results to test

Returns:

whether or not headers can be added to the given action results

_setHeaderForActionResults

protected void _setHeaderForActionResults(String value,
                                          String key,
                                          WOActionResults results)

Attempt to set the header for the given results object.

Parameters:

value - the value

key - the key

results - the results object

response

public WOActionResults response(ERXRestFetchSpecification<?> fetchSpec,
                                ERXKeyFilter filter)

Returns the results of the rest fetch spec as an response in the format returned from the format() method. This uses the editing context returned by editingContext().

Parameters:

fetchSpec - the rest fetch specification to execute

filter - the filter to apply to the objects

Returns:

a WOResponse of the format returned from the format() method

response

public WOActionResults response(String entityName,
                                NSArray<?> values,
                                ERXKeyFilter filter)

Returns the given array as an response in the format returned from the format() method. This uses the editing context returned by editingContext().

Parameters:

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a WOResponse of the format returned from the format() method

response

public WOActionResults response(EOEditingContext editingContext,
                                String entityName,
                                NSArray<?> values,
                                ERXKeyFilter filter)

Returns the given array as an response in the format returned from the format() method.

Parameters:

editingContext - the editing context to use

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a WOResponse of the format returned from the format() method

response

public WOActionResults response(EOClassDescription entity,
                                NSArray<?> values,
                                ERXKeyFilter filter)

Returns the given array as an response in the format returned from the format() method.

Parameters:

entity - the entity type of the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a WOResponse of the format returned from the format() method

response

public WOActionResults response(ERXRestFormat format,
                                String entityName,
                                NSArray<?> values,
                                ERXKeyFilter filter)

Returns the given array as a response in the given format.

Parameters:

format - the format to use

entityName - the name of the entity type of the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a WOResponse in the given format

response

public WOActionResults response(ERXRestFormat format,
                                EOEditingContext editingContext,
                                String entityName,
                                NSArray<?> values,
                                ERXKeyFilter filter)

Returns the given array as a response in the given format.

Parameters:

format - the format to use

editingContext - the editing context to use

entityName - the name of the entities in the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a WOResponse in the given format

response

public WOActionResults response(ERXRestFormat format,
                                EOClassDescription entity,
                                NSArray<?> values,
                                ERXKeyFilter filter)

Returns the given array as a response in the given format.

Parameters:

format - the format to use

entity - the entity type of the array

values - the values in the array

filter - the filter to apply to the objects

Returns:

a WOResponse in the given format

response

public WOActionResults response(ERXRestFormat format,
                                ERXRestRequestNode responseNode)

Returns the given ERXRestRequestNode as a response in the given format.

Parameters:

format - the format to use

responseNode - the request node to render

Returns:

a WOResponse in the given format

json

public WOActionResults json(Object value,
                            ERXKeyFilter filter)

Returns the given object as a JSON response.

Parameters:

value - the value to return

filter - the filter to apply

Returns:

a WOResponse in JSON format

plist

public WOActionResults plist(Object value,
                             ERXKeyFilter filter)

Returns the given object as a PList response.

Parameters:

value - the value to return

filter - the filter to apply

Returns:

a WOResponse in PList format

xml

public WOActionResults xml(Object value,
                           ERXKeyFilter filter)

Returns the given object as an XML response.

Parameters:

value - the value to return

filter - the filter to apply

Returns:

a WOResponse in XML format

response

public WOActionResults response(Object value,
                                ERXKeyFilter filter)

Returns the given object as a response in the format returned from the format() method.

Parameters:

value - the value to return

filter - the filter to apply

Returns:

a WOResponse in the format returned from the format() method.

response

public WOActionResults response(ERXRestFormat format,
                                Object value,
                                ERXKeyFilter filter)

Returns the given object as a WOResponse in the given format.

Parameters:

format - the format to use

value - the value to return

filter - the filter to apply

Returns:

a WOResponse in the given format

response

public WOActionResults response(int status)

Returns an response with the given HTTP status and without any body content. Useful to return HTTP codes like 410 (Gone) or 304 (Not Modified)

Parameters:

status - the HTTP status code

Returns:

an error WOResponse

errorResponse

public WOActionResults errorResponse(Throwable t,
                                     int status)

Returns an error response with the given HTTP status.

Parameters:

t - the exception

status - the HTTP status code

Returns:

an error WOResponse

errorResponse

public WOActionResults errorResponse(String errorMessage,
                                     int status)

Returns an error response with the given HTTP status.

Parameters:

errorMessage - the error message

status - the HTTP status code

Returns:

an error WOResponse

errorResponse

public WOActionResults errorResponse(int status)

Returns an error response with the given HTTP status and without any body content

Parameters:

status - the HTTP status code

Returns:

an error WOResponse

headAction

public WOActionResults headAction()

Returns the response from a HEAD call to this controller.

Returns:

a head response

_takeRouteParametersFromRequest

protected void _takeRouteParametersFromRequest(WOActionResults results)

Enumerates the route keys, looks for @ERXRouteParameter annotated methods, and sets the value of the routeKey with the corresponding method if it exists.

Parameters:

results - the results to apply route parameter to

isAutomaticHtmlRoutingEnabled

protected boolean isAutomaticHtmlRoutingEnabled()

If this method returns true, all HTML format requests will be automatically routed to the corresponding IERXRouteComponent implementation based on the name returned by pageNameForAction(String).

Returns:

true if HTML format requests should be automatically routed to the corresponding page component

shouldFailOnMissingHtmlPage

protected boolean shouldFailOnMissingHtmlPage()

If automatic html routing is enabled and there is no page component found that matches the current route, should that result in a 404?

Returns:

whether or not a missing page is a failure

_setEntityName

public void _setEntityName(String entityName)

Sets the entity name for this controller.

Parameters:

entityName - this controller's entity name

entityName

protected String entityName()

Returns the name of the entity that this controller is currently handling. The default implementation retrieves the entity name from the ERXRoute.

Returns:

the entity name for the current route

pageNameForAction

protected String pageNameForAction(String actionName)

Returns the name of the page component for this entity and the given action. The default implementation of this returns entityName + Action + Page ("PersonEditPage", "PersonViewPage", etc).

Parameters:

actionName - the name of the action

Returns:

the name of the page component for this action

performUnknownAction

protected WOActionResults performUnknownAction(String actionName)
                                        throws Exception

Called when no standard action method can be found to handle the requested route. The default implementation just throws an exception.

Parameters:

actionName - the unknown action name

Returns:

WOActionResults

Throws:

Exception

performActionNamed

public WOActionResults performActionNamed(String actionName)

Overrides:

performActionNamed in class WODirectAction

responseNodeForActionNamed

public ERXRestRequestNode responseNodeForActionNamed(String actionName)

Returns the response node generated from performing the action with the given name.

Parameters:

actionName - the name of the action to perform

Returns:

the response node

responseContentForActionNamed

public String responseContentForActionNamed(String actionName)

Returns the response content generated from performing the action with the given name.

Parameters:

actionName - the name of the action to perform

Returns:

the response content

performActionNamed

public WOActionResults performActionNamed(String actionName,
                                          boolean throwExceptions)
                                   throws RuntimeException

Performs the given action, optionally throwing exceptions instead of converting to http response codes.

Parameters:

actionName - the name of the action to perform

throwExceptions - whether or not to throw exceptions

Returns:

the action results

Throws:

RuntimeException - if a failure occurs

performHtmlActionNamed

protected WOActionResults performHtmlActionNamed(String actionName)
                                          throws Exception

If automatic HTML routing is enabled and this request used an HTML format, this method is called to dispatch the HTML action.

Parameters:

actionName - the name of the HTML action

Returns:

the results of the action

Throws:

Exception - if anything fails

performRouteActionNamed

protected WOActionResults performRouteActionNamed(String actionName)
                                           throws Exception

If this request is for a normal route action, this method is called to dispatch it.

Parameters:

actionName - the name of the action to perform

Returns:

the results of the action

Throws:

Exception - if anything fails

performActionWithAnnotations

protected WOActionResults performActionWithAnnotations(Method actionMethod,
                                                       List<Annotation> parameterAnnotations)
                                                throws Exception

Called when performRouteAction dispatches a method that uses parameter annotations.

Parameters:

actionMethod - the action method to dispatch

parameterAnnotations - the list of annotations

Returns:

the results of the action

Throws:

Exception - if anything fails

performActionWithArguments

protected WOActionResults performActionWithArguments(Method actionMethod,
                                                     Object... args)
                                              throws Exception

Called when an action method is dispatched by performRouteAction in any form.

Parameters:

actionMethod - the method to invoke

args - the arguments to pass to the method

Returns:

the results of the method

Throws:

Exception - if anything fails

performActionNamedWithError

protected WOActionResults performActionNamedWithError(String actionName,
                                                      Throwable t)

Called when performing an action fails, giving a chance to return an appropriate error result.

Parameters:

actionName - the name of the action that attempted to perform

t - the error that occurred

Returns:

an appropriate error result

processActionResults

protected WOActionResults processActionResults(WOActionResults results)

Before returning the action results, this method is called to perform any last minute processing.

Parameters:

results -

allowWindowNameCrossDomainTransport

protected boolean allowWindowNameCrossDomainTransport()

Returns whether or not the window.name cross-domain transport is allowed.

Returns:

whether or not the window.name cross-domain transport is allowed

allowJSONP

protected boolean allowJSONP()

Returns whether or not JSONP (JSON with Padding) is allowed.

Returns:

whether or not JSONP (JSON with Padding) is allowed

accessControlAllowOrigin

protected String accessControlAllowOrigin()

Returns the allowed origin for cross-site requests. Set the property ERXRest.accessControlAllowOrigin=* to enable all origins.

Returns:

the allowed origin for cross-site requests

accessControlAllowRequestMethods

protected NSArray<String> accessControlAllowRequestMethods(String requestMethod)

Returns the allowed request methods given the requested method. Set the property ERXRest.accessControlAllowRequestMethods to override the default of returning OPTIONS,GET,HEAD,POST,PUT,DELETE,TRACE,CONNECT.

Parameters:

requestMethod - the requested method

Returns:

the array of allowed request methods

accessControlAllowRequestHeaders

protected NSArray<String> accessControlAllowRequestHeaders(NSArray<String> requestHeaders)

Returns the allowed request headers given the requested headers.Set the property ERXRest.accessControlAllowRequestHeaders to override the default of just returning the requested headers.

Parameters:

requestHeaders - the requested headers

Returns:

the array of allowed request headers

accessControlMaxAage

protected long accessControlMaxAage()

Returns the maximum age in seconds for the preflight options cache.

Returns:

the maximum age for the preflight options cache

optionsAction

public WOActionResults optionsAction()
                              throws Throwable

A default options action that implements access control policy.

Returns:

the response

Throws:

Throwable

pageWithName

public <T extends WOComponent> T pageWithName(Class<T> componentClass)

Calls pageWithName.

Type Parameters:

T - the type of component to return

Parameters:

componentClass - the component class to lookup

Returns:

the created component

controller

public <T extends ERXRouteController> T controller(String entityName)

Returns another controller, passing the required state on.

Type Parameters:

T - the type of controller to return

Parameters:

entityName - the entity name of the controller to lookup

Returns:

the created controller

controller

public <T extends ERXRouteController> T controller(Class<T> controllerClass)

Returns another controller, passing the required state on.

Type Parameters:

T - the type of controller to return

Parameters:

controllerClass - the controller class to lookup

Returns:

the created controller

dispose

public void dispose()

Disposes any resources the route controller may be holding onto (like its editing context).

isSchemaRequest

protected boolean isSchemaRequest()

Returns whether or not this request is for a schema.

Returns:

whether or not this request is for a schema

schemaResponse

protected WOActionResults schemaResponse(ERXKeyFilter filter)

Returns the schema response for the current entity with the given filter.

Parameters:

filter - the filter to apply

Returns:

the schema response for the current entity with the given filter

schemaResponseForEntityNamed

protected WOActionResults schemaResponseForEntityNamed(String entityName,
                                                       ERXKeyFilter filter)

Returns the schema response for the given entity with the given filter.

Parameters:

entityName - the entity name

filter - the filter to apply

Returns:

the schema response for the given entity with the given filter

toString

public String toString()

Overrides:

toString in class WOAction

_registerControllerForRequest

protected static void _registerControllerForRequest(ERXRouteController controller,
                                                    WORequest request)

Registers the given controller with the given request, so it can be later disposed. This can be a very useful performance optimization for apps that gets a large number of requests.

Parameters:

controller - the controller to register

request - the request to register with

_controllersForRequest

public static NSMutableArray<ERXRouteController> _controllersForRequest(WORequest request)

Returns the controllers that have been used on the given request.

Parameters:

request - the request

_disposeControllersForRequest

public static void _disposeControllersForRequest(WORequest request)

Disposes all of the controllers that were used on the given request.

Parameters:

request - the request