com.ibm.jaggr.core

Interface IAggregator

All Known Implementing Classes:

AbstractAggregatorImpl

public interface IAggregator

Interface for the AMD Aggregator. Provides accessors to other aggregator components and some service methods. Implementors of this interface extend HttpServlet, so they are created by the framework when a servlet implementing this interface is instanciated.

The aggregator registers as an OSGi service using this interface and the servlet alias as the name service property.

When servicing requests, a reference to the aggregator may be obtained from the request attribute named AGGREGATOR_REQATTRNAME. It may also be obtained from the session context attributes using the same name.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	IAggregator.SubstitutionTransformer Transformer interface used by substituteProps(String, SubstitutionTransformer).

Field Summary

Fields

Modifier and Type	Field and Description
static String	AGGREGATOR_REQATTRNAME HTTP request attribute name for the IAggregator instance associated with a given request
static String	CONCURRENTMAP_REQATTRNAME Name of the request attribute which holds an instance of a ConcurrentMap which can be used by module builders to store request specific properties in a thread-safe way.

Method Summary

Methods

Modifier and Type	Method and Description
javax.servlet.http.HttpServlet	asServlet() Returns this instance of the aggregator as a HttpServlet.
Future<?>	buildAsync(Callable<?> builder, javax.servlet.http.HttpServletRequest request) Runs the specified builder on an asynchronous thread and returns a Future to the result.
ICacheManager	getCacheManager() Returns the cache manager object for this aggregator.
IConfig	getConfig() Returns the config object for this aggregator.
javax.servlet.http.HttpServletRequest	getCurrentRequest() Returns the request object currently being processed.
IDependencies	getDependencies() Returns the dependencies object for this aggregator.
IExecutors	getExecutors()
Iterable<IAggregatorExtension>	getExtensions(String extensionPointId) Returns an Iterable for the collection of aggregator extensions identified by extensionPointId.
InitParams	getInitParams() Returns the servlet init-params for this aggregator.
IModuleBuilder	getModuleBuilder(String mid, IResource res) Returns an IModuleBuilder for the specified arguments.
String	getName() Returns the name of the servlet implementing this interface.
IOptions	getOptions() Returns the options object for this aggregator.
IPlatformServices	getPlatformServices() Get the IPlatformServices implementation for this aggregator.
IResourceFactory	getResourceFactory(org.apache.commons.lang3.mutable.Mutable<URI> uri) Returns a new IResourceFactory for the specified URI.
IHttpTransport	getTransport() Returns the HTTP transport in use by this object
File	getWorkingDirectory() Returns this aggregator's working directory.
IGzipCache	newGzipCache() Factory method for IGZipCache
ILayerCache	newLayerCache() Factory method for ILayerCache
IModule	newModule(String mid, URI uri) Factory method for IModule instances.
IModuleCache	newModuleCache() Factory method for IModuleCache
IResource	newResource(URI uri) Returns a new IResource for the specified URI.
boolean	reloadConfig() Reloads the config data using the latest values in the config file specified in the config init-param of the servlet.
IResource	runConverters(IResource res) Run the registered resource converters against the specified resource.
String	setForceError(String forceError) Command provider function for setting forced errors in development mode.
String	substituteProps(String str) Performs substitution of variable names of the form ${name} with the values defined in java system properties, or with the value returned by a registered variable resolver that implements the interface IVariableResolver.
String	substituteProps(String str, IAggregator.SubstitutionTransformer transformer) Like substituteProps(String), but allows the caller to specify a transformer class to process the substitution values.

Field Detail

AGGREGATOR_REQATTRNAME

static final String AGGREGATOR_REQATTRNAME

HTTP request attribute name for the IAggregator instance associated with a given request

CONCURRENTMAP_REQATTRNAME

static final String CONCURRENTMAP_REQATTRNAME

Name of the request attribute which holds an instance of a ConcurrentMap which can be used by module builders to store request specific properties in a thread-safe way.

Method Detail

getName

String getName()

Returns the name of the servlet implementing this interface. This is same as the value of the alias attribute in the <servlet> element of the plugin.xml for the bundle that defines the servlet.

Returns:

The name of the servlet.

getConfig

IConfig getConfig()

Returns the config object for this aggregator. The aggregator config is specified using the config servlet init-param. The URI specified by this init-param points to a server side AMD config file that specifies the aggregator config propertes using JSON format in the same way that the client side loader config JSON specifies the AMD configuration for the loader on the client. \

Returns:

The config object for this aggregator

getOptions

IOptions getOptions()

Returns the options object for this aggregator. Options are specified in the server wide aggregator.properties file, located in the home directory of the user that launched the server.

Returns:

The current aggregator options.

getExecutors

IExecutors getExecutors()

getCacheManager

ICacheManager getCacheManager()

Returns the cache manager object for this aggregator. The cache manager provides methods for asynchronously maintaining cached resources.

Returns:

The cache manager for this aggregator

getDependencies

IDependencies getDependencies()

Returns the dependencies object for this aggregator. Used for expanding module dependencies.

Returns:

The dependencies object for this aggregator.

getTransport

IHttpTransport getTransport()

Returns the HTTP transport in use by this object

Returns:

the HTTP transport

setForceError

String setForceError(String forceError)

Command provider function for setting forced errors in development mode.

Parameters:

forceError - the error parameters. See ForcedErrorResponse.ForcedErrorResponse(String) for description.

Returns:

a string that will be displayed on the console.

getResourceFactory

IResourceFactory getResourceFactory(org.apache.commons.lang3.mutable.Mutable<URI> uri)

Returns a new IResourceFactory for the specified URI. The aggregator will create the new resource using one of the registered resource factories.

The aggregator will select the factory from among the registered IResourceFactory extensions by testing the provided uri against the scheme attribute of each of the registered resource factories as follows:

Iterate through the registered resource factory extensions looking for extensions that specify a scheme attribute matching the scheme of uri or a scheme attribute of *. For each matching extension, call the IResourceFactory.handles(URI) method and if the method returns true, then call the IResourceFactory.newResource(URI) method to create the new resource.

The iteration order of the resource factories is determined by the order that resourcefactories init-params are declared within the servlet element defining the aggregator servlet, the order that the factory elements are declared in the resource factory extensions within the plugin.xml{s}, and on the insertion positions of extensions registered programatically using IExtensionInitializer.IExtensionRegistrar.registerExtension(java.lang.Object, java.util.Properties, com.ibm.jaggr.core.InitParams, java.lang.String, java.lang.String, com.ibm.jaggr.core.IAggregatorExtension).

The registered resource factory extensions may be obtained by calling getExtensions(String);

If a satisfactory resource factory cannot be found, then null is returned.

Parameters:

uri - (Input/Output) A mutable reference to the input uri which may be modified to reference a different uri for the same resource if the uri needs to be transformed in order to match to a resource factory (e.g. a relative uri transformed into an absolute uri).

Returns:

The resource factory for the specified URI, or null

newResource

IResource newResource(URI uri)

Returns a new IResource for the specified URI. The aggregator will create the new resource using the resource factory obtained by calling getResourceFactory(Mutable).

This method may return an instance of NotFoundResource if a resource factory for the URI cannot be found.

This method calls runConverters(IResource) against the resource obtained from the resource factory before returning the result.

Parameters:

uri - The URI for the resource

Returns:

The newly created resource object.

runConverters

IResource runConverters(IResource res)

Run the registered resource converters against the specified resource. This method returns either the specified resource or new resource if the resource is converted.

Note that this method is called automatically by newResource(URI), so it is generally not necessary to call this method directly.

Parameters:

res - the resource to run converters against

Returns:

the converted resource, or res if no conversion is applied.

getModuleBuilder

IModuleBuilder getModuleBuilder(String mid,
                              IResource res)

Returns an IModuleBuilder for the specified arguments. The aggregator will select the builder from among the registered module builder extensions by testing the provided mid and res arguments against the attributes for each of the registered extensions as follows:

Iterate through the registered module builder extensions looking for extensions that specify an extension attribute that matches the file extension of the resource specified by res or an extension attribute of *. For each matching module builder extension, if the extension does not specify a plugin attribute or the value of the plugin attribute matches the plugin specified by mid (if any), then call the module builder's IModuleBuilder.handles(String, IResource) method. If the method returns true, then the module builder is returned to the caller.

The iteration order of the module builders is determined by the order that modulebuilders init-params are declared within the servlet element defining the aggregator servlet, the order that the builder elements are declared in the module builder extensions within the plugin.xml{s}, and on the insertion positions of extensions registered programatically using IExtensionInitializer.IExtensionRegistrar.registerExtension(java.lang.Object, java.util.Properties, com.ibm.jaggr.core.InitParams, java.lang.String, java.lang.String, com.ibm.jaggr.core.IAggregatorExtension).

The registered module builder extensions may be obtained by calling getExtensions(String).

Parameters:

mid - The module id for the module to be built

res - The resource for the module

Returns:

The module builder for the source, or null if no module builder can be found.

getInitParams

InitParams getInitParams()

Returns the servlet init-params for this aggregator. The servlet init-params are defined using <init-param> elements within the <servlet> element in the plugin.xml

Returns:

The servlet init-params

getWorkingDirectory

File getWorkingDirectory()

Returns this aggregator's working directory. This is the location on the file system where the aggregator stores cache files and serialized objects.

Returns:

The working directory

reloadConfig

boolean reloadConfig()
                     throws IOException

Reloads the config data using the latest values in the config file specified in the config init-param of the servlet.

Any services registered using the IConfigListener interface are notified.

Returns:

True if the config has been modified since it was last loaded.

Throws:

IOException

asServlet

javax.servlet.http.HttpServlet asServlet()

Returns this instance of the aggregator as a HttpServlet.

Returns:

The aggregator as a HttpServlet

getExtensions

Iterable<IAggregatorExtension> getExtensions(String extensionPointId)

Returns an Iterable for the collection of aggregator extensions identified by extensionPointId. This includes extensions obtained from the eclipse extension registry, as well as extensions registered though the IExtensionInitializer.IExtensionRegistrar interface.

Parameters:

extensionPointId - The extension point id for the extensions to be returned, or null for all extensions.

Returns:

An Iterable to the collection of matching extensions.

newModule

IModule newModule(String mid,
                URI uri)

Factory method for IModule instances.

Parameters:

mid - the module id

uri - the URI to the module source

Returns:

the new IModule instance

newLayerCache

ILayerCache newLayerCache()

Factory method for ILayerCache

Returns:

the new ILayerCache instance

newModuleCache

IModuleCache newModuleCache()

Factory method for IModuleCache

Returns:

the new IModuleCache instance

newGzipCache

IGzipCache newGzipCache()

Factory method for IGZipCache

Returns:

the new IGzipCache instance

substituteProps

String substituteProps(String str)

Performs substitution of variable names of the form ${name} with the values defined in java system properties, or with the value returned by a registered variable resolver that implements the interface IVariableResolver. Variable resolvers are registered in the OSGi service registry. If more than one resolver is registered, the first one that returns a value for the variable will be used. If no value is found for a variable, then the variable identifier is unmodified in the returned string.

Parameters:

str - The string for which variables should be substituted

Returns:

The input string with variables of the form ${name} replaced with the variable values.

substituteProps

String substituteProps(String str,
                     IAggregator.SubstitutionTransformer transformer)

Like substituteProps(String), but allows the caller to specify a transformer class to process the substitution values.

Parameters:

str - The input string

transformer - An instance of IAggregator.SubstitutionTransformer

Returns:

The transformed string

getPlatformServices

IPlatformServices getPlatformServices()

Get the IPlatformServices implementation for this aggregator.

Returns:

An implementation of IPlatformServices

buildAsync

Future<?> buildAsync(Callable<?> builder,
                   javax.servlet.http.HttpServletRequest request)

Runs the specified builder on an asynchronous thread and returns a Future to the result. Saves request to a thread local that can be queried by the async thread using getCurrentRequest().

Parameters:

builder - the builder to run

request - the request object

Returns:

the Future to the build result

getCurrentRequest

javax.servlet.http.HttpServletRequest getCurrentRequest()

Returns the request object currently being processed. This method will return the request object for the servlet's main processing threads, as well as any asynchronous builders invoked using buildAsync(Callable, HttpServletRequest). For all other threads, the return value will be null.

Returns:

the current request object, or null