JGenerator. Free generator of dynamic Flash content.

Frequently Asked Questions

General questions

Will JGenerator support custom objects?
Does JGenerator run on the Macintosh platform?
Why not open-source?
I would like to have some java-based api to JGenerator. Are there any plans for that?
Does JGenerator produce the same output formats that Generator does (most impotantly jpeg, and gif)?
Do you have any performance benchmarks that you could share?
Does this version do multithreading? The reason for wanting to know this is to see if the JGenerator would be up to high volume serving.
Also, do the internals of JGenerator use any of the java.awt API - as I was wondering if it would work on a server with no display server.
Would there be a way to run Jgenerator off a CD with a JDK on the CD as well, without having to install anything ?
Where can I learn about Java API to JGenerator?
I want to put "powered by JGenerator" button on my page. Do you have some?
Does JGenerator support character sets with foreign characters, e.g. ISO-8859-1 or Latin1?

Installation

How to install JGenerator?

The JGenerator is a Java application, compliant with JDK 1.3 and so a Java virtual machine (VM) is required to run the product. The JGenerator comes in three different flavours:

with installer bundled with VM (Windows or Mac only)
with installer without VM (Windows or Mac only)
without installer and without VM (any platform)
If you are not sure what to choose I recommend you the first case. You just download it, run the installer and that's it, you are all set.
If you already have VM installed on your computer (for example Mac OS X already has it installed!) or willing to download it yourself, then you may want to choose second or third case.
In these cases I highly recommend that you obtain the latest stable copy of the JDK from Sun Microsystems. As of this writing it is the JDK 1.3. You can download it from here. Or you can just install Java Runtime Environment (which is much smaller) from here. Note that if you have some servlet engine installed on your computer you probably already have some JDK installed too, so if this is the case you don't have to install another JDK. And again I strongly recommend you to use Hotspot VM (JDK 1.3) for online processing. In my tests Hotspot faster than JDK 1.2 in 1.5 times !
The JGenerator itself is simple to install. If it's version with the installer, you just run the installer and that's it. If it's .zip archive you just need to unzip jgenerator.zip into some directory, for example c:\. It will create you the directory c:\jgenerator-vX.Y.Z.
To configure JGenerator for offline processing click here.
To configure JGenerator for online processing you need to install some servlet engine. Currently it works with Tomcat, JRun, ServletExec 3.x. and Resin. If you already have one of them installed, go to corresponding configuration page: for Tomcat, for JRun, for ServletExec 3.x and for Resin. Otherwise you need to download one of them, install and configure, then you can configure the JGenerator to work with them. The JGenerator should work with the other servlet engines as well, I just have not checked this yet. If it works with the others, please let me know.

Configuring JGenerator on Tomcat

Install the JGenerator as described here.
I am not an expert in Tomcat or Apache configuration, so I will just give you one very simple and workable way of making it up and running. All the issues related to security and to similar stuff I let you manage by yourself.
First you have to create a context in server.xml file, something like this:
        <Context path="" 
                 docBase="webapps/ROOT"
                 crossContext="false"
                 debug="0" 
                 reloadable="true" > 
        </Context>
    
path="" means you want to process .swt's from any directory. Note that if you already have a similar context you should not create it again.
Then you add servlet entry to web.xml in corresponding <docBase>/WEB_INF directory (in my example it's webapps/ROOT/WEB-INF):
    <servlet>
        <servlet-name>
            swt
        </servlet-name>
        <servlet-class>
            com.iv.flash.servlet.GeneratorServlet
        </servlet-class>
        <init-param>
            <param-name>com.iv.flash.installDir</param-name>
            <param-value>c:\jgenerator-vX.Y.Z</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>
            swt
        </servlet-name>
        <url-pattern>
            *.swt
        </url-pattern>
    </servlet-mapping>
    
You have to put the directory where you installed the JGenerator into <init-param> com.iv.flash.installDir value.
Now you have to copy jgen.jar (which can be found in jgenerator-vX.Y.Z/lib/) into <docBase>/WEB_INF/lib directory (in my example it's webapps/ROOT/WEB-INF/lib). If <docBase>/WEB_INF/lib does not exist just create it.
So now you are done with Tomcat configuration. If you want to configure Apache JServ as well you'd better read Apache and Tomcat documentation. As a simple solution add these two lines to your my_tomcat_apache.conf:
AddType text/swt .swt
AddHandler jserv-servlet .swt
    
Enjoy!

Configuring JGenerator on Tomcat 3.3 (by Alessandro D'Andrea)

Using JGenerator with Apache - Tomcat 3.3 and Jk (replace old Jserve)
A base configuration to run JGenerator with Tomcat 3.3 Servlet Engine is:
Extract your Jgeneratorxx.tar.gz in a dir (for example /usr/local/jgenerator)

Make a dir for JGenerator in your $TOMCAT_HOME.
In this step you create the directory where JGenerator will work. You can also create this directory in your Httpd Document Root and then make a link in your $TOMCAT_HOME but the first is the simplest way to run JGenerator.
[root@dollydesign]# mkdir $TOMCAT_HOME/jgenerator
Then we create the directory structure for servlets:
[root@dollydesign]# mkdir $TOMCAT_HOME/jgenerator/WEB-INF [root@dollydesign]# mkdir $TOMCAT_HOME/jgenerator/WEB-INF/classes
Now give the right permission (the same of the other directory in $TOMCAT_HOME:
[root@dollydesign]# chown -R nobody.bin $TOMCAT_HOME/jgenerator

Extract jgen.jar file in classes dir.
Then copy and extract jgen.jar file in $TOMCAT_HOME/jgenerator/WEB-INF/classes
[root@dollydesign]# cd $TOMCAT_HOME/jgenerator/WEB-INF/classes [root@dollydesign]# jar xvf /usr/local/jgenerator/lib/jgen.jar
Make a little config file for Tomcat.
In this step you create the xml context file (feature added in Tomcat 3.3):
Go into $TOMCAT_HOME/conf
Then make a file named "apps-" + directory name + ".xml" which contains Jgenerator servlets. In this example "apps-jgenerator.xml".
This file contains:
   <?xml version="1.0" encoding="ISO-8859-1"?>
   <jgenerator>
   
    <Context path="/jgenerator" 
             docBase="jgenerator" 
             reloadable="true" 
             trusted="false" > 
    </Context>
   </jgenerator>
Making a little web.xml file for jgenertor.
Go to $TOMCAT_HOME/jgenerator/WEB-INF/
Make web.xml file that contains:
    <?xml version="1.0" encoding="ISO-8859-1"?>

    <!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

    <web-app>
        <servlet>
            <servlet-name>
                swt
            </servlet-name>
            <servlet-class>
                com.iv.flash.servlet.GeneratorServlet
            </servlet-class>
            <init-param>
                <param-name>com.iv.flash.installDir</param-name>
                <param-value>/usr/local/jgenerator</param-value>
            </init-param>
        </servlet>
        <servlet-mapping>
            <servlet-name>
                swt
            </servlet-name>
            <url-pattern>
                *.swt
            </url-pattern>
        </servlet-mapping>
    </web-app>
Now we modify Apache config file (httpd.conf) in order to add *.swt bind to Tomcat.
We add these two lines:
        
    AddType text/swt .swt
    JkMount /jgenerator/*.swt ajp13
The second line is for ajp13 support, if you are using ajp12 simply replace the second line with
        
    JkMount /jgenerator/*.swt ajp12
Now restart Tomcat, then Apache and insert in $TOMCAT_HOME/jgenerator an SWT file for testing the application. You can see JGeneretor running at http://www.yourhost.com/jgenerator/yourfile.swt
Alessandro D'Andrea (a.dandrea@dollydesign.com)

Configuring JGenerator on JRun 2.3

Install the JGenerator as described here.
Run JRunAdmin (whether from command line or from GUI).
Go to Services, select jse (Java Servlet Engine) and click on Service Config.

Go to Mappings and add new entry. Put *.swt into Virtual Path/Extension and JGenerator to Servlet Invoked.

Then go to Aliases and add new entry. Put JGenerator into Name, com.iv.flash.servlet.GeneratorServlet into Class Name, com.iv.flash.installDir=<directory where the JGenerator is installed> into initArguments.

Then save your changes. You also have to add <directory where JGenerator is installed>/lib/jgen.jar to JRun's classpath. Just go to JRunAdmin->General->Java->Java Classpath.

Configuring JGenerator on JRun 3.0 (by Nico Joos)

There is a link to MSWord document which describes this.

Configuring JGenerator on IIS4/ServletExec 3.x (by CJ Smessaert)

the following instructions assume you've already installed and configured ServletExec 3.x on NT4/IIS4. the concept of a virtual server still applies since SE considers the 'default' web site as if it were also a virtual. if you need specific configuration help, feel free to email me at cj@ignitionstate.com.
jGenerator 'install'
-download latest jGenerator package
-unarchive jGenerator (note path) onto local machine. NOTE: instructions below refer to this path as <jgeneratorpath>.
Configuring ServletExec's Properties
Using ServletExec's Administration Console (http://virtualhostdomainname/servlet/admin) for a specific Virtual Server:
-add <jgeneratorpath>\lib\jgen.jar to classpath
-under Servlets/Configure, 'Add Servlet', assigning the following name/value pairs:
Servlet Name: GeneratorServlet
Servlet Class: com.iv.flash.servlet.GeneratorServlet
Initialization Parameters
Name = com.iv.flash.installDir
Value = <jgeneratorpath>
-under Servlets/Aliases, define the following:
Alias = *.swt
Servlet Name(s) = GeneratorServlet
Configuring IIS's Virtual Server Properties (need to map .swt extension to servlet engine)
-open IIS Administration Console
-open Properties for specific Virtual Server (right-click)
-click 'Home Directory' tab
-press Configuration button under Application Settings
-under Application Mappings, click Add button
-assign the following:
Executable = full path ServletExec_ISAPI.dll on local drive
Extension = .swt
-click OK
-click OK
DONE!

Configuring JGenerator on JServ (by Tobi)

1. Copy the jgenerator binaries to .
The directory should contain the directories:
- logs
- bin
- lib
and the file iv.properties.
NOTE1: the logs-directory has to be writable by the webserver
2a. When running JServ in automatic mode,
change jserv.properties : add the line
wrapper.classpath=/lib/jgen.jar
2b. When running in manual mode:
add /lib/jgen.jar
to your classpath before running jserv
3. Change the zone-properties file.
add the following lines:
servlet.jgenerator.code=com.iv.flash.servlet.GeneratorServlet
servlet.jgenerator.initArgs=com.iv.flash.installDir=
4. Change the httpd.conf file:
We assume a zone has been mounted under "/example" using the ApJServMount
directive add the following lines below the ApJServMount-command:
ApJServAction .swt /example/swt
5. For advanced configuration, edit the iv.properties-file.

Configuring JGenerator on Resin (by Christian Cantrell)

Install the JGenerator as described here.
Edit your resin.conf file (found in resinx.x/conf). Between the <web-app id='/'> and the </web-app> tags, insert the following:

<servlet-mapping url-pattern='*.swt' servlet-name='jgen'/>
<servlet servlet-name='jgen' servlet-class='com.iv.flash.servlet.GeneratorServlet'>
  <init-param com.iv.flash.installDir='/path/to/JGenerator/installation'/>
</servlet>
The url-pattern '*.swt' means that any request matching that pattern will be handled by the named servlet, which in this case is com.iv.flash.servlet.GeneratorServlet. The init parameter "com.iv.flash.installDir" points to the directory where JGenerator is installed (for example, c:\jgenerator on Windows, or /usr/local/jgenerator on Unix).
The only other thing you must do is either copy jgen.jar (found in jgenerator/lib) to resinx.x/lib, or otherwise make sure jgen.jar is in your classpath. You can either use your system classpath, or build a custom classpath within the resin start scripts.
You must restart resin for your changes to take effect. Copy an swt file into your document root and request it from your browser.

Configuring JGenerator on Tomcat under IIS. (by maurizio piacenza)

These are the right instructions and now swt files can work in Tomcat directories as well as in IIS directories: You can see SWT files in Tomcat directories if you type http://localhost/nameOfTomcatDirectory or if you type http://localhost:8080/nameOfTomcatDirectory; for IIS directory you use http://localhost/nameOfIISDirectory:
- Configuration about IIS to work with Tomcat is the same as in Jackarta site - then...
created a "lib" directory in "webapps/examples/WEB-INF/" directory of Tomcat and put "jgen.jar" file in it.
in web.xml file in Tomcat/conf/ and webapps/examples/WEB-INF/ added this code, between web-app tag (<web-app></web-app>:
<servlet> 
    <servlet-name> swt </servlet-name> 
    <servlet-class> com.iv.flash.servlet.GeneratorServlet </servlet-class> 
    <init-param>
        <param-name>com.iv.flash.installDir</param-name>
        <param-value>c:\jgenerator-1.3.0</param-value> 
    </init-param> 
</servlet>
<servlet-mapping> 
    <servlet-name> swt </servlet-name> 
    <url-pattern> *.swt </url-pattern> 
</servlet-mapping>
in "uriworkermap.properties" file in "Tomcat/conf/" directory added "/*.swt=ajp12" row
made sure in server.xml file (in Tomcat/conf/) there is this code:
<Context path="/"
    docBase="C:/Inetpub/wwwroot"
    crossContext="true"
    debug="0"
    reloadable="true"
    trusted="false" >
</Context>
in place of
<Context path="/"
    docBase="webapps/ROOT"
    crossContext="true"
    debug="0"
    reloadable="true"
    trusted="false" >
</Context>
In C:/Inetpub/wwwroot directory created a WEB-INF directory and put "lib" directory and "classe" directory in it; "lib" directory must have jgen.jar in it while in "classes" you have to put all classes you will use in the site. Then create (or duplicate) a web.xml file in WEB-INF directory you've just created and put in it the same code there is in web.xml of examples;
OK, that's really all! Now JSP files work in every IIS directory under Inetpub/wwwroot and in every directory under tomcat\webapps\examples (you can call them typing http://localhost/examples) and also SWt files work in every directory of IIS and in Tomcat examples. There is only a disadvantage: now you can't call webapps/ROOT cause you have substituted this Tomcat context with Inetpub/wwwroot; if you want (but this work only on 8080 port) you can add a new context in Tomcat. Type these lines:
<Context path="/tomcatsite"
    docBase="webapps/ROOT"
    crossContext="true"
    debug="0"
    reloadable="true"
    trusted="false" >
</Context>
You can use any name you want instead of "tomcatsite" :-) Now, if you type http://localhost:8080/tomcatsite you will see Tomcat index default page (an error will occur if you try with IIS, without typing :8080)
I hope this will be useful for a lot of people

Configuring JGenerator on Lotus Domino. (by Alexandre Courgnaud)

ok, there's no much things to do in configuring the Domino servlet engine, here it is on windows platform and should be the same under Linux or other domino platform:
These steps concerned Domino release 5.x only with its own servlet manager (Domino can also works with IBM Websphere, consult your documentation for configuration).
A. To be brief, we have to edit the servlets.properties file to fullfill with the following informations :
servlet.jGenerator.code=com.iv.flash.servlet.GeneratorServlet
servlet.jGenerator.initArgs=com.iv.flash.installDir=<PATH>
servlet.jGenerator.extension=swt
where "<PATH>" is the installed jGenerator directory, for example "D:\\Program Files\\JGenerator" on my server. The servlet.properties file can be found in the Domino data directory, for example "D:\Lotus\Domino\Data" on my server.
Second, we have to define several things in the Domino Directory (names.nsf in the Domino data directory) :

Open the server document of the server onto you will run the servlet
Go to "Internet protocols" tab.
Select the "Domino Web Engine" subtab
In the "Java Servlets" section, we have four fields:

Java servlet support
Servlet URL path
Class path
Servlet file extensions

In the field "Java servlet support", select "Domino Servlet Manager"
The field "Servlet URL path" is the path in a URL that signals Domino that the URL refers to a servlet. The default is "/servlet". Here is the path where you will put your ".swt" files for example.
The default value for "Class path" is "domino\servlet" (which means "d:\lotus\domino\data\domino\servlet" directory on my server) but you can add more paths that that will be used by the Servlet Manager and JVM search to find servlets and dependent classes. The standard Java libraries installed with Domino are automatically in the class path. Don't forget to paste the .jar files of jgenerator in this directory if you didn't specified the directory "..\JGenerator\lib".
Now concerning int the "Servlet file extensions" field, just specify the file extension that jGenerator will hold. For ".swt" file, just type "swt" in the field.

That's it, just restart your http task by typing "tell http restart" on the console server and everything should be ok.
B. For information and to have a complete description of the servlet configuration, here is a good page with screenshots.
These informations can also be found in the Domino help administration database under the title "Managing Java servlets on a Web server". If you need some assistance you may contact Alexandre Courgnaud at alc@shortcut.cc

How to use the JGenerator for offline processing?

Install the JGenerator as described here.
Add JGenerator/bin directory to your PATH environment variable. If you installed JGenerator manually, without an installer, you have to set an environment variable IVGEN_HOME to the directory where the JGenerator is installed. If you installed JGenerator using an installer you don't need to do it!
Then you can run the JGenerator in offline mode by running the command: jgenerate. If you run jgenerate -help you will get the following output:
JGenerator Version 1.3.1
Copyright (c) Dmitry Skavish, 2000-2001. All rights reserved.

Usage: jgenerate [options] <filename.swt>

Options:
    -help                  displays usage text
    -log                   redirect messages to system log file
    -swf <filename.swf>    output a Flash movie
    -param <name> <value>  specifies a named parameter
    -setenv1 <url>         specifies flash environment (Name,Value or XML)
    -setenv2 <url>         specifies flash environment (Name1,Name2... or XML)
    -encoding <encoding>   specifies default encoding of all datasources
    -dump <filename>       dump template content into specified file
    -time                  print processing time

    
This is quite self-explanatory. I'll just give you some examples:
    jgenerate test.swt                  - processes test.swt and generates test.swf
    jgenerate -swf test1.swf test.swt   - processes test.swt and generates test1.swf
    jgenerate -swf test1.swf -param Name "Mandrake" -param age 1 test.swt   
                - processes test.swt with two parameters: 
                   Name="Mandrake" and age=1 and generates test1.swf
    
Currently the offline mode is not very effective if you need to process several files because every time you invoke jgenerate, it creates java virtual machine which takes some time. In future releases I will provide some way for batch processing. This means that you will create some file with all the neccesary information included, like what files you want to be processed with all the required parameters. Then you will just run jgenerate and pass this file as a parameter, so it can process all of the files without these delays caused by VM invokation. Note that the online mode does not have this kind of problems.

What all these files under JGenerator directory are for?

When you unzip JGenerator on your computer you have the directory structure like this:
       jgenerator-vX.Y.Z/
          bin/
          doc/
          lib/
          log/
    
jgenerator-vX.Y.Z/bin/
jgenerator-vX.Y.Z/bin/message.txt - a message file which you can edit if you want to.
jgenerator-vX.Y.Z/bin/error.swt & .fla - error.swt is processed and send to the user if there were some errors encountered during Flash template processing.
jgenerator-vX.Y.Z/bin/DefaultSymbolFile.swt & .fla - symbol file used by commands like Table and Charts
jgenerator-vX.Y.Z/bin/jgenerate.cmd - command to run offline JGenerator on Windows
jgenerator-vX.Y.Z/bin/jgenerate - command (bash script by "renard" jmf.renard@free.fr) to run offline JGenerator on Unix

jgenerator-vX.Y.Z/lib/ - contains file jgen.jar. This file you have to add to the classpath of the servlet engine you will be using.
jgenerator-vX.Y.Z/log/ - contains log file jgenerator.log and file with statistic information
jgenerator-vX.Y.Z/ - contains iv.properties file. You can edit this file if you want to configure the JGenerator in some way. The entries in this file are self-explanatory.

General quiestions

Will JGenerator support custom objects?

Yes. But not the Macromedia Generator's object.

Does JGenerator run on the Macintosh platform?

Yes. Check here.

Why not open-source?

Since version 1.2.0 JGenerator is open sourced (Apache style license).

I would like to have some java-based api to JGenerator. Are there any plans for that?

There is some simple API for parsing/generating Flash templates. Here is javadoc to this: GenUtil
This is actually kind of obsolete. Since JGenerator is open sourced you can use its API which is obviously much capable.

Does JGenerator produce the same output formats that Generator does (most impotantly jpeg, and gif)?

The JGenerator produces only Flash content (.swf) right now, but there are plans to provide support for gif and jpeg.

Do you have any performance benchmarks that you could share?

Yes. Check here.

Does this version do multithreading? The reason for wanting to know this is to see if the JGenerator would be up to high volume serving.

The short answer to both questions is Yes.
The long answer is that it does not have any restrictions on that.
I mean that if the servlet engine you are using does create new threads on each new request then the JGenerator makes use of it. JGenerator is thread safe and thread aware.
For example if you run JGenerator with JRun developer's edition then you will have no more than 3 threads in one time, but if you use Tomcat or JRun enterprise edition then you will have as many threads as requests (actually as many as you configure it to have). It means that JGenerator is very well scalable, the more CPUs you have the more users will be served simultaneously.
You can control the number of created threads in iv.properties file with property: com.iv.flash.maxThreads
For more info about the perfomance see benchmark tests.

Also, do the internals of JGenerator use any of the java.awt API - as I was wondering if it would work on a server with no display server.

No, it does not use awt at all. I am planning to use Java2D to produce images in addition to .swf, but all the work will be done in memory, it will not require any display server.

Would there be a way to run Jgenerator off a CD with a JDK on the CD as well, without having to install anything ?

For offline processing the answer is definitely Yes. You probably just have to modify the script which is used to start jgenerator.

Where can I learn about Java API to JGenerator?

You can download the sources and check 'examples/api' directory. It contains several examples on API. I am going to provide more soon. If you didn't find what were you looking for just ask me.

I want to put "powered by JGenerator" button on my page. Do you have some?

Yes, thanx to robin. Here is the image:

Here is the html: <a href="http://www.flashgap.com"><img src="pwdbyjgen.jpg"></a>

Does JGenerator support character sets with foreign characters, e.g. ISO-8859-1 or Latin1?

Yes. Choose Publish settings in Flash. Make sure .swt is checked. Under the Generator tab, locate the data encoding popup menu. Instead of choosing an encoding from the menu, write "Latin1" or "ISO8859-1" (without dash after ISO) without the quotes in the data encoding field and then Export (not Publish!) to .swt file (Generator template).
Now, when JGenerator parses the data sources you'll get foreign characters, e.g. åäö, ßü or ñ!