Using a generator

Generators are mapped to bundles as if they were regular script or CSS files, only using a special syntax:

        prefix:path(params)[params]

The prefix is a key you will specify when implementing the Generator, and the path is a string which will have different meaning depending on your generator's functionality. Also, you have params in parentheses and in brackets (both of which are optional), that further help in parameterizing the mappings. A simple mapping example, with no params, is as follows:

        jawr.js.bundle.one.mappings=jar:net/jawr/cpscript.js

In this case we are using the already existing classpath script generator, which reads a script from the classpath, as opposed to reading it from the web application dir structure. So the path in this case is the classpath where the script will be found. The prefix is 'jar', which lets Jawr know that this path must be resolved using the classpath generator.

This is an example in which the mapping uses two different parameters:

        jawr.js.bundle.one.mappings=messages:com.myapp.messages(mynamespace)[javascript.messages]

Note that if you use the parameters, the order must always be parentheses first, brackets last. If you need only one parameter, you can omit the brackets param.

Jawr generators

Jawr comes with several generators, each accomplishing a special kind of task. The currently provided generators are:

All-around generators

Implementing a generator

You will find below the class diagram for generators.

The root interface for resource generator is :

• net.jawr.web.resource.bundle.generator.PrefixedResourceGenerator. All resource generator must implement a method, which defines the mapping for this generator.

          public String getMappingPrefix();
  

  The getMappingPrefix() method returns a key you will use when mapping you generator to bundles. Jawr will recognize this key in the bundle mappings and use your generator when it applies. So, if you returned 'foo' in this method, you would map your generator like this:

          jawr.js.bundle.one.mappings=foo:somePath
  

  There are 2 main types of generator:

• net.jawr.web.resource.bundle.generator.ResourceGenerator, which is the generator for the text resources (JS and CSS).
• net.jawr.web.resource.bundle.generator.StreamResourceGenerator, which is the generator for the image resources.
• Implementing a CSS or a JS generator

  A JS or a CSS generator is an implementation of the interface net.jawr.web.resource.bundle.generator.ResourceGenerator. This is a simple interface which exposes two methods:

  • public Reader createResource(GeneratorContext context);
  • public String getDebugModeRequestPath();

  The getDebugModeRequestPath simply returns a path to be used in debug mode. This is simply a fake script or CSS name and it really has no importance unless you are mapping the Jawr servlet to a suffix different from *.css or .js. 99% of the use cases don't need to care about this so you can simply return one of two constants: ResourceGenerator.JAVASCRIPT_DEBUGPATH or ResourceGenerator.CSS_DEBUGPATH:

  public String getDebugModeRequestPath() {
          return ResourceGenerator.JAVASCRIPT_DEBUGPATH;
  }
  

  Finally, the createResource() method is where the actual generation takes place. This method takes a single parameter of type GeneratorContext, which contains all the information you need to build a dynamic script or CSS. The useful methods are:

  • getPath(): this contains the mapping, without the prefix and parameters. For instance, in a mapping of the form 'prefix:thePath(param)', this method returns 'thePath'.
  • getConfig(): returns the JawrConfig object used throughout the application. It contains data about the Jawr configuration, such as wether debug mode is on or off, the current servlet mapping, and so on.
  • getCharset(): returns the current charset, which the returned script or CSS must conform to.
  • getServletContext(): returns the application's ServletContext.
  • getParenthesesParam(): returns the params in parentheses, if any were declared. For instance, in a mapping such as 'foo:path(aParam)', this would return 'aParam'.
  • getBracketsParam(): returns the params in brackets, if any were declared. For instance, in a mapping such as 'foo:path(aParam)[anotherParam], this would return 'anotherParam'.

    Using this information, you should be able to generate a script or CSS and return in in the form of a Reader object (typically a StringReader is sufficient for the task).

• Implementing an Image resource generator

  An image generator is an implementation of the interface net.jawr.web.resource.bundle.generator.StreamResourceGenerator. This is a simple interface which exposes one method:

  • public InputStream createResourceAsStream(GeneratorContext context);

  This method will return the input stream for the generated image resource. Like for the createResource method of the ResourceGenerator, this method takes as parameter a GeneratorContext, which contains all the information you need to build the image resource.

Mapping a generator

Once you have your Generator implemented, you need to register into Jawr in order to use it. This is simply a matter of mapping its classname in the configuration properties file under the key 'jawr.custom.generators'. If there is more than one, you simply declare them separated by commas:

        jawr.custom.generators=com.mycompany.myapp.MyCustomGeneratorImplementation,com.mycompany.myapp.AnotherGenerator

A simple example: an alert message generator

Here is a sample class which you can use to get started. It simply creates a script that displays an alert message with whichever text is used as the path in the mapping:

package net.jawr.example;

        public class TestGenerator implements ResourceGenerator {

        public Reader createResource(GeneratorContext context) {
                
                return new StringReader(";alert('Mapping contained:" + context.getPath() +  "');");
        }

        public String getMappingPrefix() {
                return "example";
        }
        
        public String getDebugModeRequestPath() {
                return ResourceGenerator.JAVASCRIPT_DEBUGPATH;
        }
}

With this class in hand, we first register it in our properties config file:

        jawr.custom.generators=net.jawr.example.TestGenerator

And now it's a matter of creating a bundle and use the generator:

        jawr.js.bundle.global.id=/bundles/global.js
        jawr.js.bundle.global.mappings=example:Hello World!,example:And Hello Again!

And that's it, now add the bundle to any page and when it's loaded, you should get an alert box with the text 'Mapping contained:Hello World!' followed by a second alert box with the text 'Mapping contained:And Hello Again!'.

Security issues with generator

If you develop your own generator, which reads content from resources on your server, you must take care of prevent users to access unauthorized resources. You must check if the requested resource is an allowed one or not. For example, the user must not be able to retrieve the files located under /WEB-INF/ or /META-INF/ in your web application, or directly the content of the JSP files.

To check if your generator is sensible to this issue, you must launch your application in debug mode, and then try to reach your resource using the following URL:

        http://localhost:8080/myWebAppContext/sample.js?generationConfigParam=myGen:/WEB-INF/web.xml

In this example, myGen is the prefix of the generator. So you must replace it by the prefix of your generator. If you are able to see the content of the web.xml file, this means that you need to change your generator to fix this issue.