[Helma-user] Helma Howto for Built in User Management with xml db

[Maksim Lin for technical support mailling lists]

In the src for Application.java at line 396 there is the colourful
comment of:
// The whole user/userroot handling is basically old
// ugly obsolete crap. Don't bother.

However for Helma beginners (or even journeyman like myself) who won't
necessarily think to read that bit of src code before trying to use the
default documented user handling when writing a simple app using the
xmlDB and wondering why it doesn't work I thought I'd contribute the
notes below to save time/frustration in the future.

Plus now that I've learnt and documented the functionality, to me it
seems a very handy and easy-to-use way of basic user handling,
esepcially for quick prototyping and demos.

Maks.

Helma Howto for Built in User Management with xml db
==================================

1. Do NOT specify a user collection or mountpoint in Root. 

Explaination: Helma by default will create a 2 hopobjects in any app
that has an empty db folder:
object id=0 is root
object id=1 is a users
and Helmas builtin User management functions are hard-coded to look for
this hopobject "id=1"
Note this goes even for apps using an SQL mapping!

2. You DO need to create a users Prototype. Here you will need at least
"name" and "password" properties. Note that it MUSt be "password" as
this is hardcoded, however you can use any name for the "name" property
as long as you then set the _name internal property. That sentence
sounds a bit weird so perhaps an example will help:

User/type.properties
_name = username
username
password
email
imagefile

As you can see you can have any other properties of your own choosing.

A nice easter egg (from reading the src) is that you can define a
"userprototype" property in app.properties to set the "user" prototype. 
Strangely though, the object id=1 still gets the name "users" and
prototype ref "user" no matter what you set "userprototype" to be but
everything still works as expected.

Note: Actually if you just want users with default "name" and "password"
properties and *nothing* else, then you don't even need a Users
prototype folder at all!

3. To add users, use the Application Prototypes app.registerUser()
method. It will return the newly created user object. If there is an
error registering the new user eeg. a user already exists with that
username) it will return null.

4. To login a user, there is the session.login(username, password)
method. It will return true if the username/password combo is valid.
Lots of other handy methods in app and in session see:
http://helma.zumbrunn.net/reference/core/app.html
http://helma.zumbrunn.net/reference/core/session.html