Difference between revisions of "Session Module"

From BaseX Documentation
Jump to navigation Jump to search
(Created page with "This XQuery Module contains functions for handling session information on an HTTP request that has triggered the query. This module is mainly useful in the con...")
 
m (Text replacement - "</syntaxhighlight>" to "</pre>")
 
(88 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
This [[Module Library|XQuery Module]] contains functions for handling session information on an HTTP request that has triggered the query. This module is mainly useful in the context of [[Web Application]]s.
+
This [[Module Library|XQuery Module]] contains functions for accessing and modifying server-side session information. This module is mainly useful in the context of [[Web Application]]s.
  
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the {{Code|http://basex.org/modules/session}} namespace, which must be dynamically imported. In this documentation, the namespace is bound to the {{Code|session}} prefix.
+
* 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 to the <code><nowiki>http://basex.org/modules/session</nowiki></code> namespace, which is statically bound to the {{Code|session}} prefix.
 +
* If any of the functions is called outside the servlet context, <code>[[XQuery Errors#BaseX Errors|basex:http]]</code> is raised.
 +
* As sessions are side-effecting operations, all functions are flagged as ''nondeterministic''. As a result, some query optimizations will be suppressed.
  
 
=Functions=
 
=Functions=
  
 
==session:id==
 
==session:id==
−
{|
+
 
−
|-
+
{| width='100%'
−
| width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Func|request:session-id||xs:string}}
+
| width='120' | '''Signature'''
−
|-
+
|<pre>session:id() as xs:string</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Returns the session ID of a servlet request.
 
|Returns the session ID of a servlet request.
−
|-
+
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} No session is available for the current client.
 +
|- valign="top"
 +
| '''Examples'''
 +
|Running the server-side XQuery file {{Code|id.xq}} via <code><nowiki>http://localhost:8080/id.xq</nowiki></code>:
 +
<pre lang='xquery'>
 +
import module namespace session = "http://basex.org/modules/session";
 +
'Session ID: ' || session:id()
 +
</pre>
 +
|}
 +
 
 +
==session:created==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>session:created() as xs:dateTime</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the creation time of a session.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} No session is available for the current client.
 +
|}
 +
 
 +
==session:accessed==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>session:accessed() as xs:dateTime</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the last access time of a session.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} No session is available for the current client.
 +
|}
 +
 
 +
==session:names==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>session:names() as xs:string*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns the names of all attributes bound to the current session.
 +
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
−
|The following RESTXQ function can be called via <code><nowiki>http://localhost:8984/restxq/id</nowiki></code>:
+
|Running the server-side XQuery file {{Code|names.xq}} via <code><nowiki>http://localhost:8080/names.xq</nowiki></code>:
−
<pre class="brush:xquery">
+
<pre lang='xquery'>
−
module namespace test = 'http://basex.org/examples/test';
+
import module namespace session = "http://basex.org/modules/session";
−
import module namespace request = "http://exquery.org/ns/restxq/request";
+
session:names() ! element variable { . }
−
declare
 
−
  %restxq:path("/id")
 
−
  function test:id()
 
−
{
 
−
  'ID: ' || request:session-id()
 
−
};
 
 
</pre>
 
</pre>
 
|}
 
|}
  
−
==session:attribute==
+
==session:get==
−
{|
+
 
−
|-
+
{| width='100%'
−
| width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Func|request:attribute|$key as xs:string|xs:string?}}
+
| width='120' | '''Signature'''
−
|-
+
|<pre>session:get(
 +
  $name    as xs:string,
 +
  $default  as item()*    := ()
 +
) as item()*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the value of an attribute bound to the current session, or an empty sequence if no value was bound.
+
|Returns the value of a session attribute with the specified <code>$name</code>. If the attribute is unknown, an empty sequence or the optionally specified {{Code|$default}} value will be returned instead.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
−
|The following RESTXQ function can e.g. be called via <code><nowiki>http://localhost:8984/restxq/get?key=user</nowiki></code>:
+
|Running the server-side XQuery file {{Code|get.xq}} via <code><nowiki>http://localhost:8080/get.xq?key=user</nowiki></code>:
−
<pre class="brush:xquery">
+
<pre lang='xquery'>
−
module namespace test = 'http://basex.org/examples/test';
+
import module namespace session = "http://basex.org/modules/session";
−
import module namespace request = "http://exquery.org/ns/restxq/request";
+
'Value of ' || $key || ': ' || session:get($key)
−
declare
 
−
  %restxq:path("/get")
 
−
  %restxq:query-param("key", "{$key}", "")
 
−
  %restxq:request("{$req}")
 
−
  function test:get($req, $key)
 
−
{
 
−
  'Value of ' || $key || ': ' || request:get-attribute($req, $key)
 
−
};
 
 
</pre>
 
</pre>
 
|}
 
|}
  
−
==session:update-attribute==
+
==session:set==
−
{|
+
 
−
|-
+
{| width='100%'
−
| width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Func|request:update-attribute|$key as xs:string, $value as xs:string|empty-sequence()}}
+
| width='120' | '''Signature'''
−
|-
+
|<pre>session:set(
 +
  $name  as xs:string,
 +
  $value as item()*
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Binds an attribute with the specified value to the current session.
+
|Binds the specified {{Code|$value}} to the session attribute with the specified {{Code|$name}}.
−
|-
+
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|not-found|#Errors}} No session is available for the current client.
 +
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
−
|The following RESTXQ function can e.g. be called via <code><nowiki>http://localhost:8984/restxq/set?key=user&value=john</nowiki></code>:
+
|Running the server-side XQuery file {{Code|set.xq}} via <code><nowiki>http://localhost:8080/set.xq?key=user&value=john</nowiki></code>:
−
<pre class="brush:xquery">
+
<pre lang='xquery'>
−
module namespace test = 'http://basex.org/examples/test';
+
import module namespace session = "http://basex.org/modules/session";
−
import module namespace request = "http://exquery.org/ns/restxq/request";
+
session:set($key, $value), 'Variable was set.'
−
declare
 
−
  %restxq:path("/set")
 
−
  %restxq:query-param("key", "{$key}", "")
 
−
  %restxq:query-param("value", "{$value}", "")
 
−
  %restxq:request("{$req}")
 
−
  function test:set($req, $key, $value)
 
−
{
 
−
  request:set-attribute($req, $key, $value),
 
−
  'Attribute was set.'
 
−
};
 
 
</pre>
 
</pre>
 +
|}
 +
 +
==session:delete==
 +
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>session:delete(
 +
  $name  as xs:string
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Deletes a session attribute with the specified <code>$name</code>.
 +
|- valign="top"
 +
| '''Examples'''
 +
|Running the server-side XQuery file {{Code|delete.xq}} via <code><nowiki>http://localhost:8080/delete.xq?key=user</nowiki></code>:
 +
<pre lang='xquery'>
 +
import module namespace session = "http://basex.org/modules/session";
 +
session:delete($key), 'Variable was deleted.'
 +
</pre>
 +
|}
 +
 +
==session:close==
 +
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>session:close() as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Unregisters a session and all data associated with it.
 +
|}
 +
 +
=Errors=
 +
 +
{| class="wikitable" width="100%"
 +
! width="110"|Code
 +
|Description
 +
|- valign="top"
 +
|{{Code|not-found}}
 +
|No session is available for the current client.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.4
 +
* Updated: Only create session if required.
 +
 +
;Version 9.3
 +
* Updated: {{Function||session: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.0
 +
* 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 18:35, 1 December 2023

This XQuery Module contains functions for accessing and modifying server-side session information. 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 to the http://basex.org/modules/session namespace, which is statically bound to the session prefix.
  • If any of the functions is called outside the servlet context, basex:http 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]

session:id[edit]

Signature 
session:id() as xs:string
Summary Returns the session ID of a servlet request.
Errors not-found: No session is available for the current client.
Examples Running the server-side XQuery file id.xq via http://localhost:8080/id.xq: 
import module namespace session = "http://basex.org/modules/session";
'Session ID: ' || session:id()

session:created[edit]

Signature 
session:created() as xs:dateTime
Summary Returns the creation time of a session.
Errors not-found: No session is available for the current client.

session:accessed[edit]

Signature 
session:accessed() as xs:dateTime
Summary Returns the last access time of a session.
Errors not-found: No session is available for the current client.

session:names[edit]

Signature 
session:names() as xs:string*
Summary Returns the names of all attributes bound to the current session.
Examples Running the server-side XQuery file names.xq via http://localhost:8080/names.xq: 
import module namespace session = "http://basex.org/modules/session";
session:names() ! element variable { . }

session:get[edit]

Signature 
session:get(
  $name     as xs:string,
  $default  as item()*    := ()
) as item()*
Summary Returns the value of a session attribute with the specified $name. If the attribute is unknown, an empty sequence or the optionally specified $default value will be returned instead.
Examples Running the server-side XQuery file get.xq via http://localhost:8080/get.xq?key=user: 
import module namespace session = "http://basex.org/modules/session";
'Value of ' || $key || ': ' || session:get($key)

session:set[edit]

Signature 
session:set(
  $name   as xs:string,
  $value  as item()*
) as empty-sequence()
Summary Binds the specified $value to the session attribute with the specified $name.
Errors not-found: No session is available for the current client.
Examples Running the server-side XQuery file set.xq via http://localhost:8080/set.xq?key=user&value=john: 
import module namespace session = "http://basex.org/modules/session";
session:set($key, $value), 'Variable was set.'

session:delete[edit]

Signature 
session:delete(
  $name  as xs:string
) as empty-sequence()
Summary Deletes a session attribute with the specified $name.
Examples Running the server-side XQuery file delete.xq via http://localhost:8080/delete.xq?key=user: 
import module namespace session = "http://basex.org/modules/session";
session:delete($key), 'Variable was deleted.'

session:close[edit]

Signature 
session:close() as empty-sequence()
Summary Unregisters a session and all data associated with it.

Errors[edit]

Code Description
not-found No session is available for the current client.

Changelog[edit]

Version 9.4
  • Updated: Only create session if required.
Version 9.3
  • Updated: session: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.0
  • Updated: Allow sequences as session values.

This module was introduced with Version 7.5.

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