Difference between revisions of "Sessions Module"

From BaseX Documentation
Jump to navigation Jump to search
(Created page with "This XQuery Module can only be called from users with ''Admin'' permissions. It contains functions for accessing and modifying all registered server-side sessi...")
 
 
(49 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
−
As sessions are side-effecting operations, all functions in this module are flagged as ''non-deterministic''. This means that the evaluation order of the functions will not be influenced by the compiler.
+
* The module will be available if the {{Code|basex-api}} library is found in the classpath. This is the case if you use one of the complete distributions of BaseX (zip, exe, war).
 +
* All functions and errors are assigned of the <code><nowiki>http://basex.org/modules/sessions</nowiki></code> namespace, which is statically bound to the {{Code|sessions}} prefix.
 +
* If any of the functions is called outside the servlet context, <code>[[XQuery Errors#BaseX Errors|basex:http]]</code> is raised.
 +
* If a specified session id is not found, <code>[[#Errors|not-found]]</code> is raised.
 +
* As sessions are side-effecting operations, all functions are flagged as ''nondeterministic''. As a result, some query optimizations will be suppressed.
  
−
All functions are assigned to the {{Code|http://basex.org/modules/sessions}} namespace, which must be dynamically imported. In this documentation, the namespace is bound to the {{Code|sessions}} prefix. Errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
+
=Functions=
  
−
If the module is called outside the servlet context, the error [[#BXSE0003|BXSE0003]] is raised. If a specified session is not found, [[#BXSE0004|BXSE0004]] is raised.
+
==sessions:ids==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>sessions:ids() as xs:string*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the IDs of all registered sessions.
 +
|}
 +
 
 +
==sessions:created==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>sessions:created(
 +
  $id  as xs:string
 +
) as xs:dateTime</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the creation time of the session specified by {{Mono|$id}}.
 +
|}
  
−
=Functions=
+
==sessions:accessed==
  
−
==sessions:id==
 
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|sessions:ids||xs:string}}
+
|<pre>sessions:accessed(
−
|-
+
  $id  as xs:string
 +
) as xs:dateTime</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the IDs of all registered sessions.
+
|Returns the last access time of the session specified by {{Mono|$id}}.
 
|}
 
|}
  
 
==sessions:names==
 
==sessions:names==
 +
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|sessions:names|$id as xs:string|xs:string*}}
+
|<pre>sessions:names(
−
|-
+
  $id as xs:string
 +
) as xs:string*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the names of all variables bound to the session specified by {{Mono|$id}}.
+
|Returns the names of all attributes bound to the session specified by {{Mono|$id}}.
 
|}
 
|}
  
 
==sessions:get==
 
==sessions:get==
 +
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|sessions:get|$id as xs:string, $key as xs:string|xs:string?}}<br/>{{Func|sessions:get|$id as xs:string, $key as xs:string, $default as xs:string|xs:string}}
+
|<pre>sessions:get(
−
|-
+
  $id       as xs:string,
 +
  $name    as xs:string,
 +
  $default as item()*    := ()
 +
) as item()*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the value of a variable bound to the session specified by {{Mono|$id}}. If the variable does not exist, an empty sequence or the optionally specified default value is returned instead.
+
|Returns the value of an attribute with the specified {{Code|$name}} from the session with the specified {{Mono|$id}}. If the attribute is unknown, an empty sequence or the optionally specified {{Code|$default}} value will be returned instead.
−
|-
 
−
| '''Errors'''
 
−
|{{Error|BXSE0002|#Errors}} the value of a session variable could not be retrieved.
 
 
|}
 
|}
  
 
==sessions:set==
 
==sessions:set==
 +
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|sessions:set|$id as xs:string, $key as xs:string, $value as xs:string|empty-sequence()}}
+
|<pre>sessions:set(
−
|-
+
  $id     as xs:string,
 +
  $name  as xs:string,
 +
  $value as item()*
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Assigns a value to a variable bound to the session specified by {{Mono|$id}}.
+
|Returns the specified {{Code|value}} to the attribute with the specified {{Code|$name}} from the session with the specified {{Mono|$id}}.
−
|-
 
−
| '''Errors'''
 
−
|{{Error|BXSE0001|#Errors}} a function item was specified as value of a session variable.
 
 
|}
 
|}
  
 
==sessions:delete==
 
==sessions:delete==
 +
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|sessions:delete|$id as xs:string, $key as xs:string|empty-sequence()}}
+
|<pre>sessions:delete(
−
|-
+
  $id   as xs:string,
 +
  $name  as xs:string
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Deletes a variable bound to the session specified by {{Mono|$id}}.
+
|Deletes an attribute with the specified {{Code|$name}} from the session with the specified {{Mono|$id}}.
 
|}
 
|}
  
 
==sessions:close==
 
==sessions:close==
 +
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|sessions:close|$id as xs:string|empty-sequence()}}
+
|<pre>sessions:close(
−
|-
+
  $id as xs:string
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Unregisters the session specified by {{Mono|$id}}.
 
|Unregisters the session specified by {{Mono|$id}}.
Line 80: Line 121:
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
−
! width="5%"|Code
+
! width="110"|Code
−
! width="95%"|Description
+
|Description
−
|-
+
|- valign="top"
−
|{{Code|BXSE0001}}
+
|{{Code|not-found}}
−
|A function item was specified as value of a session attribute.
+
|The specified session is not available.
−
|-
 
−
|{{Code|BXSE0002}}
 
−
|An error occurred while retrieving the value of a session attribute.
 
−
|-
 
−
|{{Code|BXSE0003}}
 
−
|A function was called outside the servlet context.
 
−
|-
 
−
|{{Code|BXSE0004}}
 
−
|The specified session was not found.
 
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.3
 +
* Updated: {{Function||sessions:get}}: Values that have no XQuery type will be returned as strings.
 +
 +
;Version 9.0
 +
* Updated: error codes updated; errors now use the module namespace
 +
 +
;Version 8.4
 +
* Updated: Allow sequences as session values.
  
 
This module was introduced with Version 7.5.
 
This module was introduced with Version 7.5.
−
 
−
[[Category:XQuery]]
 

Latest revision as of 14:52, 31 October 2023

This XQuery Module can only be called from users with Admin permissions. It contains functions for accessing and modifying all registered server-side sessions. This module is mainly useful in the context of Web Applications.

Conventions[edit]

  • The module will be available if the basex-api library is found in the classpath. This is the case if you use one of the complete distributions of BaseX (zip, exe, war).
  • All functions and errors are assigned of the http://basex.org/modules/sessions namespace, which is statically bound to the sessions prefix.
  • If any of the functions is called outside the servlet context, basex:http is raised.
  • If a specified session id is not found, not-found is raised.
  • As sessions are side-effecting operations, all functions are flagged as nondeterministic. As a result, some query optimizations will be suppressed.

Functions[edit]

sessions:ids[edit]

Signature 
sessions:ids() as xs:string*
Summary Returns the IDs of all registered sessions.

sessions:created[edit]

Signature 
sessions:created(
  $id  as xs:string
) as xs:dateTime
Summary Returns the creation time of the session specified by $id.

sessions:accessed[edit]

Signature 
sessions:accessed(
  $id  as xs:string
) as xs:dateTime
Summary Returns the last access time of the session specified by $id.

sessions:names[edit]

Signature 
sessions:names(
  $id  as xs:string
) as xs:string*
Summary Returns the names of all attributes bound to the session specified by $id.

sessions:get[edit]

Signature 
sessions:get(
  $id       as xs:string,
  $name     as xs:string,
  $default  as item()*    := ()
) as item()*
Summary Returns the value of an attribute with the specified $name from the session with the specified $id. If the attribute is unknown, an empty sequence or the optionally specified $default value will be returned instead.

sessions:set[edit]

Signature 
sessions:set(
  $id     as xs:string,
  $name   as xs:string,
  $value  as item()*
) as empty-sequence()
Summary Returns the specified value to the attribute with the specified $name from the session with the specified $id.

sessions:delete[edit]

Signature 
sessions:delete(
  $id    as xs:string,
  $name  as xs:string
) as empty-sequence()
Summary Deletes an attribute with the specified $name from the session with the specified $id.

sessions:close[edit]

Signature 
sessions:close(
  $id  as xs:string
) as empty-sequence()
Summary Unregisters the session specified by $id.

Errors[edit]

Code Description
not-found The specified session is not available.

Changelog[edit]

Version 9.3
  • Updated: sessions:get: Values that have no XQuery type will be returned as strings.
Version 9.0
  • Updated: error codes updated; errors now use the module namespace
Version 8.4
  • Updated: Allow sequences as session values.

This module was introduced with Version 7.5.

Retrieved from "http://docs.basex.org/index.php?title=Sessions_Module&oldid=16678"