JVC - Java View Controller

What is JVC?

JVC is a tool for creating Java web applications.

Most well designed web applications separate their components into models, views and controllers. JVC creates the view and controller part of your web application (you are free to use any model implementation you like).

JVC is simple and the web applications it creates are fast because the requests are processed by pre-compiled Java code. For even better performance we recommend configuring your web server so that the static content is handled by an Apache server instead of by your JVC app.

Writing a JVC web app is simple because you just write POJO's and you don't need any xml configuration files.

JVC uses standard open source tools like Tomcat, Ant and Log4j.

JVC applications share many similarities with Ruby on Rails applications, but since JVC apps are written in Java many errors can be caught while compiling instead of during runtime.

What does JVC do?

1. Creates web application project skeletons (see Hello JVC section)
2. Converts view templates into page generator and controller classes (as part of the build process)
3. Dispatches page requests to the appropriate page generator and controller and returns their response (at run time).

What do you do?

• Add your 'business logic' code to the controller classes that were generated during the build process.
• Add a persistence mechanism, probably using an ORM solution like SqlMapper + Persist or Hibernate (if you're a masochist).

View Templates

And one meta tag pair:

During the build process view templates get turned into page generators and controllers.

Page Generators

You can look at the page generator source code, but don't modify it (your changes will be overwritten the next time the project is rebuilt). The page generators for the view templates in the view directory become corresponding Java classes located in the src/<package_prefix>/generators/ directory (you specified the package_prefix when you create your project or it defaults to no package, see Hello JVC section). Note: if you build your project with the -Dline.numbers=true command line argument then the each line of the page generator code will contain a comment indicating which part of which template it came from.

Controllers

All the page controllers corresponding to the view templates in a particular directory extend a 'local' base controller, and all these 'local' base controllers in turn extend a single 'global' base controller. See the Hello JVC section for an example.

The generated controller classes don't do anything other than provide access to the JVCRequestContext, but they give you a place to wire in your web application code while keeping it separate from your views. Page specific code can be added to in the page controllers and common code can be put in the 'local' or 'global' base controllers.

If you look at the source code for a PageGenerator.java class you will see that on the first line of each page generator method the corresponding page controller object is instantiated and stored in the variable controller. This is how your page view and controller can interact.

Request Dispatcher and JVCRequestContext

In the Tomcat server the JVC request dispatcher is a simple servlet.

The only JVC class you, as a developer, really need to know about is the JVCRequestContext. When the request dispatcher receives a request it decides if it is for static or dynamic content. If its for dynamic content then it creates a JVCRequestContext and instantiates the appropriate controller and PageGenerator and passes them the JVCRequestContext.

For more details please see the javadocs

Hello JVC

Lets assume you installed JVC in your ~/dev/jvc/ directory then you can create a hello_jvc app by typing:

~/dev/jvc$ ant new_project -Dname=hello_jvc
~/dev/jvc$ cd ../hello_jvc
~/dev/hello_jvc$ ant test # run unit tests (optional)
~/dev/hello_jvc$ $CATALINA_HOME/bin/shutdown.sh -force
~/dev/hello_jvc$ ant install
~/dev/hello_jvc$ $CATALINA_HOME/bin/startup.sh

or instead of the last 3 commands you can just type:

~/dev/hello_jvc$ ant rev

At this point you should be able to go to http://localhost:8080/hello_jvc and see your new web app (assuming your Tomcat server is in its default configuration).
(Note: you may have to start/stop Tomcat and install your app as root if you installed Tomcat as root).

Now lets look at what was created.

hello_jvc/
  build.xml
  conf/
    ...
  dist/
    ...
  docs/
    ...
  lib/
    ...
  src/
    Application.java
    controllers/
      BaseController.java
      docs/
        BaseDocsController.java
        examples/
          BaseExamplesController.java
          FormTestController.java
          RequestController.java
          BouncerController.java
          RedirectController.java
          TagController.java
      ...
    generators/
      BaseGenerator.java
      docs/
        examples/
          BouncerGenerator.java
          FormTestGenerator.java
          RedirectGenerator.java
          RequestGenerator.java
          TagGenerator.java
      ...
    test/
      ...
    utils/
      Helpers.java
  view/
    docs/
      examples/
        bouncer.jhtml
        formTest.jhtml
        redirect.jhtml
        _request.jhtml
        request.jhtml
        tag.jhtml
      ...
    shared/
      ...
    static/
      ...
    tests/
      ...

Notice how, for example, the tag.jhtml view template spawns the TagGenerator.java page generator and the TagController.java, BaseExamplesController.java and BaseController.java controllers.

Use the -Dpkg.prefix option when creating your application to cause the generated code to be put into your own java package. For example: if you are creating a web app called my_app and want your code to be in the package com.acme then type: ant new_project -Dname=my_app -Dpkg.prefix=com.acme

Tips and Tricks

• Included template file names must start with underscore character (ie. [[+ _include_me.jhtml ]]) to distinguish them from normal view template files.
• When you rebuild your app the generator tool will regenerate the page generator source file if the corresponding view template has been modified, but it doesn't check if any included files have been modified, so when you edit an included view template file you should use add the -Dregen=t to your ant call. For example: ant install -Dregen=t
• To specify an absolute link to a page in your app you need to prepend the rc.contextPath() or just use the JVCRequestContext.makeLink() method (ie. [[= rc.makeLink("click me", "/path/relative/to/view/directory.html") ]])
• Redirects are implemented by throwing a NonStandardResponseException so if you call JVCRequestContext.redirect() inside a try...catch block be sure to re-throw any NonStandardResponseExceptions. This also means you don't have to return after calling JVCRequestContext.redirect().
• Any character in a view template can be escaped by preceeding it with a \ character. For example to display a Java-code-tag use \[[.
• When re-deploying your app you must stop and restart Tomcat or else it will keep using the old version of your app. The ant rev target will do this for you.
• If you get a compile error in a page generator it means you have a syntax error in a view template. To quickly locate the line in the template that caused the problem you can rebuild using the -Ddebug=t flag, which will add line number comments to the page generator source code.
• When building a real web app you will need to add model classes to manage your persistent data. JVC places no restrictions on what model implementation you use, but we like the open source project Persist, especially when used in conjuction with SqlMapper.

Installation