er.rest.entityDelegates
Class ERXStandardRestEntityDelegate

java.lang.Object
  er.rest.entityDelegates.ERXAbstractRestEntityDelegate
      er.rest.entityDelegates.ERXStandardRestEntityDelegate

All Implemented Interfaces:

IERXRestEntityDelegate, IERXRestSecurityDelegate

Direct Known Subclasses:

ERXUnsafeReadOnlyRestEntityDelegate, ERXUnsafeRestEntityDelegate

public abstract class ERXStandardRestEntityDelegate
extends ERXAbstractRestEntityDelegate

ERXStandardRestEntityDelegate provides additional implementations of methods above and beyond ERXAbstractRestEntityDelegate.

In particular it adds support for loading certain common configuration out of your application Properties file, including:

• entity aliases
• property aliases
• view properties
• insert properties
• update properties

Entity Aliases

Entity aliases allow you to remap the name of entity from its actual internal name to some other name that is shown to consumers of your service:

 ERXRest.[EntityName].alias=SomeOtherName
 

For example:

 ERXRest.Person.alias = Employee
 

In the above example, our entity is named Person, but we want users of our service to see it named "Employee."

Property Aliases

Just like entity aliases, it is often desirable to be able to rename properties of your entity for use externally. Property aliases provide a mechanism to do this, and ERXStandardRestEntityDelegate allows you to define these mappings in your Application properties file.

 ERXRest.[EntityName].[propertyName].alias=someOtherName
 

For example:

 ERXRest.Person.displayName.alias = name
 

In the above example, the we are saying that the "displayName" property of the "Person" entity should be called "name" to users of the service. The entity name in this property should be the actual entity name, not the entity alias if one exists.

View/Update/Insert Properties

There are three types of properties you can control: view, update, and insert. View properties are the set of properties (keys, attributes, relationships, etc) that a particular caller is allowed to view on an object. Insert properties are the properties that a caller is allowed to specify at creation time for a new object. Update properties are the properties that a caller is allowed to update during an update request. Insert and update properties are implicitly view properties, and update properties are implicitly insert properties.

Note that all properties that appear in a properties definition should be "actual" property names, not property aliases. Similarly, all entity names should be the actual entity names and not entity aliases.

If you have already ERXXmlRestResponseWriter (if not, you should), you know that it can define a set of properties that CAN be displayed to your users for any particular entity or keypath (the "detailsProperties"). The properties defined for the renderer only define what the user can possibly see -- it does not deal with security, which is the entity delegate's responsibility. So it is possible to declare that the renderer should show "firstName,lastName,email" for a Person in details, but your view properties may only allow you to see "firstName".

This implementation provides a simple way to define view, insert, and update properties for an entity. These definitions, by default, are fixed for any use of the entity by any user. If you want to dynamically adjust what keypaths users can view, insert, and update based on some more complicated permissions structure, then you can either override the corresponding methods, or extend ERXAbstractRestEntityDelegate instead of this implementation.

Because the view properties are not dynamic by default, it is a common desire to use the detailsProperties declaration from ERXXmlRestResponseWriter as the view properties also. To do this, you can use the the ERXStandardRestEntityDelegate(String entityName) variant of the constructor, or you can use the ERXStandardRestEntityDelegate() constructor and manually call loadDetailsPropertiesAsViewPropertiesForEntityNamed(String entityName) and it will automatically make all details properties view properties.

To define view, insert, and update properties in your Application's Properties file, you can declare:

 ERXRest.[EntityName].viewProperties=property1,property2,property3,...
 ERXRest.[EntityName].insertProperties=property1,property2,property3,...
 ERXRest.[EntityName].updateProperties=property1,property2,property3,...
 

For example:

 ERXRest.BlogPost.viewProperties=author,title,submissionDate,contents
 ERXRest.BlogPost.insertProperties=author,title,contents
 ERXRest.BlogPost.updateProperties=title,contents
 

In the above example, we allow users to see the author, title, submissionDate and contents properties of a BlogPost. However, when they insert, we want to automatically set "submissionDate", so we do not allow that property. Additionally we don't want to allow users to change the original author of a post (note this example is a bit contrived), so we don't include "author" key in the updateProperties.

Author:

mschrag

Constructor Summary

ERXStandardRestEntityDelegate()
Constructs an ERXStandardRestEntityDelegate without an explicit entity reference.

ERXStandardRestEntityDelegate(java.lang.String entityName)
Constructs an ERXStandardRestEntityDelegate with an explicit entity name, and WILL load details properties as view properties.

ERXStandardRestEntityDelegate(java.lang.String entityName, boolean detailsPropertiesAreViewProperties)
Constructs an ERXStandardRestEntityDelegate with an explicit entity name, optionally loading details properties as view properties.

Method Summary

void	addInsertPropertyName(java.lang.String entityName, java.lang.String insertPropertyName) Adds an insert property for the specified entity.
void	addUpdatePropertyName(java.lang.String entityName, java.lang.String updatePropertyName) Adds an update property for the specified entity.
void	addViewPropertyName(java.lang.String entityName, java.lang.String visiblePropertyName) Adds a view property for the specified entity.
boolean	canInsertProperty(com.webobjects.eoaccess.EOEntity entity, com.webobjects.eocontrol.EOEnterpriseObject eo, java.lang.String propertyName, ERXRestContext context) Returns true if propertyName is declared as an insert property.
boolean	canUpdateProperty(com.webobjects.eoaccess.EOEntity entity, com.webobjects.eocontrol.EOEnterpriseObject eo, java.lang.String propertyName, ERXRestContext context) Returns true if propertyName is declared as an update property.
boolean	canViewProperty(com.webobjects.eoaccess.EOEntity entity, java.lang.Object obj, java.lang.String propertyName, ERXRestContext context) Returns true if propertyName is declared as a view property.
protected java.lang.String	defaultIDAttributeName() Returns the default "id" attribute name for all entities.
java.lang.String	entityAliasForEntityNamed(java.lang.String entityName) Returns the entity alias for the given entity name.
protected boolean	hasViewProperties() Returns whether or not there are any view properties.
protected java.lang.String	idAttributeName(com.webobjects.eoaccess.EOEntity entity)
void	inserted(com.webobjects.eoaccess.EOEntity entity, com.webobjects.eocontrol.EOEnterpriseObject eo, ERXRestContext context) Default empty implementation.
protected void	loadDetailsPropertiesAsViewPropertiesForEntityNamed(java.lang.String entityName) Loads the details properties for the specified entity from the configuration for ERXXmlRestResponseWriter and calls addViewPropertyName for each.
protected void	loadInsertPropertiesForEntityNamed(java.lang.String entityName) Loads the insert properties for the specified entity from the property ERXRest.[EntityName].insertProperties and calls addInsertPropertyName for each.
protected void	loadUpdatePropertiesForEntityNamed(java.lang.String entityName) Loads the update properties for the specified entity from the property ERXRest.[EntityName].updateProperties and calls addUpdatePropertyName for each.
protected void	loadViewPropertiesForEntityNamed(java.lang.String entityName) Loads the view properties for the specified entity from the property ERXRest.[EntityName].viewProperties and calls addViewPropertyName for each.
com.webobjects.eoaccess.EOEntity	nextEntity(com.webobjects.eoaccess.EOEntity entity, java.lang.String key) Looks up the key from the property ERXRest.[EntityName].[key].nextEntity .
java.lang.String	propertyAliasForPropertyNamed(com.webobjects.eoaccess.EOEntity entity, java.lang.String propertyName) Returns the property alias for the given property name for the specified entity.
java.lang.String	propertyNameForPropertyAlias(com.webobjects.eoaccess.EOEntity entity, java.lang.String propertyAlias) Returns the property name for the given property alias for the specified entity.
protected com.webobjects.eocontrol.EOQualifier	qualifierFromContext(ERXRestContext context) A shortcut for pulling a qualifier from the "qualifier" form value.
void	setDefaultIDAttributeName(java.lang.String defaultIDAttributeName) Sets the default "id" attribute name for all entities.
protected com.webobjects.foundation.NSArray<com.webobjects.eocontrol.EOSortOrdering>	sortOrderingsFromContext(ERXRestContext context) A shortcut for pulling the sort ordering from the "order" and "direction" form values.
void	updated(com.webobjects.eoaccess.EOEntity entity, com.webobjects.eocontrol.EOEnterpriseObject eo, ERXRestContext context) Default empty implementation.
protected void	updatePropertyAliasForPropertyNamed(java.lang.String entityName, java.lang.String propertyName)

Methods inherited from class er.rest.entityDelegates.ERXAbstractRestEntityDelegate

_cascadingValue, _displayDetailsFromProperties, _displayPropertiesFromProperties, _isEOID, _objectWithKey, _updateArrayFromDocument, _updatePropertiesFromDocument, _updateRelationshipFromDocument, allPossiblePropertyNamesOnEarth, cascadingValue, delete, displayDetails, displayProperties, formatAttributeValue, idForEO, idForNode, initializeEntityNamed, insertObjectFromDocument, isEOID, objectForNode, objectWithKey, objectWithKey, parseAttributeValue, preprocess, processObjectFromDocument, stringIDForEO, takeValueForKey, updateArrayFromDocument, updateObjectFromDocument, valueForKey

Methods inherited from class java.lang.Object

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

Methods inherited from interface er.rest.entityDelegates.IERXRestEntityDelegate

objectsForEntity, visibleObjects

Methods inherited from interface er.rest.entityDelegates.IERXRestSecurityDelegate

canDeleteObject, canInsertObject, canInsertObject, canUpdateObject, canViewObject

Constructor Detail

ERXStandardRestEntityDelegate

public ERXStandardRestEntityDelegate()

Constructs an ERXStandardRestEntityDelegate without an explicit entity reference. loadDetailsPropertiesAsViewPropertiesForEntityNamed, loadViewPropertiesForEntityNamed, loadUpdatePropertiesForEntityNamed, and loadInsertPropertiesForEntityNamed will NOT be called.

ERXStandardRestEntityDelegate

public ERXStandardRestEntityDelegate(java.lang.String entityName,
                                     boolean detailsPropertiesAreViewProperties)

Constructs an ERXStandardRestEntityDelegate with an explicit entity name, optionally loading details properties as view properties. Additionally, loadViewPropertiesForEntityNamed, loadUpdatePropertiesForEntityNamed, and loadInsertPropertiesForEntityNamed WILL be called.

Parameters:

entityName - the name of the entity that this delegate represents

detailsPropertiesAreViewProperties - if true, .detailsProperties will be loaded as .viewProperties

ERXStandardRestEntityDelegate

public ERXStandardRestEntityDelegate(java.lang.String entityName)

Constructs an ERXStandardRestEntityDelegate with an explicit entity name, and WILL load details properties as view properties. Additionally, loadViewPropertiesForEntityNamed, loadUpdatePropertiesForEntityNamed, and loadInsertPropertiesForEntityNamed WILL be called.

Parameters:

entityName - the name of the entity that this delegate represents

Method Detail

setDefaultIDAttributeName

public void setDefaultIDAttributeName(java.lang.String defaultIDAttributeName)

Sets the default "id" attribute name for all entities.

Parameters:

defaultIDAttributeName - the default "id" attribute name for all entities

defaultIDAttributeName

protected java.lang.String defaultIDAttributeName()

Returns the default "id" attribute name for all entities.

Returns:

the default "id" attribute name for all entities

idAttributeName

protected java.lang.String idAttributeName(com.webobjects.eoaccess.EOEntity entity)

Overrides:

idAttributeName in class ERXAbstractRestEntityDelegate

entityAliasForEntityNamed

public java.lang.String entityAliasForEntityNamed(java.lang.String entityName)

Returns the entity alias for the given entity name. This looks in the ERXRest.[EntityName].alias property. If not found, entityName is returned.

Specified by:

entityAliasForEntityNamed in interface IERXRestEntityDelegate

Overrides:

entityAliasForEntityNamed in class ERXAbstractRestEntityDelegate

Parameters:

entityName - the name of the entity

Returns:

the entity alias

propertyAliasForPropertyNamed

public java.lang.String propertyAliasForPropertyNamed(com.webobjects.eoaccess.EOEntity entity,
                                                      java.lang.String propertyName)

Returns the property alias for the given property name for the specified entity. This looks in the ERXRest.[EntityName].[propertyName].alias property. If not found, entityName is returned.

Specified by:

propertyAliasForPropertyNamed in interface IERXRestEntityDelegate

Overrides:

propertyAliasForPropertyNamed in class ERXAbstractRestEntityDelegate

Parameters:

entity - the entity

propertyName - the name of the property

Returns:

the property alias

propertyNameForPropertyAlias

public java.lang.String propertyNameForPropertyAlias(com.webobjects.eoaccess.EOEntity entity,
                                                     java.lang.String propertyAlias)

Returns the property name for the given property alias for the specified entity. This looks in the ERXRest.[EntityName].[propertyName].alias property. If not found, entityName is returned.

Specified by:

propertyNameForPropertyAlias in interface IERXRestEntityDelegate

Overrides:

propertyNameForPropertyAlias in class ERXAbstractRestEntityDelegate

Parameters:

entity - the entity

propertyAlias - the name of the property alias

Returns:

the property name

loadViewPropertiesForEntityNamed

protected void loadViewPropertiesForEntityNamed(java.lang.String entityName)

Loads the view properties for the specified entity from the property ERXRest.[EntityName].viewProperties and calls addViewPropertyName for each.

Parameters:

entityName - the name of the entity to load properties for

loadUpdatePropertiesForEntityNamed

protected void loadUpdatePropertiesForEntityNamed(java.lang.String entityName)

Loads the update properties for the specified entity from the property ERXRest.[EntityName].updateProperties and calls addUpdatePropertyName for each.

Parameters:

entityName - the name of the entity to load properties for

loadInsertPropertiesForEntityNamed

protected void loadInsertPropertiesForEntityNamed(java.lang.String entityName)

Loads the insert properties for the specified entity from the property ERXRest.[EntityName].insertProperties and calls addInsertPropertyName for each.

Parameters:

entityName - the name of the entity to load properties for

loadDetailsPropertiesAsViewPropertiesForEntityNamed

protected void loadDetailsPropertiesAsViewPropertiesForEntityNamed(java.lang.String entityName)

Loads the details properties for the specified entity from the configuration for ERXXmlRestResponseWriter and calls addViewPropertyName for each.

Parameters:

entityName - the name of the entity to load properties for

addViewPropertyName

public void addViewPropertyName(java.lang.String entityName,
                                java.lang.String visiblePropertyName)

Adds a view property for the specified entity.

Parameters:

entityName - the name of the entity

visiblePropertyName - the name of the view property

updatePropertyAliasForPropertyNamed

protected void updatePropertyAliasForPropertyNamed(java.lang.String entityName,
                                                   java.lang.String propertyName)

addUpdatePropertyName

public void addUpdatePropertyName(java.lang.String entityName,
                                  java.lang.String updatePropertyName)

Adds an update property for the specified entity.

Parameters:

entityName - the name of the entity

updatePropertyName - the name of the update property

addInsertPropertyName

public void addInsertPropertyName(java.lang.String entityName,
                                  java.lang.String insertPropertyName)

Adds an insert property for the specified entity.

Parameters:

entityName - the name of the entity

insertPropertyName - the name of the insert property

canInsertProperty

public boolean canInsertProperty(com.webobjects.eoaccess.EOEntity entity,
                                 com.webobjects.eocontrol.EOEnterpriseObject eo,
                                 java.lang.String propertyName,
                                 ERXRestContext context)

Returns true if propertyName is declared as an insert property.

Parameters:

entity - the entity

eo - the object to check

propertyName - the property name to check

context - the rest context

Returns:

true if propertyName is declared as an insert property

canUpdateProperty

public boolean canUpdateProperty(com.webobjects.eoaccess.EOEntity entity,
                                 com.webobjects.eocontrol.EOEnterpriseObject eo,
                                 java.lang.String propertyName,
                                 ERXRestContext context)

Returns true if propertyName is declared as an update property.

Parameters:

entity - the entity

eo - the object to check

propertyName - the property name to check

context - the rest context

Returns:

true if propertyName is declared as an update property

canViewProperty

public boolean canViewProperty(com.webobjects.eoaccess.EOEntity entity,
                               java.lang.Object obj,
                               java.lang.String propertyName,
                               ERXRestContext context)

Returns true if propertyName is declared as a view property.

Parameters:

entity - the entity

obj - the object to check

propertyName - the property name to check

context - the rest context

Returns:

true if propertyName is declared as a view property

hasViewProperties

protected boolean hasViewProperties()

Returns whether or not there are any view properties.

Returns:

whether or not there are any view properties

inserted

public void inserted(com.webobjects.eoaccess.EOEntity entity,
                     com.webobjects.eocontrol.EOEnterpriseObject eo,
                     ERXRestContext context)
              throws ERXRestException,
                     ERXRestSecurityException

Default empty implementation. Extend to do custom insertion processing for the object.

Specified by:

inserted in class ERXAbstractRestEntityDelegate

Parameters:

entity - the entity of the object

eo - the inserted object

context - the rest context

Throws:

ERXRestException - if a general error occurs

ERXRestSecurityException - if a security exception occurs

updated

public void updated(com.webobjects.eoaccess.EOEntity entity,
                    com.webobjects.eocontrol.EOEnterpriseObject eo,
                    ERXRestContext context)
             throws ERXRestException,
                    ERXRestSecurityException

Default empty implementation. Extend to do custom update processing for the object.

Specified by:

updated in class ERXAbstractRestEntityDelegate

Parameters:

entity - the entity of the object

eo - the updated object

context - the rest context

Throws:

ERXRestException - if a general error occurs

ERXRestSecurityException - if a security exception occurs

nextEntity

public com.webobjects.eoaccess.EOEntity nextEntity(com.webobjects.eoaccess.EOEntity entity,
                                                   java.lang.String key)

Looks up the key from the property ERXRest.[EntityName].[key].nextEntity . Extend to provide support for custom non-model properties.

Parameters:

entity - the entity of the object

key - the key of the entity to return an entity definition for

Returns:

the destination entity for the given key (or null if there isn't one)

qualifierFromContext

protected com.webobjects.eocontrol.EOQualifier qualifierFromContext(ERXRestContext context)

A shortcut for pulling a qualifier from the "qualifier" form value.

Parameters:

context - the rest context

Returns:

the requested qualifir

sortOrderingsFromContext

protected com.webobjects.foundation.NSArray<com.webobjects.eocontrol.EOSortOrdering> sortOrderingsFromContext(ERXRestContext context)

A shortcut for pulling the sort ordering from the "order" and "direction" form values.

Parameters:

context - the rest context

Returns:

an array of sort orderings