Difference between revisions of "Session Module"
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 | + | 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 | + | * 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=' | + | |- valign="top" |
− | | | + | | 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''' | ||
− | | | + | |Running the server-side XQuery file {{Code|names.xq}} via <code><nowiki>http://localhost:8080/names.xq</nowiki></code>: |
− | <pre | + | <pre lang='xquery'> |
− | + | import module namespace session = "http://basex.org/modules/session"; | |
− | import module namespace | + | session:names() ! element variable { . } |
− | |||
− | |||
− | |||
− | { | ||
− | |||
− | } | ||
</pre> | </pre> | ||
|} | |} | ||
− | ==session: | + | ==session:get== |
− | {| | + | |
− | |- | + | {| width='100%' |
− | | width=' | + | |- valign="top" |
− | | | + | | width='120' | '''Signature''' |
− | |- | + | |<pre>session:get( |
+ | $name as xs:string, | ||
+ | $default as item()* := () | ||
+ | ) as item()*</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the value of | + | |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''' | ||
− | | | + | |Running the server-side XQuery file {{Code|get.xq}} via <code><nowiki>http://localhost:8080/get.xq?key=user</nowiki></code>: |
− | <pre | + | <pre lang='xquery'> |
− | + | import module namespace session = "http://basex.org/modules/session"; | |
− | import module namespace | + | 'Value of ' || $key || ': ' || session:get($key) |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
</pre> | </pre> | ||
|} | |} | ||
− | ==session: | + | ==session:set== |
− | {| | + | |
− | |- | + | {| width='100%' |
− | | width=' | + | |- valign="top" |
− | | | + | | width='120' | '''Signature''' |
− | |- | + | |<pre>session:set( |
+ | $name as xs:string, | ||
+ | $value as item()* | ||
+ | ) as empty-sequence()</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Binds | + | |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''' | ||
− | | | + | |Running the server-side XQuery file {{Code|set.xq}} via <code><nowiki>http://localhost:8080/set.xq?key=user&value=john</nowiki></code>: |
− | <pre | + | <pre lang='xquery'> |
− | + | import module namespace session = "http://basex.org/modules/session"; | |
− | import module namespace | + | session:set($key, $value), 'Variable 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. | ||
− | |||
− |
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.
Contents
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 thesession
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.