Wrap handler elements

The <WrapHandler> element in security-config.xml defines complex security permissions on an entity. The wrap handler “wraps around” the permission conditions of the associated handler. The associated handler type must not be object-based, meaning that it must be one of the following:

  • <StaticHandler>
  • <WrapHandler>

It is not possible to create a security handler that takes an object using a <WrapHandler> element. A wrap security handler always create a new static handler.

There is no limit to the number of <WrapHandler> elements that can exist in security-config.xml. Each <WrapHandler> element can contain zero to many <SystemPermType> elements.

A <WrapHandler> element must come after the <Handler> element that defines the permission referenced by wrapPermKey. The associated handler can be another <WrapHandler>. It is possible to cascade <WrapHandler> elements.

This element has the following syntax.

<WrapHandler entity="entity" permKey="perm" wrapPermKey="wrapPerm" desc="..." noPermissionDisplayKey="key">
  <SystemPermType code="code"/>
  ...
</WrapHandler>

You access this permission in code as perm.entity.perm. This syntax has the following meaning:

  • entity – The business object or entity on which the permission acts.
  • perm – The permission given for this entity.

The attributes on the various elements have the following meanings.

Element

Attribute

Required

Description

WrapHandler

entity

Yes

The entity type on which this security handler acts.

permKey

Yes

The application permission to grant.

wrapPermKey

Yes

The associated permission being wrapped. You must declare the permission referenced by the wrapPermKey earlier in security-config.xml than this <WrapHandler> element.

desc

No

A human-readable description of the permission.

noPermissionDisplayKey

No

A display key that provides the text to show if the user does not have a required permission.

SystemPermType

code

Yes

A code value defined in the SystemPermissionType typelist.

The following example illustrates a <StaticHandler> element with two cascading <WrapHandler> elements following it. 

// Static Handler - ViewProfiler permission
<StaticHandler entity="User" permKey="ViewProfiler" noPermissionDisplayKey="No access to ViewProfiler.">
  <SystemPermType code="internaltools"/>
  <SystemPermType code="toolsProfilerview"/>
</StaticHandler>

 //First Wrap Handler - EditProfiler permission
<WrapHandler entity="User" permKey="EditProfiler" wrapPermKey="ViewProfiler" noPermissionDisplayKey="No access to EditProfiler.">
  <SystemPermType code="internaltools"/>
  <SystemPermType code="toolsProfileredit"/>
</WrapHandler>

 //Second Wrap Handler - EditWebserviceProfiler permission
<WrapHandler entity="User" permKey="EditWebserviceProfiler" wrapPermKey="EditProfiler" noPermissionDisplayKey="No access to EditWebServiceProfiler.">
  <SystemPermType code="toolsProfilerwebserviceedit"/>
</WrapHandler>

This sequence of handlers does the following:

  1. The first wrap handler verifies that the user meets the security criteria defined in the handler specified by its wrapPermKey attribute (ViewProfiler). If the user has an assigned role that contains any of the system permissions specified by the ViewProfiler handler, the handler permits the user to have the EditProfiler application permission. If the user does not have such a role, she receives an error message.
  2. The second wrap handler checks to see that the user meets the security criteria defined in the handler specified by its wrapPermKey attribute (EditProfiler). If the user has an assigned role that contains the toolsProfilerwebserviceedit permission, the handler permits the user to have the EditWebserviceProfiler application permission. If the user does not have such a role, she receives an error message.

Wrap handlers specify AND conditions

Wrap security handlers define Boolean AND conditions. Using the example shown previously, the sequence of security handlers evaluates the following set of conditions: 

(perm.System.internaltools OR perm.System.toolsProfilerview) 
AND (perm.System.internaltools OR perm.System.toolsProfilerEdit) 
AND (permission.System.toolsProfilerwebserivceedit)

For this compound condition to evaluate to true, all of the following conditions must be true:

  • The user must have a role that contains either the interntools or toolsProfilerview system permission as specified in ViewProfiler static handler.
  • The user must have a role that contains either the interntools or toolsProfileredit system permission as specified in the EditProfiler wrap handler.
  • The user must have a role that contains the toolsProfilerwebservicesedit system permission as specified in the EditWebServiceProfiler wrap handler.

Only if the user meets all sets of security criteria does the security handler permit the user to have the specified application permission (EditwebserviceProfiler).

See also