/*
* Helma License Notice
*
* The contents of this file are subject to the Helma License
* Version 2.0 (the "License"). You may not use this file except in
* compliance with the License. A copy of the License is available at
* http://adele.helma.org/download/helma/license.txt
*
* Copyright 1998-2007 Helma Software. All Rights Reserved.
*
* $RCSfile: session.js,v $
* $Author$
* $Revision$
* $Date$
*/
/**
* @fileoverview Default properties and methods of the session object.
*/
/**
* This object is automatically instantiated as the session property
* of the global object (or global.session).
*
* The session object is a host object representing the session
* for the request that is currently handled by the scripting
* environment.
*
* Each web request is associated with a SessionObject
* representing a 'user session'. Helma recognises requests
* being made from the same client within the same session through
* a session cookie named 'HopSession'. If no such cookie is sent
* with the request, Helma will set that a cookie with a random
* hash with the next response.
*
* Within the scripting environment 'session' always
* represents the current session of the user, who initiated
* the web request.
*
* Besides that default session object, it is also possible
* to fetch active sessions of other clients through the method
* app.getSessions(), and to create additional SessionObjects
* through app.createSession().
*
* For further details also see the JavaDocs for
* helma.framework.core.SessionBean. Since that class is a
* JavaBean all get- and set-methods are also directly
* available as properties of that object.
*
* @type SessionBean
* @see Packages.helma.framework.core.SessionBean
*/
session = new Object();
/**
* The unique identifier for a session object (session cookie).
*
* Contains the unique identifier of the current
* session, which is equivalent to the value stored in
* the HopSession-cookie on the client side.
*
* This property is read-only.
*
* Example:
* res.writeln(session._id);
* 1fcca129764400@eefa22dfab
*
* @type String
*/
session._id = new String();
/**
* The cookie value of a session.
*
* Contains the unique identifier of the current
* session, which is equivalent to the value stored
* in the HopSession-cookie on the client side.
*
* This property is read-only.
*
* Example:
* res.writeln(session.cookie);
* 1fcca129764400@eefa22dfab
*
* @type String
*/
session.cookie = new String();
/**
* Object providing space for run-time user data (user cache).
*
* This property of the SessionObject offers the
* possibility to store arbitrary data within the current
* user session. Note, that this can just be used as a
* temporary storage, since sessions are not stored
* persistently within Helma, and are generally lost when
* the application is restarted.
*
* Example:
* session.data.lastclick = new Date();
* session.data.language = "en";
*
* res.write(session.data);
* TransientNode session
*
* for (var p in session.data)
* res.writeln(p + ": " + session.data[p]);
* lastclick: Fri Jul 12 14:08:20 CEST 2002
* language: en
*
* res.write(session.data.lastclick);
* Fri Jul 12 14:08:20 CEST 2002
*
* res.write(session.data["language"]);
* en
*
* @type TransientNode
*/
session.data = new Object();
/**
* The date a session was created or a login or logout was performed the last time.
*
* This is a convenience property to acknowledge
* that pages are often dependent on the login status
* and must be re-rendered when a user has logged in,
* logged out or is running with a new session.
*
* Contains the timestamp of when the associated
* client started the session, or logged in, or
* logged out the last time, whichever happened most
* recently.
*
* This property is read- and write-able.
*
* Example:
* if (session.lastModified < this.modifytime)
* renderSkin("main");
* else
* res.notModified();
*
* @type Date
*/
session.lastModified = new Date();
/**
* If set, the message will be available during the next request as res.message
*
* @type String
*/
session.message = new String();
/**
* A reference to the user object associated with the current session.
*
* Contains a reference to the UserObject associated
* with this session. This property is null if the client
* has not been logged in yet, or has already been logged
* out. Checking this for being unequal to null is the
* usual way to check whether a client is logged in or not.
* This property is read-only, but can be set through the
* method session.login(User usr).
*
* Example:
* session.login("tobi", "mumbl3");
* res.write(session.user);
* HopObject tobi
*
* res.write(session.user.registered);
* Thu Jun 28 17:25:33 CEST 2001
*
* res.write(session.user["url"]);
* http://helma.org
*
* @type User
*/
session.user = new User();
/**
* A date object representing the time this user's session was last active.
*
* Contains the timestamp of the last web request, that
* has been submitted by that client. This property is
* read-only, but can be set to the current time through
* session.touch().
*
* For new sessions, if the session represents a
* registered user the result equals the date the user
* was logged in the last time; otherwise the result
* equals the current date.
*
* This property is read-only
*
* Example:
* res.write(session.lastActive())
* Thu Nov 02 16:12:13 GMT+01:00 2000
*
* @return Date of last request by this user
* @type Date
*/
session.lastActive = function() {};
/**
* Logs in a user defined by its name and a password phrase, or by directly passing a HopObject.
*
* There are two variants of session.login():
*
* If called with one HopObject argument, the session
* is associated with the user represented by the
* HopObject.
*
* If called with two string arguments, it returns true
* if the user name / password pair matches the stored
* values in the database and false otherwise.
*
* Associates the passed User to that session,
* i.e. logs the client in as that User. The property
* user of the session object will refer to the User.
*
* Example:
* var login = session.login("tobi", "mumbl3");
* if (login)
* res.write("Welcome back, " + session.user.name + "!");
* else
* res.write("Oops, please try again...");
* Welcome back, tobi!
*
* @param {User|String} user either as User object to be logged in or the username to be checked as string
* @param {String} password as String, if the first parameter is a username
* @return Boolean true if the user was logged in, otherwise false
* @type Boolean
*/
session.login = function(user,password) {};
/**
* Logs out a user.
*
* Removes the reference to a User associated with
* the current session, if such a reference exists.
* Additionally the global function onLogout will
* be called.
*
* Example:
* res.write(session);
* [Session for user tobi]
*
* session.logout();
* res.write(session);
* [Anonymous Session]
*/
session.logout = function() {};
/**
* A date object representing the time a user's session was started.
*
* This property is read-only.
*
* Example:
* res.write(session.onSince());
* Fri Aug 10 16:36:36 GMT+02:00 2001
*
* @return Date when the current session was started.
* @type Date
*/
session.onSince = function() {};
/**
* Refreshes the user's session.
*
* The session's expiration date is set to the current date
* plus session timeout. This also happens automatically
* when a user request is sent to Helma.
*
* The lastActive property will be set to the current
* timestamp. Useful to artificially avoid a session timeout.
*
* Example:
* res.writeln(session.lastActive);
* Fri Jul 12 14:40:20 CEST 2002
*
* session.touch();
*
* res.writeln(session.lastActive);
* Fri Jul 12 14:55:20 CEST 2002
*/
session.touch = function() {};