CSSModuleBuilder (Jaggr Core 1.3.4-SNAPSHOT API)

java.lang.Object
- com.ibm.jaggr.core.impl.modulebuilder.text.TextModuleBuilder
- - com.ibm.jaggr.core.impl.modulebuilder.css.CSSModuleBuilder

All Implemented Interfaces:

IConfigListener, IExtensionInitializer, IExtensionSingleton, IShutdownListener, IModuleBuilder

Direct Known Subclasses:

LessModuleBuilder
```
public class CSSModuleBuilder
extends TextModuleBuilder
implements IExtensionInitializer, IExtensionSingleton, IShutdownListener, IConfigListener
```
This class optimizes CSS module resources that are loaded by the AMD aggregator. The following optimizations are performed:
- Comment removal
- Unnecessary white-space and token removal
- In-lining of @imports
- In-lining of image URLs using the Data URI scheme
- Runs configured PostCSS plugins (e.g. autoprefixer)
This module works by extending TextModuleBuilder and processing the text stream associated with the Reader that is returned by the overridden method getContentReader(String, com.ibm.jaggr.core.resource.IResource, javax.servlet.http.HttpServletRequest, java.util.List).
Comment removal

Removes comments identified by /* ... */ comment tags
Unnecessary white-space and token removal

Removes carriage returns, line-feeds, tabs and multiple spaces, replacing them with a single space character where necessary. It will also remove unneeded tokens like trailing semi-colons and quotes surrounding URLs.
In-lining of @imports

@import statements will be replaced with the contents of the imported CSS. In order for this to work, the @import URLs must be relative, and the must be locatable on the server relative to the location of the importing CSS. Non-relative URLs may be used in @import statements but their use is severely restricted by CSS rules which require that all @import statements be ahead of any styles in a document. Since in-lining an @import replaces it with the contents of the imported style-sheet, any in-lined style sheets which contain style definitions will cause subsequent @import statements which don't get in-lined to be ignored.
Relative URLs in imported CSS files will be rewritten to make them relative to the location of the top level CSS module that is being requested.
In-lining of @import statements is controlled by the following property specified in the server-side AMD config:

INLINEIMPORTS_CONFIGPARAM

If true, then @import statements will be inlined. The default value is true.

In-lining of image URLs using the Data URI scheme

Foo Image URLs in CSS can optionally be in-lined, replacing the URL with the base64 encoded contents of the image using the Data URI scheme. In-lining of image URLs by is controlled by the following properties specified in the server-side AMD config:

SIZETHRESHOLD_CONFIGPARAM

This parameter specifies the maximum size of an image that may be in-lined. Images larger than this size will not be in-lined. The size is specified in bytes. The default size is 0

IMAGETYPES_CONFIGPARAM

A comma delimited list of mime types that may be in-lined. The standard image types (image/gif, image/png, image/jpeg and image/tiff) do not need to be specified. If you want to in-line any other image types, you can add the mime type to this list.

EXCLUDELIST_CONFIGPARAM

A comma delimited list of filespecs to be excluded from in-lining. The filespec may contain the wildcard characters * and ?. If the filespec does not contain the path separator character '/', then the filespec is matched against the filename portion of image resource only. If the filespec does contain a path separator, then it is matched against the full path of the image resource on the server. Note that * and ? will match the path separator so, for example, the filespec */foo/bar.css will match any path that ends with /foo/bar.css. Any image resource that matches one of these filespecs will not be in-lined.

INCLUDELIST_CONFIGPARAM

A comma delimited list of filespecs to be in-lined. Resources that match these filespecs will be in-lined, even if they don't meet any of the other qualifications for in-lining, and no other files will be inlined (i.e. the include list is a white-list). Filespec matching rules are the same as for inlinedImageExcludeList.

Running configured PostCSS plugins

Plugins are configured in the Server-side AMD JavaScript config using an array of two element arrays as in the following example:
```
 postcss: {
    plugins: [
       [
          'autoprefixer',  // Name of the plugin resource
                           // Can be an AMD module id or an absolute URI to a server resource
          function(autoprefixer) {
              return autoprefixer({browsers: '> 1%'}).postcss; } // the init function
           }
       ]
    }
 ],
 
```

Nested Class Summary
- Nested classes/interfaces inherited from interface com.ibm.jaggr.core.IExtensionInitializer
  IExtensionInitializer.IExtensionRegistrar

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`AMD_DEFINE_SHIM_JS`
`static String`	`BLANK`
`static int`	`DEFAULT_SCOPE_POOL_SIZE`
`static String`	`EXCLUDELIST_CONFIGPARAM`
`static String`	`EXPORTS`
`int`	`imageSizeThreshold`
`static String`	`IMAGETYPES_CONFIGPARAM`
`boolean`	`includeAMDPaths`
`static String`	`INCLUDEAMDPATHS_CONFIGPARAM`
`static boolean`	`INCLUDEAMDPATHS_DEFAULT_VALUE`
`static String`	`INCLUDELIST_CONFIGPARAM`
`static int`	`INITIALIZER_THREAD_POOL_SIZE`
`Collection<Pattern>`	`inlinedImageExcludeList`
`static String`	`INLINEIMAGES_REQPARAM_NAME`
`boolean`	`inlineImports`
`static String`	`INLINEIMPORTS_CONFIGPARAM`
`static boolean`	`INLINEIMPORTS_DEFAULT_VALUE`
`static String`	`INLINEIMPORTS_REQPARAM_NAME`
`static String`	`MINIFIER_INITIALIZATION_JS`
`static String`	`MINIFIER_INITIALIZATION_VAR`
`static String`	`MINIFYER_RES_NAME`
`static String`	`MODULE`
`static String`	`PLUGINS`
`static String`	`POSTCSS`
`static String`	`POSTCSS_CONFIGPARAM`
`static String`	`POSTCSS_INSTANCE`
`static Map<String,Boolean>`	`POSTCSS_OPTIONS`
`static String`	`POSTCSS_RES_NAME`
`static String`	`POSTCSSPLUGINS_CONFIGPARAM`
`static String`	`PREAMBLE`
`static String`	`PROCESS`
`protected static Pattern`	`protocolPattern`
`protected static List<ICacheKeyGenerator>`	`s_cacheKeyGenerators`
`protected static Collection<String>`	`s_inlineableImageTypes`
`static int`	`SCOPE_POOL_TIMEOUT_SECONDS`
`static String`	`SCOPEPOOLSIZE_CONFIGPARAM`
`static String`	`SIZETHRESHOLD_CONFIGPARAM`
`static int`	`SIZETHRESHOLD_DEFAULT_VALUE`
`protected static Pattern`	`urlPattern`
`static String`	`UTF8_CHARSET`

Constructor Summary

Constructors
Modifier Constructor and Description

CSSModuleBuilder()

protected CSSModuleBuilder(IAggregator aggregator)

Constructors
Modifier	Constructor and Description
	`CSSModuleBuilder()`
`protected`	`CSSModuleBuilder(IAggregator aggregator)`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`configLoaded(IConfig conf, long sequence)` This method is called when the config is loaded/reloaded, after the config has been modified by any registered `IConfigModifier` services.
`protected org.mozilla.javascript.Scriptable`	`createThreadScope(org.mozilla.javascript.Context cx, org.mozilla.javascript.Scriptable protoScope)` Creates a thread scope for the PostCSS processor and it's plugins.
`String`	`dequote(String in)` Removes single or double quotes from a quoted string.
`protected String`	`getBase64(InputStream in)` Returns a base64 encoded string representation of the contents of the resource associated with the `URLConnection`.
`List<ICacheKeyGenerator>`	`getCacheKeyGenerators(IAggregator aggregator)` This method may be called, before `IModuleBuilder.build(String, IResource, HttpServletRequest, List)` is called by a separate worker thread, to obtain a cache key generator for this builder.
`protected Reader`	`getContentReader(String mid, IResource resource, javax.servlet.http.HttpServletRequest request, List<ICacheKeyGenerator> keyGens)`
`protected BlockingQueue<org.mozilla.javascript.Scriptable>`	`getThreadScopes()` Returns the thread scope queue
`boolean`	`handles(String mid, IResource resource)` Returns true if this module builder handles the specified resource
`void`	`initialize(IAggregator aggregator, IAggregatorExtension extension, IExtensionInitializer.IExtensionRegistrar registrar)` Called immediately after the extension is created to set the aggregator instance that this extension object was created for.
`protected void`	`initPostcss(IConfig config)` Initializes Rhino with PostCSS and configured plugins.
`protected String`	`inlineImageUrls(javax.servlet.http.HttpServletRequest req, String css, IResource res)` Replace `url(<relative-path>)` references in the input CSS with `url(data:<mime-type>;<base64-encoded-data>` ).
`protected String`	`inlineImports(javax.servlet.http.HttpServletRequest req, String css, IResource res, String path)` Processes the input CSS to replace @import statements with the contents of the imported CSS.
`protected String`	`postcss(String css, IResource res)` Runs given CSS through PostCSS processor for minification and any other processing by configured plugins .
`protected String`	`readToString(Reader in)` Copies the contents of the specified `Reader` to a String.
`void`	`shutdown(IAggregator aggregator)` This method is called from within the aggregator's `GenericServlet.destroy()` method to notify listeners that the servlet is shutting down.
`protected Pattern`	`toRegexp(String filespec)` Returns a regular expression for a filepath that can include standard file system wildcard characters (e.g.

Methods inherited from class com.ibm.jaggr.core.impl.modulebuilder.text.TextModuleBuilder
build, isScript

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - INLINEIMPORTS_CONFIGPARAM
```
public static final String INLINEIMPORTS_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - INCLUDELIST_CONFIGPARAM
```
public static final String INCLUDELIST_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - EXCLUDELIST_CONFIGPARAM
```
public static final String EXCLUDELIST_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - IMAGETYPES_CONFIGPARAM
```
public static final String IMAGETYPES_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - SIZETHRESHOLD_CONFIGPARAM
```
public static final String SIZETHRESHOLD_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - INCLUDEAMDPATHS_CONFIGPARAM
```
public static final String INCLUDEAMDPATHS_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - POSTCSSPLUGINS_CONFIGPARAM
```
public static final String POSTCSSPLUGINS_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - SCOPEPOOLSIZE_CONFIGPARAM
```
public static final String SCOPEPOOLSIZE_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - POSTCSS_CONFIGPARAM
```
public static final String POSTCSS_CONFIGPARAM
```
    See Also:
    Constant Field Values
  - INLINEIMPORTS_DEFAULT_VALUE
```
public static final boolean INLINEIMPORTS_DEFAULT_VALUE
```
    See Also:
    Constant Field Values
  - INCLUDEAMDPATHS_DEFAULT_VALUE
```
public static final boolean INCLUDEAMDPATHS_DEFAULT_VALUE
```
    See Also:
    Constant Field Values
  - SIZETHRESHOLD_DEFAULT_VALUE
```
public static final int SIZETHRESHOLD_DEFAULT_VALUE
```
    See Also:
    Constant Field Values
  - INLINEIMPORTS_REQPARAM_NAME
```
public static final String INLINEIMPORTS_REQPARAM_NAME
```
    See Also:
    Constant Field Values
  - INLINEIMAGES_REQPARAM_NAME
```
public static final String INLINEIMAGES_REQPARAM_NAME
```
    See Also:
    Constant Field Values
  - PREAMBLE
```
public static final String PREAMBLE
```
    See Also:
    Constant Field Values
  - BLANK
```
public static final String BLANK
```
    See Also:
    Constant Field Values
  - UTF8_CHARSET
```
public static final String UTF8_CHARSET
```
    See Also:
    Constant Field Values
  - POSTCSS_RES_NAME
```
public static final String POSTCSS_RES_NAME
```
    See Also:
    Constant Field Values
  - MINIFYER_RES_NAME
```
public static final String MINIFYER_RES_NAME
```
    See Also:
    Constant Field Values
  - POSTCSS
```
public static final String POSTCSS
```
    See Also:
    Constant Field Values
  - PROCESS
```
public static final String PROCESS
```
    See Also:
    Constant Field Values
  - PLUGINS
```
public static final String PLUGINS
```
    See Also:
    Constant Field Values
  - POSTCSS_INSTANCE
```
public static final String POSTCSS_INSTANCE
```
    See Also:
    Constant Field Values
  - MODULE
```
public static final String MODULE
```
    See Also:
    Constant Field Values
  - EXPORTS
```
public static final String EXPORTS
```
    See Also:
    Constant Field Values
  - AMD_DEFINE_SHIM_JS
```
public static final String AMD_DEFINE_SHIM_JS
```
    See Also:
    Constant Field Values
  - MINIFIER_INITIALIZATION_VAR
```
public static final String MINIFIER_INITIALIZATION_VAR
```
    See Also:
    Constant Field Values
  - MINIFIER_INITIALIZATION_JS
```
public static final String MINIFIER_INITIALIZATION_JS
```
    See Also:
    Constant Field Values
  - POSTCSS_OPTIONS
```
public static final Map<String,Boolean> POSTCSS_OPTIONS
```
  - INITIALIZER_THREAD_POOL_SIZE
```
public static final int INITIALIZER_THREAD_POOL_SIZE
```
    See Also:
    Constant Field Values
  - DEFAULT_SCOPE_POOL_SIZE
```
public static final int DEFAULT_SCOPE_POOL_SIZE
```
    See Also:
    Constant Field Values
  - SCOPE_POOL_TIMEOUT_SECONDS
```
public static final int SCOPE_POOL_TIMEOUT_SECONDS
```
    See Also:
    Constant Field Values
  - urlPattern
```
protected static final Pattern urlPattern
```
  - protocolPattern
```
protected static final Pattern protocolPattern
```
  - s_inlineableImageTypes
```
protected static final Collection<String> s_inlineableImageTypes
```
  - s_cacheKeyGenerators
```
protected static final List<ICacheKeyGenerator> s_cacheKeyGenerators
```
  - imageSizeThreshold
```
public int imageSizeThreshold
```
  - inlineImports
```
public boolean inlineImports
```
  - includeAMDPaths
```
public boolean includeAMDPaths
```
  - inlinedImageExcludeList
```
public Collection<Pattern> inlinedImageExcludeList
```
- Constructor Detail
  - CSSModuleBuilder
```
public CSSModuleBuilder()
```
  - CSSModuleBuilder
```
protected CSSModuleBuilder(IAggregator aggregator)
```
- Method Detail
  - getContentReader
```
protected Reader getContentReader(String mid,
                      IResource resource,
                      javax.servlet.http.HttpServletRequest request,
                      List<ICacheKeyGenerator> keyGens)
                           throws IOException
```
    Overrides:
    
    getContentReader in class TextModuleBuilder
    
    Throws:
    
    IOException
  - readToString
```
protected String readToString(Reader in)
                       throws IOException
```
    Copies the contents of the specified Reader to a String.
    
    Parameters:
    in - The input Reader
    
    Returns:
    The contents of the Reader as a String
    
    Throws:
    
    IOException
  - inlineImports
```
protected String inlineImports(javax.servlet.http.HttpServletRequest req,
                   String css,
                   IResource res,
                   String path)
                        throws IOException
```
    Processes the input CSS to replace @import statements with the contents of the imported CSS. The imported CSS is minified, image URLs in-lined, and this method recursively called to in-line nested @imports.
    
    Parameters:
    req - The request associated with the call.
    css - The current CSS containing @import statements to be processed
    res - The resource for the CSS file.
    path - The path, as specified in the @import statement used to import the current CSS, or null if this is the top level CSS.
    
    Returns:
    The input CSS with @import statements replaced with the contents of the imported files.
    
    Throws:
    
    IOException
  - inlineImageUrls
```
protected String inlineImageUrls(javax.servlet.http.HttpServletRequest req,
                     String css,
                     IResource res)
```
    Replace url(<relative-path>) references in the input CSS with url(data:<mime-type>;<base64-encoded-data> ). The conversion is controlled by option settings as described in CSSModuleBuilder.
    
    Parameters:
    req - The request associated with the call.
    css - The input CSS
    res - The resource for the CSS file
    
    Returns:
    The transformed CSS with images in-lined as determined by option settings.
  - postcss
```
protected String postcss(String css,
             IResource res)
                  throws IOException
```
    Runs given CSS through PostCSS processor for minification and any other processing by configured plugins .
    
    Parameters:
    css -
    res -
    
    Returns:
    The processed CSS.
    
    Throws:
    
    IOException
  - initPostcss
```
protected void initPostcss(IConfig config)
```
    Initializes Rhino with PostCSS and configured plugins. The minifier plugin is always added. Additional plugins are added based on configuration. See CSSModuleBuilder for a description of the plugin config JavaScript
    
    Parameters:
    config - The config object
    
    Throws:
    
    IllegalArgumentException - if any of the config parameters are not valid
    
    RuntimeException - for any other exception caught within this module
  - createThreadScope
```
protected org.mozilla.javascript.Scriptable createThreadScope(org.mozilla.javascript.Context cx,
                                                  org.mozilla.javascript.Scriptable protoScope)
```
    Creates a thread scope for the PostCSS processor and it's plugins. Thread scopes allow PostCSS to process multiple CSS modules concurrently, each executing in a separate thread, without interfering with each other.
    
    Parameters:
    cx - the Rhino Context
    protoScope - the parent scope object
    
    Returns:
    the thread scope
  - getThreadScopes
```
protected BlockingQueue<org.mozilla.javascript.Scriptable> getThreadScopes()
```
    Returns the thread scope queue
    
    Returns:
    the thread scope queue
  - getBase64
```
protected String getBase64(InputStream in)
                    throws IOException
```
    Returns a base64 encoded string representation of the contents of the resource associated with the URLConnection.
    
    Parameters:
    in - The input stream for the resource
    
    Returns:
    The base64 encoded string representation of the resource
    
    Throws:
    
    IOException
  - toRegexp
```
protected Pattern toRegexp(String filespec)
```
    Returns a regular expression for a filepath that can include standard file system wildcard characters (e.g. * and ?)
    
    Parameters:
    filespec - A filespec that can contain wildcards
    
    Returns:
    A regular expression to match paths specified by filespec
  - getCacheKeyGenerators
```
public final List<ICacheKeyGenerator> getCacheKeyGenerators(IAggregator aggregator)
```
    Description copied from interface: IModuleBuilder
    
    This method may be called, before IModuleBuilder.build(String, IResource, HttpServletRequest, List) is called by a separate worker thread, to obtain a cache key generator for this builder. If cache keys for this builder depend on module content, then this method should return a provisional cache key generator, which generates cache keys based on information in the request only. Provisional cache keys may be more exclusive than non-provisional cache keys in matching requests to module builds.
    If this method returns a provisional cache key generator, then IModuleBuilder.build(String, IResource, HttpServletRequest, List) will be called with a null cache key generator list and that method MUST return a ModuleBuild object with a new immutable list of non-provisional cache key generators when subsequently called for the same request.
    
    Specified by:
    
    getCacheKeyGenerators in interface IModuleBuilder
    
    Overrides:
    
    getCacheKeyGenerators in class TextModuleBuilder
    
    Parameters:
    aggregator - The aggregator instance
    
    Returns:
    The list of cache key generators for this builder. One or more of the cache key generators may be provisional.
  - handles
```
public boolean handles(String mid,
              IResource resource)
```
    Description copied from interface: IModuleBuilder
    
    Returns true if this module builder handles the specified resource
    
    Specified by:
    
    handles in interface IModuleBuilder
    
    Overrides:
    
    handles in class TextModuleBuilder
    
    Parameters:
    mid - the module id
    resource - the resource for the module id
    
    Returns:
    true if this builder can build the module
  - shutdown
```
public void shutdown(IAggregator aggregator)
```
    Description copied from interface: IShutdownListener
    
    This method is called from within the aggregator's GenericServlet.destroy() method to notify listeners that the servlet is shutting down.
    
    Specified by:
    
    shutdown in interface IShutdownListener
    
    Parameters:
    aggregator - The aggregator that is shutting down
  - initialize
```
public void initialize(IAggregator aggregator,
              IAggregatorExtension extension,
              IExtensionInitializer.IExtensionRegistrar registrar)
```
    Description copied from interface: IExtensionInitializer
    
    Called immediately after the extension is created to set the aggregator instance that this extension object was created for.
    
    Specified by:
    
    initialize in interface IExtensionInitializer
    
    Parameters:
    aggregator - The aggregator that this extension was created for.
    extension - The extension object
    registrar - A registrar object that can be used to register additional aggregator extendables
  - configLoaded
```
public void configLoaded(IConfig conf,
                long sequence)
```
    Description copied from interface: IConfigListener
    
    This method is called when the config is loaded/reloaded, after the config has been modified by any registered IConfigModifier services.
    
    Specified by:
    
    configLoaded in interface IConfigListener
    
    Parameters:
    conf - The new config object. In order to detect and react to config changes, you can save the value returned from IConfig.toString() and compare it with the value returned in subsequent configLoaded events.
    sequence - The sequence number. Notifications for different listener events (options, config, dependencies) that have the same cause have the same sequence number. Notifications resulting from servlet initialization have the sequence number 1. The sequence number is incremented for subsequent event causes, but there is no guarantee about the the values for subsequent notifications other than that they will be increasing.
  - dequote
```
public String dequote(String in)
```
    Removes single or double quotes from a quoted string. The entire string is expected to be quoted, with possible leading or trailing whitespace. If the string is not quoted, then it is returned unmodified.
    
    Parameters:
    in - The possibly quoted string
    
    Returns:
    The string with quotes removed

Class CSSModuleBuilder

Comment removal

Unnecessary white-space and token removal

In-lining of @imports

In-lining of image URLs using the Data URI scheme

Running configured PostCSS plugins

Nested Class Summary

Nested classes/interfaces inherited from interface com.ibm.jaggr.core.IExtensionInitializer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class com.ibm.jaggr.core.impl.modulebuilder.text.TextModuleBuilder

Methods inherited from class java.lang.Object

Field Detail

INLINEIMPORTS_CONFIGPARAM

INCLUDELIST_CONFIGPARAM

EXCLUDELIST_CONFIGPARAM

IMAGETYPES_CONFIGPARAM

SIZETHRESHOLD_CONFIGPARAM

INCLUDEAMDPATHS_CONFIGPARAM

POSTCSSPLUGINS_CONFIGPARAM

SCOPEPOOLSIZE_CONFIGPARAM

POSTCSS_CONFIGPARAM

INLINEIMPORTS_DEFAULT_VALUE

INCLUDEAMDPATHS_DEFAULT_VALUE

SIZETHRESHOLD_DEFAULT_VALUE

INLINEIMPORTS_REQPARAM_NAME

INLINEIMAGES_REQPARAM_NAME

PREAMBLE

BLANK

UTF8_CHARSET

POSTCSS_RES_NAME

MINIFYER_RES_NAME

POSTCSS

PROCESS

PLUGINS

POSTCSS_INSTANCE

MODULE

EXPORTS

AMD_DEFINE_SHIM_JS

MINIFIER_INITIALIZATION_VAR

MINIFIER_INITIALIZATION_JS

POSTCSS_OPTIONS

INITIALIZER_THREAD_POOL_SIZE

DEFAULT_SCOPE_POOL_SIZE

SCOPE_POOL_TIMEOUT_SECONDS

urlPattern

protocolPattern

s_inlineableImageTypes

s_cacheKeyGenerators

imageSizeThreshold

inlineImports

includeAMDPaths

inlinedImageExcludeList

Constructor Detail

CSSModuleBuilder

CSSModuleBuilder

Method Detail

getContentReader

readToString

inlineImports

inlineImageUrls

postcss

initPostcss

createThreadScope

getThreadScopes

getBase64

toRegexp

getCacheKeyGenerators

handles

shutdown

initialize

configLoaded

dequote