Welcome to the WebMacro project!

Contents:

• About WebMacro
• Where to learn more
• Licensing
• Anatomy of this release
• Installing
• Compiling
• Overview
• Credits

About WebMacro

WebMacro is a free Java development package that allows you to keep HTML and presentational issues out of your Java servlet code--while providing web designers with a simple template language capable of displaying any Java object.

WebMacro was mostly written by Justin Wells, with a lot of help from Yuen-Ping Leung, and crucial support from the WebMacro mailing list.

WebMacro is available for use under the GNU GPL (v2), and the Semiotek Public License Version 1.0 (SPL). You may use it under whichever of these two licenses you prefer. The terms of the GNU GPL appear in the file "COPYING", the terms of the Semiotek Public License are as follows:

/* ====================================================================
 * Copyright (c) 1997-2000 Semiotek Inc.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgment: "This product 
 *    includes software developed by Justin Wells and Semiotek Inc. for 
 *    use in the WebMacro Servlet Framework (http://www.webmacro.org)."
 *
 * 4. The names "Semiotek Inc." and "WebMacro" must not be used to
 *    endorse or promote products derived from this software without
 *    prior written permission. For written permission, please contact
 *    justin@webmacro.org
 *
 * 5. Products derived from this software may not be called "WebMacro"
 *    nor may "WebMacro" appear in their names without prior written
 *    permission of Justin Wells.
 *
 * 6. Redistributions of any form whatsoever must retain the following
 *    acknowledgment: "This product includes software developed by 
 *    Justin Wells and Semiotek Inc. for use in the WebMacro Servlet
 *    Framework (http://www.webmacro.org)."
 *
 * THIS SOFTWARE IS PROVIDED BY SEMIOTEK INC. ``AS IS'' AND ANY EXPRESSED 
 * OR IMPLIED WARRANTIES OR CONDITIONS, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY AND FITNESS FOR A 
 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SEMIOTEK INC. OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 
 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * ====================================================================
 *
 * For more information on Semiotek Inc. and the WebMacro Servlet 
 * Framework project, please see .
 *
 */

Documentation & Contact Information

Full documentation for WebMacro can be found on the WebSite. This README is just an overview.

• WebMacro Website
• Mailing list

A snapshot of the website has been included in the "docs" directory for convenience. It includes Java Doc API's, and everything else you might need to find.

If you are looking for support, found a bug, have a suggestion, or just want to chat with the developers, use the WebMacro mailing list--that's where we are! You may also find that other WebMacro users have answers to your problems as well.

---

Anatomy of this Release

• webmacro.jar contains all the core classes, and needs to be added to your classpath for Java 1.1 use. If you want to use WebMacro under Java2 you should recompile it WITHOUT the collections classes. This will require replacing "com.sun.java.util.collections" with "java.util.collections" in the source code (this is the only change you should need to make).

• collections.jar contains the Sun JDK 1.1 collection classes, which WebMacro uses. You will need these under Java 1.1

• src.zip contains all the .java source code for WebMacro, you only need it if you intend to modify the source

• docs contains all the documentation, including the JavaDoc stuff under webroot/api, and licensing information.

• examples contains a few example WebMacro programs and templates for you to look at to figure out how things work

How To Use It

• This applies to the HelloWorld, Standalone, and GuestBook examples.

  These classes are servlets. Compile them and install them in your servlet directory. Note that there are multiple .class files for GuestBook, so be sure to copy all of them.

  Then follow the instructions below to configure your classpath, and edit the webmacro.properties configuration file.

• Edit the WebMacro.properties file to fix directories for your system You MUST set the directory in which templates live. To use the example code this would be in (perhaps) $HOME/webmacro/examples directory, which must be in your classpath.

  WARNING: Be careful with what is meant by "classpath" here. WebMacro will try to load the properties file using the ClassLoader (and therefore the classpath) which loaded the classes in WebMacro.jar--some servlet runners, JRun for example, set this classpath in a configuration file.

• You need to have the JSDK installed and working, or an equivalent servlet interface, and it has to be in your CLASSPATH.

• You need a Java 1.1 compatible runtime environment to use the WebMacro.jar file distributed with this release. Java2 users should unpack the sources, erase the contents of org/webmacro/util/java2 (pseudo classes which conflict with the real Java2 counterparts), and recompile. See the section on compiling for help.

• You need to include WebMacro.jar in your classpath

• You need to include your own Java directory in your classpath, where you will have your WebMacro handlers and other work. To use the WebMacro examples you might use $HOME/webmacro/examples--it is usually convenient to make this the same directory as your WebMacro.properties files lives in.

Here is an example CLASSPATH:

CLASSPATH=$JAVA_HOME/lib/classes.zip:$HOME/webmacro/webmacro.jar:$HOME/WebMacro/examples:$JSDK_HOME

  

You have unpacked WebMacro in your home directory in this example. $JSDK_HOME contains the "javax" directory in which you have your JSDK base classes, and JAVA_HOME/lib/classes.zip contains the standard library.

Using the examples

Follow the steps above. Then read the comments at the head of each examples .java file for detailed instructions.

Note that the examples are not pre-compiled, you must compile them.

HelloWorld and GuestBook use the WMServlet approach, so put all their .class files in your servlet directory.

TestWM uses the Reactor method. So register Reactor as the servlet with TestWM as its script name (last part of the URL).

How to Compile WebMacro

WebMacro ships with a webmacro.jar file compiled for JDK 1.1.7 and 1.1.8; to use WebMacro with java2 you will need to recompile.

• You need the JSDK sources installed and in your classpath.
• You need a FULLY compliant Java compiler for JDK 1.1.7 or better. Please note that Sun's "javac" and compiler derived form it do not fulfil this requirement, as JDK 1.1 javac has a known bug with respect to blank final variables. Hopefully this will be fixed in Java2/JD1.2--in the meantime you can use IBM's jikes compiler, which IS fully compliant with the Java specification.
• Unpack the src.zip file in a directory that is part of your classpath

To compile under JDK 1.1.8:

• you may have to use "jikes" (compiler from IBM, free) rather than javac, due to a compiler bug in javac relating to final variables.
• WebMacro uses the Java2 collections classes. Under JDK 1.1.8 you need to install and import the com.sun.java.util.collections classes in collections.jar. If you are compiling under Java2 you need to remove the import of these classes in order to compile with the collection classes in java.util.*. Please note that under Java2 if you do not compile against the java.util.* versions of the collection classes, then WebMacro will fail to introspect the Java2 collections classes properly.

See the website for a link to jikes; and check the FAQ and mailing list if you have any trouble.

A few more notes:

• Many classes have test harnesses on them, written as main(), which you can use to test whether things are working for you. See in particular org.webmacro.engine.StreamTemplate, as a good example of how to use WebMacro outside of a servlet.
• There is a 'mkdoc' shell script available to create the JavaDoc documentation in under the webroot directory. This just contains the correct javadoc command, so if you are running under NT you can inspect it to see the correct command line to generate the javadocs.

Overview of the WebMacro System:

WebMacro is similar in many ways to JSP/ASP and other projects in many ways, but differs from those according to our biases:

• We think it is wrong to use markup for a scripting language
• We think it is wrong to embed programs on a web page
• We think it is wrong for web scripts to look like hard programming
• We believe that programming and graphics design are separate tasks

So we have designed a language very much like all the other, but which fits with our biases above.

WebMacro presents two separate interfaces:

1. A template language for web page designers to use, into which they can substitute values from a web program
2. A library and framework for web based programming, for use by technical developers, which is independent of any layout or other graphical concerns

You might be both a graphics designer AND a programmer. Many people are. However I think you will agree that these activies use different sides of your brain--or at least very different kinds of thinking--and it is painful to try and do both at the same time.

Alternately you might be a programmer working with a web designer: By providing the web designer with a list of variables which they can substitute into a page, you keep the designer at some distance from your sensitive program codes. At the same time, the designer is free to take those variables and lay them out any which way they please.

This separation of program code and content is the fundamental idea behind the WebMacro system.

How it works:

WebMacro relies heavily on introspection to glue your template to your back-end. On your back end you stick ordinary Java objects into your Context. WebMacro will then introspect these objects and make them available as properties in the template.

Introspection is fairly expensive so WebMacro avoids doing this at execution time. The first time a class is introspected WebMacro caches the knowledge it gains about the class for efficient use in the future. Templates are also compiled into a form suitable for rapid-execution on first use. (Note that you have to turn on the Template caching in your WebMacro.properties file to see this behavior.)

The overall design of WebMacro is that the state for each request is contained in this Context object: you need to instantiate a new Context for every request (you can create a prototype Context and then clone it for efficiency--this is automatically done for you most of the time.)

Since the state for each request is entirely contained within the Context, templates can be shared between multiple requests. Since templates have no state, they don't need to be synchronized. Since Contexts are accessed by only one thread ("thread per request") they don't need to be synchronized either. Thus you get very good performance out of WebMacro since most of the code can avoid the overhead of synchronization locks.

Finally, WebMacro is a framework. Most of its behavior is loaded dynamically based on the configuration file, WebMacro.properties--the effect of this is that you can radically alter the behavior of WebMacro by replacing the classes named in WebMacro.properties with your own. There are a large number of "plug points" in the design to allow an advanced user to customize WebMacro extensively.

For an ordinary user, though, it's good enough to rely on the default configuration. All you have to do is create contexts and load templates using the provided WebMacro interfaces. See the examples provided in the examples directory for more information.

Credits

WebMacro grew out of various internal projects at Semiotek Inc., and was largely written by me--Justin Wells. It's my third attempt at a template oriented web framework, incorporating the experiences I had with the previous systems.

Yuen-Ping Leung, a close friend and sometimes co-worker of mine, contributed a great deal to the project in its early days--and continues to help out on a regular basis.

A special thanks as well to Jason Hunter and the folks over at the Java Apache project, who have contributed a lot of good ideas and frequently code as well.

Of course there are all the people on the WebMacro mailing lists who have helped out in supporting WebMacro. I used to list you all here, but now you are too numerous!! But WebMacro wouldn't be what it is today without all the help from the list.

I encourage everyone to subscribe to the list and gripe about whatever bothers them, help me find flaws, suggest features, and periodically vote on what direction we should take: send your subscribe message to webmacro-request@webmacro.org

Thanks for all your support!

-Justin

---