Janno - The Jamecs Modular Web Platform
Version 0.10
RELEASE NOTES and README INFORMATION
====================================
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 http://www.apache.org/licenses/LICENCE-2.0 for more
information and full terms and conditions of use.
CONTENTS
--------
+ Welcome to Janno
+ Installation
+ Configuration
+ Now what?
+ Troubleshooting
+ Contact Information
WELCOME TO JANNO
----------------
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:
sess.getAttribute("session.context").
getComponentInstance(Your.class).method()
+ 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 (http://www.springframework.org/) 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 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jamecs 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.
INSTALLATION
------------
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).
CONFIGURATION
-------------
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 http://wiki.roscopeco.co.uk/display/JAMECS/Overview
NOW WHAT?
---------
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:
jamecs-users@lists.sourceforge.net
jamecs-developers@lists.sourceforge.net
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.
TROUBLESHOOTING
---------------
First port of call: Wiki (http://wiki.roscopeco.co.uk/)
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).
I GET NullPointerException WHEN PERSISTING / RELOADING CLASSES WITH HIBER:
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
above.
Other stuff:
I HAVE PROBLEMS USING JANNO WITH (not Jetty): Get Jetty, try again, ask
again.
CONTACT INFORMATION
-------------------
The Jamecs Homepage : http://jamecs.sourceforge.net/
The Project Homepage : http://sourceforge.net/projects/jamecs
The Jamecs Wiki : http://wiki.roscopeco.co.uk/display/JAMECS/Home
Roscopeco Open Tech : http://roscopeco.co.uk/
Moxy : http://roscopeco.co.uk/moxy/
Picocontainer : http://picocontainer.codehaus.org/
Nanocontainer : http://nanocontainer.codehaus.org/
Groovy : http://groovy.codehaus.org/
Velocity : http://jakarta.apache.org/velocity/
Jetty : http://jetty.mortbay.org/
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:
jamecs-support@lists.sourceforge.net [Help and support list]
jamecs-developers@lists.sourceforge.net [Developer discussion]
jamecs-users@lists.sourceforge.net [General user discussion]
Email: jamecs-devel@roscopeco.co.uk
bitbucket@roscopeco.co.uk [complaints department]
