com.ibm.jaggr.core.config

Interface IConfig

All Known Implementing Classes:

ConfigImpl

public interface IConfig

This interface encapsulates an aggregator configuration. An aggregator configuration specifies the AMD module paths, packages and aliases that are used by an application, by relating module ids to server resource URIs. The configuration is specified using a JavaScript file who's structure and format closely mirrors the client side AMD loader config JavaScript, except that instead of relating module ids to resource on the web, it relates module ids to resource on the server.

The static JavaScript configuration file is specified by the config init-param in the servlet definition.

In addition to data specified in a static JavaScript file, applications may optionally modify the configuration at runtime by registering an implementation of IConfigModifier as an OSGi service with the name parameter set to the aggregator name.

The URIs used in this interface can point to any type of resource accessible on the server, but there must be a IResource implementation available that supports the URI scheme.

In addition to locating server resources requested by the client-side loader, the module id to resource URI mappings specified in this config are used when scanning for modules in order to build the dependency graph for expanding module dependencies. Only the paths and packages properties are used for this purpose, so these properties must include all the module paths used in the application. The base URI property is only used to resolve relative paths specified in paths and packages. It is NOT scanned for modules when building the dependency graph.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	IConfig.IAlias Interface for a config alias.
static interface	IConfig.IPackage Interface for a server-side AMD module package.
static class	IConfig.Location Class for a resource location.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ALIASES_CONFIGPARAM Static constant specifying the name of the aliases config param
static String	BASEURL_CONFIGPARAM Static constant specifying the name of the baseUrl config param
static String	CACHEBUST_CONFIGPARAM Static constant specifying the name of the cacheBust config param
static String	COERCEUNDEFINEDTOFALSE_CONFIGPARAM Static constant specifying the name of the coerceUndefinedToFalse config param
static String	DEPS_CONFIGPARAM Static constant specifying the name of the deps config param
static String	DEPSINCLUDEBASEURL_CONFIGPARAM Static constant specifying the name of the depsIncludeBaseUrl config param
static String	EXPIRES_CONFIGPARAM Static constant specifying the name of the expires config param
static String	HAS_CONFIGPARAM Static constant specifying the name of the has config property
static String	JSPLUGINDELEGATORS_CONFIGPARAM Static constant specifying the name of the jsPluginDelegators config param.
static Object	NOT_FOUND Value returned from getProperty(String, Class) if the property is not found.
static String	NOTICE_CONFIGPARAM Static constant specifying the name of the notice config param
static String	PACKAGES_CONFIGPARAM Static constant specifying the name of the packages config param
static String	PATHS_CONFIGPARAM Static constant specifying the name of the paths config param
static String	PKGLOCATION_CONFIGPARAM Static constant specifying the name of the packages' config param location property
static String	PKGMAIN_CONFIGPARAM Static constant specifying the name of the packages' config param main property
static String	PKGMAIN_DEFAULT Static constant specifying the main property's default value
static String	PKGNAME_CONFIGPARAM Static constant specifying the name of the packages' config param name property
static String	TEXTPLUGINDELEGATORS_CONFIGPARAM Static constant specifying the name of the textPluginDelegators config param.

Method Summary

Methods

Modifier and Type	Method and Description
List<IConfig.IAlias>	getAliases() Returns the list of aliases specified by the aliases config param.
IConfig.Location	getBase() Returns the value of the baseUrl config param.
String	getCacheBust() Returns the value of the cacheBust config param.
Object	getConfigScope() Returns the scope object used to evaluate the config JavaScript.
URI	getConfigUri() Returns the URI for the config JavaScript file from which this config was read.
Features	getDefaultFeatures(String url) Returns the default features specified using the HAS_CONFIGPARAM config param.
List<String>	getDeps() Deprecated.
int	getExpires() Returns the value of the expires config param as an integer.
Set<String>	getJsPluginDelegators() Returns the list of plugin names specified with the JSPLUGINDELEGATORS_CONFIGPARAM config param.
String	getNotice() Returns the content of the resource specified by the notice config param.
Map<String,IConfig.Location>	getPackageLocations() Returns an ordered mapping of module ids to resource locations for all of the packages locations defined in this config.
Map<String,IConfig.IPackage>	getPackages() Returns the packages specified by the packages config param.
Map<String,IConfig.Location>	getPaths() Returns the path mappings for module names to resource URIs specified by the paths config param.
Object	getProperty(String propname, Class<?> hint) Returns the value of the named config property.
Object	getRawConfig() Returns the raw config data after the config has been modified by any IConfigModifier services that have been registered for the aggregator that this config is associated with, and after any string substitutions have been performed.
Set<String>	getTextPluginDelegators() Returns the list of plugin names specified with the TEXTPLUGINDELEGATORS_CONFIGPARAM config param.
boolean	isCoerceUndefinedToFalse() Returns the value of the coerceUndefinedToFalse config param.
boolean	isDepsIncludeBaseUrl() Returns the value of the depsIncludeBaseUrl config param.
long	lastModified() Returns the last-modified date of the config JavaScript file at the time that it was read in order to produce this config object.
URI	locateModuleResource(String mid) Returns the URI to the resource on the server for the specified module id, or null if the resource cannot be located.
String	resolve(String name, Features features, Set<String> dependentFeatures, StringBuffer sb, boolean resolveAliases) Legacy method that calls resolve(String, Features, Set, StringBuffer, boolean, boolean) with resolveHasPlugin equal to true.
String	resolve(String name, Features features, Set<String> dependentFeatures, StringBuffer sb, boolean resolveAliases, boolean evaluateHasPluginConditionals) Resolves a module id by applying the following mappings in the indicated order.
String	toString() Returns the stringized source code representation of the raw config returned by getRawConfig().

Field Detail

NOT_FOUND

static final Object NOT_FOUND

Value returned from getProperty(String, Class) if the property is not found.

PACKAGES_CONFIGPARAM

static final String PACKAGES_CONFIGPARAM

Static constant specifying the name of the packages config param

See Also:

Constant Field Values

PATHS_CONFIGPARAM

static final String PATHS_CONFIGPARAM

Static constant specifying the name of the paths config param

See Also:

Constant Field Values

ALIASES_CONFIGPARAM

static final String ALIASES_CONFIGPARAM

Static constant specifying the name of the aliases config param

See Also:

Constant Field Values

DEPS_CONFIGPARAM

static final String DEPS_CONFIGPARAM

Static constant specifying the name of the deps config param

See Also:

Constant Field Values

BASEURL_CONFIGPARAM

static final String BASEURL_CONFIGPARAM

Static constant specifying the name of the baseUrl config param

See Also:

Constant Field Values

NOTICE_CONFIGPARAM

static final String NOTICE_CONFIGPARAM

Static constant specifying the name of the notice config param

See Also:

Constant Field Values

PKGNAME_CONFIGPARAM

static final String PKGNAME_CONFIGPARAM

Static constant specifying the name of the packages' config param name property

See Also:

Constant Field Values

PKGLOCATION_CONFIGPARAM

static final String PKGLOCATION_CONFIGPARAM

Static constant specifying the name of the packages' config param location property

See Also:

Constant Field Values

PKGMAIN_CONFIGPARAM

static final String PKGMAIN_CONFIGPARAM

Static constant specifying the name of the packages' config param main property

See Also:

Constant Field Values

PKGMAIN_DEFAULT

static final String PKGMAIN_DEFAULT

Static constant specifying the main property's default value

See Also:

Constant Field Values

DEPSINCLUDEBASEURL_CONFIGPARAM

static final String DEPSINCLUDEBASEURL_CONFIGPARAM

Static constant specifying the name of the depsIncludeBaseUrl config param

See Also:

Constant Field Values

COERCEUNDEFINEDTOFALSE_CONFIGPARAM

static final String COERCEUNDEFINEDTOFALSE_CONFIGPARAM

Static constant specifying the name of the coerceUndefinedToFalse config param

See Also:

Constant Field Values

EXPIRES_CONFIGPARAM

static final String EXPIRES_CONFIGPARAM

Static constant specifying the name of the expires config param

See Also:

Constant Field Values

CACHEBUST_CONFIGPARAM

static final String CACHEBUST_CONFIGPARAM

Static constant specifying the name of the cacheBust config param

See Also:

Constant Field Values

HAS_CONFIGPARAM

static final String HAS_CONFIGPARAM

Static constant specifying the name of the has config property

See Also:

Constant Field Values

TEXTPLUGINDELEGATORS_CONFIGPARAM

static final String TEXTPLUGINDELEGATORS_CONFIGPARAM

Static constant specifying the name of the textPluginDelegators config param.

See Also:

Constant Field Values

JSPLUGINDELEGATORS_CONFIGPARAM

static final String JSPLUGINDELEGATORS_CONFIGPARAM

Static constant specifying the name of the jsPluginDelegators config param.

See Also:

Constant Field Values

Method Detail

getBase

IConfig.Location getBase()

Returns the value of the baseUrl config param. This is the base URI to use for all relative URIs specified in this config. If baseUrl is not absolute, then it is assumed to be relative to the root of the bundle defining the servlet. Note that the property name specifies Url, with a lower-case L, instead of URI with an upper-case i, to maintain symmetry with the client-side config. Files and folders located under the folder specified by baseUrl are not scanned when the Aggregator builds the module dependency map used for require list expansion unless the depsIncludeBaseUrl config param is specified with a value of true.

Returns:

The base location

getPaths

Map<String,IConfig.Location> getPaths()

Returns the path mappings for module names to resource URIs specified by the paths config param. The path URIs are assumed to be relative to baseUrl, unless the URI starts with a "/" or specfies a protocol.

Returns:

The paths map

getPackages

Map<String,IConfig.IPackage> getPackages()

Returns the packages specified by the packages config param.

Returns:

The packages map

See Also:

IConfig.IPackage

getAliases

List<IConfig.IAlias> getAliases()

Returns the list of aliases specified by the aliases config param.

Returns:

The list of aliases

isDepsIncludeBaseUrl

boolean isDepsIncludeBaseUrl()

Returns the value of the depsIncludeBaseUrl config param.

If specified with a value of true, then the files and folders under the directory specified by baseUrl will be scanned when the Aggregator builds the module dependency map used for require list expansion. The default value is false.

Returns:

The value of the depsIncludeBaseUrl config param

isCoerceUndefinedToFalse

boolean isCoerceUndefinedToFalse()

Returns the value of the coerceUndefinedToFalse config param.

If true, then the Aggregator will treat undefined features as if they were defined with a value of false. This applies to has.js feature trimming of javascript code. If this value is false, then has.js conditionals for undefined features are left unchanged. If the value is true, then conditionals involving undefined features are trimmed based on the value of the feature evaluating to false. The default value for this option is false.

Returns:

the value of the coerceUndefinedToFalse config param

getExpires

int getExpires()

Returns the value of the expires config param as an integer.

If specified, this value will be used to specified in the Cache-Control:max-age response header. If the value is zero (the default), then the Cache-Control:maz-age header will not be specified in the response.

Returns:

The value of the expires config param or zero

getDeps

@Deprecated
List<String> getDeps()

Deprecated.

Returns the value of the deps config param as a list of strings.

This property is analogous to the client-side AMD config deps property, which specifies the modules that should be loaded before the application's require.callback method is called. On the server, this property is used to trim the list of expanded dependencies for all require list expansions. Any modules listed here, along with the nested dependencies of the listed modules, will be excluded from expanded require lists for all require() calls in the application. In general, the client-side and server-side AMD configs should both specify the same modules in the deps property, although, this is not a requirement.

If the deps property is not specified in the config, then this function returns an empty list.

This method is deprecated in favor of IRequestedModuleNames.getExcludes() which is specified by Aggregator generated requests based on the modules requested in the boot layer for the application.

Returns:

The list of module names specified in the deps config param

getNotice

String getNotice()

Returns the content of the resource specified by the notice config param.

This resource contains the notice text that will be output at the beginning of every Aggregator response. The notice text should be in the form of a javascript block comment. The Aggregator does not do any processing on the notice text.

Returns:

the notice string

getCacheBust

String getCacheBust()

Returns the value of the cacheBust config param.

This is an arbitrary string specified by the application that is associated with the serialized meta-data for aggregator caches and the module dependency maps. When these data structures are de-serialized on server restarts, the saved value is compared against the value that is read from the current config, and if the values don't match, then the de-serialized data is discarded and the caches and dependency maps are deleted and rebuilt.

The value of this string is also used for the client-side cacheBust property in the loader extension combo config if it is not specified by the client.

Returns:

The value of the cacheBust config param

locateModuleResource

URI locateModuleResource(String mid)

Returns the URI to the resource on the server for the specified module id, or null if the resource cannot be located.

Parameters:

mid - The module id

Returns:

The URI for the module.

getPackageLocations

Map<String,IConfig.Location> getPackageLocations()

Returns an ordered mapping of module ids to resource locations for all of the packages locations defined in this config.

Returns:

The defined package Locations

lastModified

long lastModified()

Returns the last-modified date of the config JavaScript file at the time that it was read in order to produce this config object.

Returns:

The last-modified date

getConfigUri

URI getConfigUri()

Returns the URI for the config JavaScript file from which this config was read. Note that the returned URI may specify an aggregator specific scheme such as namedbundleresource, so you should first use IAggregator.newResource(URI) to convert the URI into an IResource and then use IResource.getURI() to obtain a platform URI that you can use to open the file, etc.

Returns:

The config JavaScript URI

getTextPluginDelegators

Set<String> getTextPluginDelegators()

Returns the list of plugin names specified with the TEXTPLUGINDELEGATORS_CONFIGPARAM config param. Loader plugins specified here delegate the loading of the resources they handle to the text module loader. When doing server-side expansion of module dependencies for a bootstrap layer, resources specifying loader plugins included in this list will be included in the response as a text resource.

Returns:

The list of loader plugins that delegate to the text module loader.

getJsPluginDelegators

Set<String> getJsPluginDelegators()

Returns the list of plugin names specified with the JSPLUGINDELEGATORS_CONFIGPARAM config param. Loader plugins specified here delegate the loading of the resources they handle to the javascript module loader (e.g. the i18n plugin). When doing server-side expansion of module dependencies for a bootstrap layer, resources specifying loader plugins included in this list will be included in the response as a javascript resources.

Returns:

The list of loader plugins that delegate to the javascript module loader.

getDefaultFeatures

Features getDefaultFeatures(String url)

Returns the default features specified using the HAS_CONFIGPARAM config param. These are default values for features that are overridden by any features defined in the request.

The default features are specified as a property map of name/value pairs. If the value of a property is a JavaScript function, then the function is invoked at the time this method is called to evalute the value of the feature. The function takes one formal parameter which is the request URL, and the returned value will be coerced to a boolean before being assigned as the value of the feature.

Parameters:

url - the request URL, or null.

Returns:

The default features.

getRawConfig

Object getRawConfig()

Returns the raw config data after the config has been modified by any IConfigModifier services that have been registered for the aggregator that this config is associated with, and after any string substitutions have been performed. The runtime type of the object is dependent upon the config processor implementation.

The returned object is read-only, so it may not be modified.

Returns:

The raw config data for this config object

See Also:

IConfigModifier

getConfigScope

Object getConfigScope()

Returns the scope object used to evaluate the config JavaScript. The runtime type of this object is depenedent upon the config processor implementation.

Returns:

The config scope object.

getProperty

Object getProperty(String propname,
                 Class<?> hint)
                   throws IllegalArgumentException

Returns the value of the named config property. If the value is not a primitive type (String, Number, Boolean), then this function will attempt to convert the property value to the class specified by hint.

The value returned may be one of the following:

• Boolean
• Number
• String
• An implementation specific representation of the value native to the config processor if the value is not one of the above and hint is null
• An object of the type specified by hint if the value can be converted
• null, if the value is null or undefined
• NOT_FOUND

Parameters:

propname - the name of the config property

hint - the class to try to convert the value to if not a primitive type

Returns:

the value of the property (may be null).

Throws:

IllegalArgumentException

toString

String toString()

Returns the stringized source code representation of the raw config returned by getRawConfig(). Changes in this string may be used to track config changes. This method is preferable to using lastModified() because external factors besides the config file (such as changes in the values of string substitution variables) may result in config changes.

Overrides:

toString in class Object

Returns:

The stringized JavaScript source representation of the current config

resolve

String resolve(String name,
             Features features,
             Set<String> dependentFeatures,
             StringBuffer sb,
             boolean resolveAliases,
             boolean evaluateHasPluginConditionals)

Resolves a module id by applying the following mappings in the indicated order.

• If resolveAliases is true, then call any alias resolvers to resolve module name aliases
• If the module id specifies a has plugin and the has feature(s) are contained in the feature set provided in the request, then evaluate the has plugin expression to obtain the mapped module id.
• If the module id matches a package name, then map to the package main module id.

Parameters:

name - The module name to resolve

features - Features that are defined in the request

dependentFeatures - Output - Set of feature names that the returned value is conditioned on. Used for cache management.

sb - If not null, then a reference to a string buffer that can be used to specify debug/diagnostic information about the module name resolution. For example, the resolver may indicate that alias resolution was not performed due to a missing required feature.

resolveAliases - If true, then module name aliases will be resolved

evaluateHasPluginConditionals - If true, then attempt to evaluate the has plugin conditionals using the features provided in features, potentially eliminating the has! loader plugin from the returned value if all features can be resolved. If false, then the conditionals are retained in the result, although the expression may change if new conditionals are introduced by alias resolution.

Returns:

The resolved module id. If the module id is unchanged, then name should be returned.

resolve

String resolve(String name,
             Features features,
             Set<String> dependentFeatures,
             StringBuffer sb,
             boolean resolveAliases)

Legacy method that calls resolve(String, Features, Set, StringBuffer, boolean, boolean) with resolveHasPlugin equal to true.

Parameters:

name - The module name to resolve

features - Features that are defined in the request

dependentFeatures - Output - Set of feature names that the returned value is conditioned on. Used for cache management.

sb - If not null, then a reference to a string buffer that can be used to specify debug/diagnostic information about the module name resolution. For example, the resolver may indicate that alias resolution was not performed due to a missing required feature.

resolveAliases - If true, then module name aliases will be resolved

Returns:

the resolved module name