ERXAbstractRestResponseWriter Class Reference

Inherits er::rest::entityDelegates::IERXRestResponseWriter.

Inherited by ERXDictionaryRestResponseWriter, and ERXXmlRestResponseWriter.

Collaboration diagram for ERXAbstractRestResponseWriter:

[legend]

List of all members.

Public Member Functions
void	appendToResponse (ERXRestContext context, IERXRestResponse response, ERXRestKey result) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
	ERXAbstractRestResponseWriter (ERXKeyFilter filter)
	ERXAbstractRestResponseWriter (boolean displayAllProperties, boolean displayAllToMany)
	ERXAbstractRestResponseWriter ()
String	toString (EOEditingContext editingContext, String entityName, NSArray values) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
String	toString (EOEntity entity, NSArray values) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
String	toString (Object value) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
Protected Member Functions
abstract void	appendArrayToResponse (ERXRestContext context, IERXRestResponse response, ERXRestKey key, String arrayName, String entityName, NSArray valueKeys, int indent, NSMutableSet< Object > visitedObjects) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
void	appendArrayToResponse (ERXRestContext context, IERXRestResponse response, ERXRestKey result, int indent, NSMutableSet< Object > visitedObjects) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
abstract void	appendDetailsToResponse (ERXRestContext context, IERXRestResponse response, EOEntity entity, EOEnterpriseObject eo, String objectName, String entityName, Object id, NSArray displayKeys, int indent, NSMutableSet< Object > visitedObjects) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
void	appendDictionaryToResponse (ERXRestContext context, IERXRestResponse response, ERXRestKey result, int indent, NSMutableSet< Object > visitedObjects) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
abstract void	appendNoDetailsToResponse (ERXRestContext context, IERXRestResponse response, EOEntity entity, EOEnterpriseObject eo, String objectName, String entityName, Object id, int indent)
abstract void	appendPrimitiveToResponse (ERXRestContext context, IERXRestResponse response, ERXRestKey result, int indent, Object value) throws ERXRestException
void	appendToResponse (ERXRestContext context, IERXRestResponse response, ERXRestKey result, int indent, NSMutableSet< Object > visitedObjects) throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException
abstract void	appendVisitedToResponse (ERXRestContext context, IERXRestResponse response, EOEntity entity, EOEnterpriseObject eo, String objectName, String entityName, Object id, int indent)
boolean	displayDetails (ERXRestContext context, ERXRestKey key) throws ERXRestException, ERXRestNotFoundException, ERXRestSecurityException
String[]	displayProperties (ERXRestContext context, ERXRestKey key) throws ERXRestException, ERXRestNotFoundException, ERXRestSecurityException
void	indent (IERXRestResponse response, int indent)
Private Attributes
boolean	_displayAllProperties
boolean	_displayAllToMany
ERXKeyFilter	_filter

---

Detailed Description

ERXAbstractRestResponseWriter provides the output-method-agnostic methods for processing a rest response and provides support for specifying rendering configuration in your application properties.

There are multiple levels of rendering controls that you can adjust. These adjustments come in two primary forms -- details and details properties.

The details setting allows you to specify that for a given keypath, whether or not a particular relationship should display only the id of the related object or the id as well as its properties.

The details properties setting defines the "upper bound" of properties to display to a user for a particular keypath. That is to say that for a particular key path, the user will never be shown any key that is outside of the specified list. However, permissions on a particular entity may restrict access such that the user is not able to see all the keys specified. This control allows you to specify at a rendering level what the user can and cannot see on an object.

These properties take the form:

 ERXRest.[EntityName].details=true/false
 ERXRest.[EntityName].detailsProperties=property_1,property_2,property_3,...,property_n
 ERXRest.[EntityName].property_a.property_a_b.details=true/false
 ERXRest.[EntityName].property_a.property_a_b.detailsProperties=property_1,property_2,property_3,...,property_n
 

For example:

 ERXRest.Organization.details=true
 ERXRest.Organization.detailsProperties=name,purchasedPlans
 ERXRest.Organization.purchasedPlans.details=false

 ERXRest.Site.details=true
 ERXRest.Site.detailsProperties=title,organization,disabledAt,memberships,sheetSets,blogEntries
 ERXRest.Site.blogEntries.details=true
 ERXRest.Site.blogEntries.detailsProperties=author,submissionDate,title,contents
 ERXRest.Site.sheetSets.details=false
 ERXRest.Site.memberships.details=false

 ERXRest.BlogEntry.details=true
 ERXRest.BlogEntry.detailsProperties=site,author,submissionDate,title,contents
 

Note that all properties that appear in a details properties definition should be "actual" property names, not property aliases. Similarly, all entity references should be the actual entity name, not an entity alias.

In the example above, if someone requests an Organization as the top level entity, the details will be displayed. The properties that will be displayed in those details includes "name" and "purchasedPlans", which is a to-many relationship. In the example, we have explicitly declared that Organization.purchasedPlans will not show any details, though this was technically unnecessary because the default is "false".

For a request for http://yoursite/yourapp.woa/rest/Organization/100.xml, the output will look like:

 <Organization id = "100">
   <name>Organization Name</name>
   <purchasedPlans type = "PurchasedPlan">
     <PurchasedPlan id = "200"/>
     <PurchasedPlan id = "201"/>
     <PurchasedPlan id = "202"/>
   </purchasedPlans>
 </Organization>
 

In the second and third blocks of the example, you can see two different specifications for properties to display for a BlogEntry. If you request Site/100/blogEntries.xml, you will see a set of properties that does not include the site relationship of the blog entry (notice that ERXRest.Site.blogEntries.detailsProperties does not specify "site"). However, if you request BlogEntry/301.xml you will see the site relationship (notice that ERXRest.BlogEntry.detailsProperties DOES contain "site"). Also note that primary keys should not be used in the definition of renderer configurations. Configuration is assumed to apply to any instance of an object that structurally matches the keypaths you define.

The renderer looks for the longest matching keypath specification in the Properties file to determine whether or not to display properties and which properties to display, so you can construct arbitrarily deep specifications for which properties to display for any given keypath.

Author:

mschrag

---

Constructor & Destructor Documentation

ERXAbstractRestResponseWriter

(

)

Constructs an ERXAbstractRestResponseWriter with displayAllProperties = false.

ERXAbstractRestResponseWriter	(	boolean	displayAllProperties,
		boolean	displayAllToMany
	)

Constructs an ERXAbstractRestResponseWriter.

Parameters:

	displayAllProperties	if true, by default all properties are eligible to be displayed (probably should only be true in development, but it won't really hurt anything). Note that entity delegates will still control permissions on the properties, it just defaults to checking all of them.
	displayAllToMany	if true, all to-many relationships will be displayed

ERXAbstractRestResponseWriter

(

ERXKeyFilter

filter

)

Constructs an ERXAbstractRestResponseWriter.

Parameters:

filter

the filter to apply to the written results

---

Member Function Documentation

abstract void appendArrayToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		ERXRestKey	key,
		String	arrayName,
		String	entityName,
		NSArray	valueKeys,
		int	indent,
		NSMutableSet< Object >	visitedObjects
	)			throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException [protected, pure virtual]

Writes the given array of objects to the response. Permissions have already been checked by the time this method is called.

Parameters:

	context	the rest context
	response	the response
	key	the current key
	arrayName	the name of the array in the context of its parent
	entityName	the entity name of the contents of the array
	valueKeys	an array of ERXRestKeys that represent the entries in the array
	indent	the indent level
	visitedObjects	the list of objects that have been visited already in this request (to prevent infinite loops)

Exceptions:

	ERXRestException	if a general error occurs
	ERXRestSecurityException	if a security error occurs
	ERXRestNotFoundException	if an object is not found
	ParseException	if a parse error occurs

Implemented in ERXDictionaryRestResponseWriter, and ERXXmlRestResponseWriter.

void appendArrayToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		ERXRestKey	result,
		int	indent,
		NSMutableSet< Object >	visitedObjects
	)			throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException [protected]

abstract void appendDetailsToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		EOEntity	entity,
		EOEnterpriseObject	eo,
		String	objectName,
		String	entityName,
		Object	id,
		NSArray	displayKeys,
		int	indent,
		NSMutableSet< Object >	visitedObjects
	)			throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException [protected, pure virtual]

Writes the visible details of an object to the response. Permissions have already been checked by the time this method is called.

Parameters:

	context	the rest context
	response	the response
	entity	the entity of the object
	eo	the current object
	objectName	the name of the object (relative to its parent)
	entityName	the entity name of the object
	id	the id of the object
	displayKeys	the list of ERXRestKeys to display
	indent	the indent level
	visitedObjects	the list of objects that have been visited already in this request (to prevent infinite loops)

Exceptions:

	ERXRestException	if a general error occurs
	ERXRestSecurityException	if a security error occurs
	ERXRestNotFoundException	if an object is not found
	ParseException	if a parse error occurs

Implemented in ERXDictionaryRestResponseWriter, and ERXXmlRestResponseWriter.

void appendDictionaryToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		ERXRestKey	result,
		int	indent,
		NSMutableSet< Object >	visitedObjects
	)			throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException [protected]

abstract void appendNoDetailsToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		EOEntity	entity,
		EOEnterpriseObject	eo,
		String	objectName,
		String	entityName,
		Object	id,
		int	indent
	)			[protected, pure virtual]

Write an object to the response without showing its details. This is typically similar to appendVisitedToResponse, but is provided as a separate call because it is semantically a different scenario. Permissions have already been checked by the time this method is called.

Parameters:

	context	the rest context
	response	the response
	entity	the entity of the object
	eo	the current object
	objectName	the name of the object (relative to its parent)
	entityName	the entity name of the object
	id	the id of the object
	indent	the indent level

Implemented in ERXDictionaryRestResponseWriter, and ERXXmlRestResponseWriter.

abstract void appendPrimitiveToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		ERXRestKey	result,
		int	indent,
		Object	value
	)			throws ERXRestException [protected, pure virtual]

Writes the bare primitive out to the response. Permissions have already been checked by the time this method is called.

Parameters:

	context	the rest context
	response	the response
	result	the current key
	indent	the indent level
	value	the value to append

Exceptions:

ERXRestException

if a general failure occurs

Implemented in ERXDictionaryRestResponseWriter, and ERXXmlRestResponseWriter.

void appendToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		ERXRestKey	result,
		int	indent,
		NSMutableSet< Object >	visitedObjects
	)			throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException [protected]

void appendToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		ERXRestKey	result
	)			throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException

Called at the end of a request to produce the output to the user.

Parameters:

	context	the rest context
	response	the response to write into
	result	the result of the rest request

Exceptions:

	ERXRestException	if there is a general failure
	ERXRestSecurityException	if there is a security violation
	ERXRestNotFoundException	if there is a missing entity
	ParseException	if there is a parse error

Implements IERXRestResponseWriter.

Reimplemented in ERXXmlRestResponseWriter.

abstract void appendVisitedToResponse	(	ERXRestContext	context,
		IERXRestResponse	response,
		EOEntity	entity,
		EOEnterpriseObject	eo,
		String	objectName,
		String	entityName,
		Object	id,
		int	indent
	)			[protected, pure virtual]

Write an object to the response that has already been visited. Typically this would just write out the type and id of the object, to prevent entering an infinite loop in the renderer. Permissions have already been checked by the time this method is called.

Parameters:

	context	the rest context
	response	the response
	entity	the entity of the object
	eo	the current object
	objectName	the name of the object (relative to its parent)
	entityName	the entity name of the object
	id	the id of the object
	indent	the indent level

Implemented in ERXDictionaryRestResponseWriter, and ERXXmlRestResponseWriter.

boolean displayDetails	(	ERXRestContext	context,
		ERXRestKey	key
	)			throws ERXRestException, ERXRestNotFoundException, ERXRestSecurityException [protected]

Returns whether or not the details (i.e. the keys of an EO) should displayed for the given key.

Parameters:

	context	the rest context
	key	the current key

Returns:

whether or not the details (i.e. the keys of an EO) should displayed for the given key

Exceptions:

	ERXRestException	if a general error occurs
	ERXRestSecurityException	if a security error occurs
	ERXRestNotFoundException	if an object is not found

String [] displayProperties	(	ERXRestContext	context,
		ERXRestKey	key
	)			throws ERXRestException, ERXRestNotFoundException, ERXRestSecurityException [protected]

Returns the set of properties that can be displayed for the given key.

Parameters:

	context	the rest context
	key	the current key

Returns:

the set of properties that can be displayed for the given key

Exceptions:

	ERXRestException	if a general error occurs
	ERXRestSecurityException	if a security error occurs
	ERXRestNotFoundException	if an object is not found

void indent	(	IERXRestResponse	response,
		int	indent
	)			[protected]

String toString	(	EOEditingContext	editingContext,
		String	entityName,
		NSArray	values
	)			throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException

Returns a String form of the given objects using the unsafe delegate.

Parameters:

values

the values to write

Returns:

a string form of the value using the given writer

Exceptions:

	ERXRestException
	ERXRestSecurityException
	ERXRestNotFoundException
	ParseException

Implements IERXRestResponseWriter.

String toString	(	EOEntity	entity,
		NSArray	values
	)			throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException

Returns a String form of the given objects using the unsafe delegate.

Parameters:

values

the values to write

Returns:

a string form of the value using the given writer

Exceptions:

	ERXRestException
	ERXRestSecurityException
	ERXRestNotFoundException
	ParseException

Implements IERXRestResponseWriter.

String toString

(

Object

value

)

throws ERXRestException, ERXRestSecurityException, ERXRestNotFoundException, ParseException

Returns a String form of the given object using the unsafe delegate.

Parameters:

value

the value to write

Returns:

a string form of the value using the given writer

Exceptions:

	ERXRestException
	ERXRestSecurityException
	ERXRestNotFoundException
	ParseException

Implements IERXRestResponseWriter.

---

Member Data Documentation

boolean _displayAllProperties [private]

boolean _displayAllToMany [private]

ERXKeyFilter _filter [private]

---

The documentation for this class was generated from the following file:

• /opt/source/Wonder/Frameworks/EOF/ERRest/Sources/er/rest/entityDelegates/ERXAbstractRestResponseWriter.java