er.rest.entityDelegates
Class ERXAbstractRestResponseWriter

java.lang.Object
  er.rest.entityDelegates.ERXAbstractRestResponseWriter

All Implemented Interfaces:

IERXRestResponseWriter

Direct Known Subclasses:

ERXDictionaryRestResponseWriter, ERXXmlRestResponseWriter

public abstract class ERXAbstractRestResponseWriter
extends java.lang.Object
implements IERXRestResponseWriter

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

Field Summary

Fields inherited from interface er.rest.entityDelegates.IERXRestResponseWriter

DETAILS_PREFIX, DETAILS_PROPERTIES_PREFIX, REST_PREFIX

Constructor Summary

ERXAbstractRestResponseWriter()
Constructs an ERXAbstractRestResponseWriter with displayAllProperties = false.

ERXAbstractRestResponseWriter(boolean displayAllProperties, boolean displayAllToMany)
Constructs an ERXAbstractRestResponseWriter.

ERXAbstractRestResponseWriter(ERXKeyFilter filter)
Constructs an ERXAbstractRestResponseWriter.

Method Summary

protected void	appendArrayToResponse(ERXRestContext context, IERXRestResponse response, ERXRestKey result, int indent, com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects)
protected abstract void	appendArrayToResponse(ERXRestContext context, IERXRestResponse response, ERXRestKey key, java.lang.String arrayName, java.lang.String entityName, com.webobjects.foundation.NSArray valueKeys, int indent, com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects) Writes the given array of objects to the response.
protected abstract void	appendDetailsToResponse(ERXRestContext context, IERXRestResponse response, com.webobjects.eoaccess.EOEntity entity, com.webobjects.eocontrol.EOEnterpriseObject eo, java.lang.String objectName, java.lang.String entityName, java.lang.Object id, com.webobjects.foundation.NSArray displayKeys, int indent, com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects) Writes the visible details of an object to the response.
protected void	appendDictionaryToResponse(ERXRestContext context, IERXRestResponse response, ERXRestKey result, int indent, com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects)
protected abstract void	appendNoDetailsToResponse(ERXRestContext context, IERXRestResponse response, com.webobjects.eoaccess.EOEntity entity, com.webobjects.eocontrol.EOEnterpriseObject eo, java.lang.String objectName, java.lang.String entityName, java.lang.Object id, int indent) Write an object to the response without showing its details.
protected abstract void	appendPrimitiveToResponse(ERXRestContext context, IERXRestResponse response, ERXRestKey result, int indent, java.lang.Object value) Writes the bare primitive out to the response.
void	appendToResponse(ERXRestContext context, IERXRestResponse response, ERXRestKey result) Called at the end of a request to produce the output to the user.
protected void	appendToResponse(ERXRestContext context, IERXRestResponse response, ERXRestKey result, int indent, com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects)
protected abstract void	appendVisitedToResponse(ERXRestContext context, IERXRestResponse response, com.webobjects.eoaccess.EOEntity entity, com.webobjects.eocontrol.EOEnterpriseObject eo, java.lang.String objectName, java.lang.String entityName, java.lang.Object id, int indent) Write an object to the response that has already been visited.
protected boolean	displayDetails(ERXRestContext context, ERXRestKey key) Returns whether or not the details (i.e.
protected java.lang.String[]	displayProperties(ERXRestContext context, ERXRestKey key) Returns the set of properties that can be displayed for the given key.
protected void	indent(IERXRestResponse response, int indent)
java.lang.String	toString(com.webobjects.eocontrol.EOEditingContext editingContext, java.lang.String entityName, com.webobjects.foundation.NSArray values) Returns a String form of the given objects using the unsafe delegate.
java.lang.String	toString(com.webobjects.eoaccess.EOEntity entity, com.webobjects.foundation.NSArray values) Returns a String form of the given objects using the unsafe delegate.
java.lang.String	toString(java.lang.Object value) Returns a String form of the given object using the unsafe delegate.

Methods inherited from class java.lang.Object

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

Constructor Detail

ERXAbstractRestResponseWriter

public ERXAbstractRestResponseWriter()

Constructs an ERXAbstractRestResponseWriter with displayAllProperties = false.

ERXAbstractRestResponseWriter

public 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

public ERXAbstractRestResponseWriter(ERXKeyFilter filter)

Constructs an ERXAbstractRestResponseWriter.

Parameters:

filter - the filter to apply to the written results

Method Detail

displayDetails

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

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

Throws:

ERXRestException - if a general error occurs

ERXRestSecurityException - if a security error occurs

ERXRestNotFoundException - if an object is not found

displayProperties

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

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

Throws:

ERXRestException - if a general error occurs

ERXRestSecurityException - if a security error occurs

ERXRestNotFoundException - if an object is not found

appendToResponse

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

Description copied from interface: IERXRestResponseWriter

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

Specified by:

appendToResponse in interface IERXRestResponseWriter

Parameters:

context - the rest context

response - the response to write into

result - the result of the rest request

Throws:

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

appendDictionaryToResponse

protected void appendDictionaryToResponse(ERXRestContext context,
                                          IERXRestResponse response,
                                          ERXRestKey result,
                                          int indent,
                                          com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects)
                                   throws ERXRestException,
                                          ERXRestSecurityException,
                                          ERXRestNotFoundException,
                                          java.text.ParseException

Throws:

ERXRestException

ERXRestSecurityException

ERXRestNotFoundException

java.text.ParseException

appendArrayToResponse

protected void appendArrayToResponse(ERXRestContext context,
                                     IERXRestResponse response,
                                     ERXRestKey result,
                                     int indent,
                                     com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects)
                              throws ERXRestException,
                                     ERXRestSecurityException,
                                     ERXRestNotFoundException,
                                     java.text.ParseException

Throws:

ERXRestException

ERXRestSecurityException

ERXRestNotFoundException

java.text.ParseException

appendToResponse

protected void appendToResponse(ERXRestContext context,
                                IERXRestResponse response,
                                ERXRestKey result,
                                int indent,
                                com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects)
                         throws ERXRestException,
                                ERXRestSecurityException,
                                ERXRestNotFoundException,
                                java.text.ParseException

Throws:

ERXRestException

ERXRestSecurityException

ERXRestNotFoundException

java.text.ParseException

indent

protected void indent(IERXRestResponse response,
                      int indent)

appendArrayToResponse

protected abstract void appendArrayToResponse(ERXRestContext context,
                                              IERXRestResponse response,
                                              ERXRestKey key,
                                              java.lang.String arrayName,
                                              java.lang.String entityName,
                                              com.webobjects.foundation.NSArray valueKeys,
                                              int indent,
                                              com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects)
                                       throws ERXRestException,
                                              ERXRestSecurityException,
                                              ERXRestNotFoundException,
                                              java.text.ParseException

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)

Throws:

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

appendVisitedToResponse

protected abstract void appendVisitedToResponse(ERXRestContext context,
                                                IERXRestResponse response,
                                                com.webobjects.eoaccess.EOEntity entity,
                                                com.webobjects.eocontrol.EOEnterpriseObject eo,
                                                java.lang.String objectName,
                                                java.lang.String entityName,
                                                java.lang.Object id,
                                                int indent)

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

appendNoDetailsToResponse

protected abstract void appendNoDetailsToResponse(ERXRestContext context,
                                                  IERXRestResponse response,
                                                  com.webobjects.eoaccess.EOEntity entity,
                                                  com.webobjects.eocontrol.EOEnterpriseObject eo,
                                                  java.lang.String objectName,
                                                  java.lang.String entityName,
                                                  java.lang.Object id,
                                                  int indent)

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

appendDetailsToResponse

protected abstract void appendDetailsToResponse(ERXRestContext context,
                                                IERXRestResponse response,
                                                com.webobjects.eoaccess.EOEntity entity,
                                                com.webobjects.eocontrol.EOEnterpriseObject eo,
                                                java.lang.String objectName,
                                                java.lang.String entityName,
                                                java.lang.Object id,
                                                com.webobjects.foundation.NSArray displayKeys,
                                                int indent,
                                                com.webobjects.foundation.NSMutableSet<java.lang.Object> visitedObjects)
                                         throws ERXRestException,
                                                ERXRestSecurityException,
                                                ERXRestNotFoundException,
                                                java.text.ParseException

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)

Throws:

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

appendPrimitiveToResponse

protected abstract void appendPrimitiveToResponse(ERXRestContext context,
                                                  IERXRestResponse response,
                                                  ERXRestKey result,
                                                  int indent,
                                                  java.lang.Object value)
                                           throws ERXRestException

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

Throws:

ERXRestException - if a general failure occurs

toString

public java.lang.String toString(java.lang.Object value)
                          throws ERXRestException,
                                 ERXRestSecurityException,
                                 ERXRestNotFoundException,
                                 java.text.ParseException

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

Specified by:

toString in interface IERXRestResponseWriter

Parameters:

value - the value to write

Returns:

a string form of the value using the given writer

Throws:

ERXRestException

ERXRestSecurityException

ERXRestNotFoundException

ParseException

toString

public java.lang.String toString(com.webobjects.eoaccess.EOEntity entity,
                                 com.webobjects.foundation.NSArray values)
                          throws ERXRestException,
                                 ERXRestSecurityException,
                                 ERXRestNotFoundException,
                                 java.text.ParseException

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

Specified by:

toString in interface IERXRestResponseWriter

Parameters:

values - the values to write

Returns:

a string form of the value using the given writer

Throws:

ERXRestException

ERXRestSecurityException

ERXRestNotFoundException

ParseException

toString

public java.lang.String toString(com.webobjects.eocontrol.EOEditingContext editingContext,
                                 java.lang.String entityName,
                                 com.webobjects.foundation.NSArray values)
                          throws ERXRestException,
                                 ERXRestSecurityException,
                                 ERXRestNotFoundException,
                                 java.text.ParseException

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

Specified by:

toString in interface IERXRestResponseWriter

Parameters:

values - the values to write

editingContext - the editingcontext to resolve the given entity name within

entityName - the entity name of the values of the array

Returns:

a string form of the value using the given writer

Throws:

ERXRestException

ERXRestSecurityException

ERXRestNotFoundException

ParseException