The Server side AMD Config file

The server-side AMD configuration is a JavaScript object that closely mirrors the client-side AMD configuration as detailed on the RequreJS web site and defines the paths and packages that relate AMD module identifiers to JavaScript and other resources, however, instead of specifying web resources, the server-side AMD config specifies URIs to resources on the server. The config file itself is specified as a resource URI. If the URI is not absolute (i.e. protocol specified), then the it is assumed to reside in the OSGi bundle that contains the plugin.xml defining the servlet. Server-side resources are specified using Universal Resource Identifiers (URIs) as specified by the java.net.URI class. JAGGR provides support for URIs using the standard file protocol for files that reside on the server's file system, and the non-standard, JAGGR defined, namedbundleresource protocol for resources residing in OSGi bundles.

The URI to the server-side AMD config file is specified using the config servlet init-param in the element defining the servlet.

The namedbundleresource protocol

The namedbundleresource protocol allows resources to be specified using the bundle symbolic name that the resource is contained in. A namedbundleresource URI looks similar to the following:

namedbundleresource://org.dojo.dojo-1.7/dojo

which specifies the resource path dojo within the OSGi bundle with the symbolic name org.dojo.dojo-1.7. URIs specified using the namedbundleresource protocol are not universal because multiple resources residing in different bundles using the same symbolic name may exist, and which resource the URI resolves to depends on the behavior of the OSGi class loader as it relates to resolving bundles. This ambiguity violates the rules governing URIs. It is, never the less, convenient to be able to specify resources that reside in named bundles using the URI syntax, so the Aggregator supports the use of the namedbundleresource protocol for URIs specified within the server-side AMD config file. The ambiguity around which bundle to use is dealt with by ensuring that the class loader of the application's bundle (the bundle containing the plugin.xml defining the servlet) is always used to load the bundle whose name is specified in the host part of the URI.

Other URI protocols

The Aggregator may be extended using the com.ibm.servlets.amd.aggregator.resourcefactory extension point to support additional URI protocols, providing the ability to extend support to include resources residing within jar files, databases, etc. The default file and namedbundleresource protocols are supported using classes that implement this extension. Variable property substitution

Strings of the form ${property-name} may appear anywhere within the config JavaScript and will be replaced with the value of the named property. The value is obtained by calling BundleContext.getPropery() using the BundleContext of the contributing bundle, or if the named property is not defined there, then by calling any registered OSGi services that support the com.ibm.servlets.amd.aggregator.IVariableResolver interface. Variable property substitution is performed before script evaluation. If a value cannot be found for a named property, then the string is left un-modified.

Scoped variables

When the server-side config javascript is being evaluated, the following JavaScript variables are defined and in scope, and may be referenced by JavaScript expressions in your config:

initParams - An object of the name-value pairs defined in the servlet init-params
options - An object of the name-value pairs defined in the Aggregator Options.
headers - An object of the name-value pairs specified in the bundle manifest for the contributing bundle (i.e. the bundle that instantiated the servlet).
console - An object containing logging methods such as error, warn, info and log.  These methods can be used to write messages to the server logs from javascript code in the config.

Override URIs

The baseUrl, paths and location properties specify resource URIs which may be either a string value, or a two element array of strings specifying primary and override URIs. The idea behind override URIs is to facilitate product customization by supporting a location on the file system where customized resources may be placed. Resources that exist in the override locations will be used instead of the corresponding resources in the location specified by the primary URI. In this scenario, the primary URI typically specifies an OSGi bundle, using the namedbundleresource URI scheme, while the override URI specifies a customization area on the server's file system.

Config properties