Overview
Locked domains is a mechanism used by Apache Shindig to isolate individual gadgets from each other as they are rendering on a single container page. By default this is accomplished by rendering each gadget in a separate iframe such that each iframe's src is unique. The web browser will then isolate each gadget because of the Same Origin Policy. Any XHR requests the gadget makes to the Shindig server must then occur on the gadget's locked domain. Other resources, such as images and JavaScript, will utilize a common unlocked domain to increase cacheability in the browser.
The following diagram attempts to illustrate a common deployment. It is not a complete picture but should help to illustrate the basic concept.
Configuration
shindig.properties
Key |
Type |
Default Value |
Description |
|---|---|---|---|
shindig.locked-domain.enabled |
boolean |
false |
Required. Used by HashLockedDomainService. Set to true to enable locked domains. Container specific configuration can be found in container.js |
shindig.locked-domain.lock-security-tokens |
boolean |
false |
Optional. Used by AbstractLockedDomainService. Locks a gadget if it needs a security token. See the javadoc for AbstractLockedDomainService.setLockSecurityTokens(Boolean) for more details. |
container.js
Key |
Type |
Default Value |
Description |
|---|---|---|---|
gadgets.uri.iframe.lockedDomainRequired |
boolean |
false |
Optional. Used by AbstractLockedDomainService. Set to true to force all gadgets to render in a locked domain. |
gadgets.uri.iframe.lockedDomainSuffix |
String |
%authority% |
Optional. Used by HashLockedDomainService. The suffix to be used to construct a locked domain url of the form <hash of gadget url><lockedDomainSuffix>. |
default.domain.unlocked.client |
String |
%host% |
Required. Used within container.js to build other urls, such as the content proxy url. |
default.domain.unlocked.server |
String |
%authority% |
Required. Used within container.js to build other urls, such as js and concat urls. |
Customization
One can customize the locked domain behavior in Shindig by injecting one's own subclass of AbstractLockedDomainService, a subclass of DefaultIframeUriManager, and an implementation of LockedDomainPrefixGenerator.
AbstractLockedDomainService
AbstractLockedDomainService defines several abstract methods that can be easily implemented to create a customized LockedDomainService. In addition to the abstract methods, one can also override AbstractLockedDomainService.isExcludedFromLockedDomain(Gadget, String) to define exclusion behavior for locked domains. By default, no gadget is excluded.
LockedDomainPrefixGenerator
A LockedDomainPrefixGenerator should be injected into one's custom LockedDomainService implementation. The default implementation, HashShaLockedDomainPrefixGenerator, creates a SHA-1 digest of the gadget url to create the prefix for the locked domain. One can implement and inject one's own LockedDomainPrefixGenerator to customize how the locked domain prefixes are generated.
DefaultIframeUriManager
DefaultIframeUriManager.getScheme(Gadget, String) can be overridden to determine the scheme of a particular gadget Url. This can be useful if one wishes to enforce either http or https for locked domain gadgets. By default this method returns null and the gadget iframe Url will be scheme-relative.