Session
Session objects are returned by the Session
command. The Session object is automatically created and maintained by the Qodly web server to control the session of a web client (e.g. a browser). This object provides the web developer with an interface to the user session, allowing to manage privileges, store contextual data, share information between processes, and launch session-related preemptive processes.
Functions and properties
.clearPrivileges() removes all the privileges associated to the session |
.expirationDate : string the expiration date and time of the session cookie |
.getPrivileges() : cCollection returns a collection of all the privilege names associated to the session |
.hasPrivilege( privilege : string ) : boolean returns true if the privilege is associated to the session, and false otherwise |
.idleTimeout : integer the inactivity session timeout (in minutes), after which the session is automatically closed by Qodly |
.isGuest() : boolean returns true if the session is a Guest session (i.e. it has no privileges) |
.setPrivileges( privilege : string ) .setPrivileges( privileges : collection ) .setPrivileges( settings : object ) associates the privilege(s) and/or role(s) defined in the parameter to the session |
.storage : object a shared object that can be used to store information available to all requests of the web client |
.userName : string the user name associated to the session |
.clearPrivileges()
.clearPrivileges()
Parameter | Type | Description | |
---|---|---|---|
Does not require any parameters |
Description
The .clearPrivileges()
function removes all the privileges associated to the session. As a result, the session automatically becomes a Guest session.
Example
//Invalidate a session
var isGuest : boolean
session.clearPrivileges()
isGuest = session.isGuest() //isGuest is True
.expirationDate
.expirationDate : string
Description
The .expirationDate
property contains the expiration date and time of the session cookie. The value is expressed as text in the ISO 8601 format: YYYY-MM-DDTHH:MM:SS.mmmZ
.
This property is read-only. It is automatically recomputed if the .idleTimeout
property value is modified.
Example
var expiration : string
expiration = session.expirationDate //eg "2021-11-05T17:10:42Z"
.getPrivileges()
.getPrivileges() : cCollection
Parameter | Type | Description | |
---|---|---|---|
Result | collection | ← | Collection of privilege names (strings) |
Description
The .getPrivileges()
function returns a collection of all the privilege names associated to the session.
Privileges are assigned to a Session using the setPrivileges()
function.
Example
The session role is assigned in an authentify()
datastore function:
//Datastore Class
exposed function authentify( role : string) : string
session.clearPrivileges()
session.setPrivileges( roles : role})
Assuming the authentify()
function is called with the "Medium" role:
var privileges : collection
privileges = Session.getPrivileges()
//privileges : ["simple","medium"]
See also
.hasPrivilege()
.hasPrivilege( privilege : string ) : boolean
Parameter | Type | Description | |
---|---|---|---|
privilege | string | ← | Name of the privilege to verify |
Result | boolean | ← | True if session has privilege, false otherwise |
Description
The .hasPrivilege()
function returns true if the privilege is associated to the session, and false otherwise.
Example
You want to check if the "WebAdmin" privilege is associated to the session:
if (session.hasPrivilege("WebAdmin"))
//Access is granted, do nothing
else
//Display an authentication page
end
.idleTimeout
.idleTimeout : integer
Description
The .idleTimeout
property contains the inactivity session timeout (in minutes), after which the session is automatically closed by Qodly.
If this property is not set, the default value is 60 (1h).
When this property is set, the .expirationDate
property is updated accordingly.
The value cannot be less than 60: if a lower value is set, the timeout is raised up to 60.
This property is read write.
Example
if (session.isGuest())
// A Guest session will close after 60 minutes of inactivity
session.idleTimeout = 60
else
// Other sessions will close after 120 minutes of inactivity
session.idleTimeout = 120
end
.isGuest()
.isGuest() : boolean
Parameter | Type | Description | |
---|---|---|---|
Result | boolean | ← | True if session is a Guest one, false otherwise |
Description
The .isGuest()
function returns true
if the session is a Guest session (i.e. it has no privileges).
Example
if (session.isGuest())
//Do something for Guest user
end
.setPrivileges()
.setPrivileges( privilege : string )
.setPrivileges( privileges : collection )
.setPrivileges( settings : object )
Parameter | Type | Description | |
---|---|---|---|
privilege | string | → | Privilege name |
privileges | collection | → | Collection of privilege names |
settings | Object | → | object with a "privileges" property (string or collection) |
Description
The .setPrivileges()
function associates the privilege(s) and/or role(s) defined in the parameter to the session.
-
In the privilege parameter, pass a string containing a privilege name (or several comma-separated privilege names).
-
In the privileges parameter, pass a collection of strings containing privilege names.
-
In the settings parameter, pass an object containing the following properties:
Property | Type | Description |
---|---|---|
privileges | string or collection | |
roles | string or collection | |
userName | string | User name to associate to the session (optional) |
For more information, please refer to the Privileges section.
If the privileges
or roles
property contains a name that is not declared, it is ignored.
By default when no privilege or role is associated to the session, the session is a Guest session.
The userName
property is available at session object level (read-only).
Example
In a custom authentication method, you set the "WebAdmin" privilege to the user:
var userOK : boolean
... //Authenticate the user
if (userOK) //The user has been approved
var info : object
info = newObject
info.privileges = newCollection("WebAdmin")
session.setPrivileges(info)
end
.storage
.storage : object
Description
The .storage
property contains a shared object that can be used to store information available to all requests of the web client.
When a session
object is created, the .storage
property is empty. Since it is a shared object, this property will be available in the storage
object of the server.
Like the
storage
object of the server, the.storage
property is always "single": adding a shared object or a shared collection to.storage
does not create a shared group.
This property is read only itself but it returns a read-write object.
Example
You want to store the client IP in the .storage
property:
if (session.storage.clientIP == null) //first access
use (session.storage)
session.storage.clientIP = newSharedObject("value", clientIP)
end
end
.userName
.userName : string
Description
The .userName
property contains the user name associated to the session. You can use it to identify the user within your code.
This property is an empty string by default. It can be set using the privileges
property of the setPrivileges()
function.
This property is read only.