Release Notes

Janno - The Jamecs Modular Web Platform
Version 0.10


Copyright (c)2005 Roscopeco Open Technologies & Contributors. 
Licenced as FREE SOFTWARE under the terms of the Apache Software Licence, 2.0
See LICENCE.txt file or for more 
information and full terms and conditions of use.


  + Welcome to Janno
  + Installation
  + Configuration
  + Now what?
  + Troubleshooting
  + Contact Information


  Welcome to Janno, an advanced Web Application Platform that provides the
  foundation for high-quality, cutting edge web-based software systems based on 
  the Java(tm) Servlets specification. Janno is the second iteration of the 
  Jamecs core, and represents a ground up redesign / rewrite with a more 
  explicit IoC design, looser coupling to the eventual goals of Jamecs, and a
  more sophisticated architecture based on the elegant functional simplicity
  allowed by constructor-based dependency injection.
  Janno aims to provide a powerful, flexible foundation for the easy development
  of complex web applications and front end systems. The goal of the Janno, as
  with every Roscopeco Open Tech project, is to provide a high-quality, solidly
  engineered, firmly user-focused platform that makes use of existing best-of-
  breed solutions with the sole aim of making your job easier. Janno provides
  a great many advanced and esoteric features for those really complex cases
  but we try wherever possible to cover the common use-cases with sensible 
  defaults, single parameters, and (the equivalent of) null constructors.
  Janno does not itself provide any specific services for Jamecs, or indeed any
  other web application. Instead, Janno provides an 'empty box' into which 
  standard modules (standard Jar files) can be deployed with a single method
  call. The core of Janno is the Moxy Runtime Tree, which represents the 
  various scopes visible in the servlet container and acts as a root container
  for deployed modules. Moxy provides complete sandboxing for modules, avoiding
  the normal Java classloader delegation and placing the onus on the container
  and the module to agree on a set of individual classes / packages to export
  to other modules, and the request pipeline.
  As mentioned, Janno will eventually become the core of a larger system
  (Jamecs) which will provide a packaged, well documented, easily-installable
  content server system as an open source (possibly commercially-backed) 
  project. This depends very much of course on the interest and involvement 
  in Janno and Jamecs as a whole, and for now the project is really more a 
  platform than a system.

  During the early development cycle we are concentrating on the following
  functionality in Janno. This snapshot includes preliminary versions of all
  of the following features:
    + Advanced constructor-based dependency injection component architecture,
      allowing components to be written in small, concise code files and freeing
      developers from configuration and initialization issues in many cases.
    + Scripting-based configuration from the core up. Janno follows the example
      set by Nanocontainer in aiming to be metadata-language-neutral - all 
      configuration is accomplished by gluing Java objects together in any of
      the (currently five) supported languages. 
    + Tight integration with Servlets 'scopes', by literally mapping a container
      to each scope. As you would expect, these containers inherit components
      from above, and provide a very fine-grained control over precisely what
      components are available with which keys in which sessions and requests.
    + Full support for deployable modules, and associated lifecycle management.
      Adding support for complex systems such as hibernate is simply a case of
      supplying a module Jar with appropriate composition script, and then
      declaring an appropriate parameter (e.g. org.hibernate.Session) in your
      action class constructor.
    + Powerful, easy to use actions written in the Java-based Groovy scripting
      language. These actions are Java classes, and take full advantage of the
      dependency injection component architecture together with other advanced 
      functionality such as automatic mapping of parameters to fields before
      your action is even called, parameter constraints, and much more. 
      We specify Groovy only because we only have an action loader 
      implementation for that language at this point, and there are many 
      difficult problems involved in CDI with non-constructor languages,
      but we fully aim to support other languages for actions.
    + Alternative integration with both traditional Groovy scripts and Groovy
      Template Language for cases where full action functionality is not
      required. Just need to grab a component from the session container and 
      call a method on it? Drop in a one-line script (without even restarting
      your container) like this:
    + Powerful, flexible, easy to use view creation and layout system based on
      Jakarta Velocity template engine, and the Velocity Tools VelocityLayout
      servlet. This is fully integrated with the action-processing features of
      Janno, allowing a view template to be selected by simply returning a 
      appropriate String from an action, and then having the Velocity code in
      that view directly access the fields of the action as required.
      Additionally, where special requirements arise, template designers can 
      access the IoC container directly, to obtain an instance of any registered
      component type in the same way as Java or Groovy code.
  In many respects Janno provides similar functionality to the core of the 
  Spring Application Framework ( in a smaller,
  much more focused package. As with all our projects, at the heart of Janno is
  our firm belief in the fact that it's easier to put dependencies together than
  to break them apart.
  As mentioned, this version exists mainly for the developers, but anyone 
  outside the project is of course welcome to try the system, and we are keen 
  to hear any feedback you may have.
  You can always find the latest stable snapshot by checking out the HEAD branch
  from anonymous CVS:
    cvs -z3 janno    
  The latest stable and snapshot releases, plus all past releases in both
  source and binary form are available from the project homepage. See the
  bottom of this file.


  If you downloaded the source, you should be aware that Janno includes both
  a standard Jar build (with the core class libraries) and a generic 'base'
  web-application (War) with the standard integration and configuration.
  While you are free to build your own Wars based on the Janno jar you should
  be aware that if you do so you will lose many of the automatic configuration
  and other convieniences provided by the war. The recommended way to build
  webapps based on Janno is to either manually unpack and customize the 
  base war, or (even better) to use the Janno Maven plugin which wraps all
  this up for you, with the additional benefit of managing dependencies and 
  so on.
  Since you'll often require the jar alongside the war (for build-time linking)
  you'll probably want to build everything. The main commands you might use:
    maven all                - Build jar, war and all documentation in target/
    maven software           - Build jar and war in target/
    maven jar / maven webapp - Build either the jar or the webapp in target/
  You could also do 'maven site' if you wish, or 'maven javadoc'. Please note
  that we are aware of the 'Multiproject' plugin, which explains why we didn't
  use it.
  If that goes to plan, install the War into your container. Have the container
  unpack it if possible, or unpack it yourself. You will probably be fine to
  run from the War, but then you won't be able to do much. 
  Now start your container. You may prefer to log-watch the first startup to
  see if it breaks, and if so, why it breaks. Assuming all goes to plan,
  you should see quite a lot of output from the standard modules and servlets.
  If all went according to plan you should be able to point your browser at the
  context root to get started. If you see the usual VelocityLayout chatter 
  you're past the hard stuff. We're using Commons Logging at present so you 
  should be able to play about with the logging settings in your container or 
  wherever is appropriate. 
  You can get full details of the goals available with the command:
    maven --usage
  If you are finding you're waiting around a lot for the tests to run you
  can add the 'tests-off' goal to your chain, e.g:
    maven tests-off clean all
  And it will disable unit-tests in the goals that follow it for the duration
  of this build.
  Please note that the reference container for Janno is now Jetty 5.1.4, and
  NOT Tomcat 5.5.x as previously. This is not to say it shouldn't work with
  Tomcat any more (it absolutely, positively should and if it doesn't we need
  to know!), just that we're not testing it or directly supporting it (such as
  we would). 


  Todo. Look below the document root of the unpacked war, where you'll find
  various directories, some even containing short readme files. 
  Also see the wiki at

  Play with it a bit, try things out, see what Groovy can do if you haven't 
  already. Read the Wiki (try the 'browse space' function), and maybe come 
  and join us on the mailing lists:
  Usual mailman -subscribe etc commands on the end of the list name. 
  If you're interesting in developing Webapps based on Janno, you might be
  interested in the Janno Tutorial, which can be found at the website. 
  If you are an administrator looking for a modular web solution, you should
  look at the Janno-based 'Jamecs' integration.


  First port of call: Wiki (  
  Next: Email or the lists.
  Common stumbling blocks:
    IT JUST DOESN'T WORK: Try unpacking the War rather than running from it, 
    check top-level composition syntax (modules.groovy and context.groovy),
    check web.xml maps lifecycle manager, request filter, etc.
    SCRIPTS FAIL WITH ODD ERRORS: Groovy is still pre-release, and is
    evolving. This is less of a problem since we migrated to the new JSR-02
    release (which includes much improved error reporting) but the dynamic
    nature of Groovy means there are a few areas to watch for (dynamic typing
    is checked at runtime remember!)
    I GET (some custom exception, e.g. FatalStartup) DURING STARTUP: Don't
    worry, this is a good thing, because it means you have a problem that is
    traced and provided for. Check out your container logs, look at the wiki,
    and finally hit the mailing lists if you've still no joy. Smile, you're
    better off than this poor guy...
    I GET (some vile RuntimeException, NPE usually) DURING STARTUP: This is
    likely to be a problem, and while it may be something we're working on 
    already we'd like you to let us know, just in case. Even if the exception
    is the result of a misconfiguration or similar, we don't like NPE escaping
    the pipeline and will want to add some proper exception handling.

    I GET (either of the above) WHEN MAKING A REQUEST: This is usually down
    to one of two things - either a problem in web.xml with the <listener> or
    <filter> entries for the lifecycle manager. Bear in mind that both are
    mandatory, and the filter must be mapped to any first-level URL that will
    perform any kind of processing with the container tree (this does not apply
    to velocity templates, for example, since they by default only have access
    to the tree when forwarded to from an action).
  With the persistence module:

    I GET NoClassDefFoundErrors FROM HIBERNATE DURING STARTUP: This is down to
    the Moxy-persistence / Hibernate lazy init incompatibilities mentioned
    above, and is something you'll have to live with for now (it still works).
    Check you have your collections and so on mapped with 'lazy="false"' for 
    the time being. The telltale of this problem is exceptions with the 
    hibernate AbstractTuplizer / CGLIBLazyInitializer at request time. See

  Other stuff:
    I HAVE PROBLEMS USING JANNO WITH (not Jetty): Get Jetty, try again, ask 


  The Jamecs Homepage  :  
  The Project Homepage :
  The Jamecs Wiki      :
  Roscopeco Open Tech  : 
  Moxy                 :
  Picocontainer        :
  Nanocontainer        :
  Groovy               :
  Velocity             :
  Jetty                :
  Jamecs was created, and the project is led, by Ross Bamford, a freelance 
  developer, consultant, and long-time master hacker from Derbyshire in the
  United Kingdom. 

  Roscopeco Open Technologies are commited to the principals of Professional 
  Open Source, and believe in OSS not just as a way to gain kudos and keep
  hackers happy, but as a real, viable, attractive alternative to commercially
  licenced software. We believe that by maintaining a firm commitment to 
  "the full system, free, for everyone" and the open community development we 
  can continue to produce the highest quality software with the widest possible
  audience. Jamecs is, and will remain, Open Source, and we are keen to hear 
  from anyone interested in helping, whether it's with code, content, 
  documentation, or whatever!

  Please remember that this is free software, provided in the hope that it
  will be useful, but with no warranties. If you are having problems with
  Jamecs, please make sure you have read the documentation and looked at
  all other avenues before mailing asking for support. We will always try to 
  help, but are busy and may take a while to respond.
  Mailing lists:     [Help and support list]  [Developer discussion]       [General user discussion]
       [complaints department]