MarkLogic Server
XQUERY API DOCUMENTATION
3.1
This page was generated
November  5,  2007
6:02  PM
XQuery Built-In and Modules Function Reference

Built-In: App Server

The application server built-in functions are XQuery functions for many HTTP application server functions. Many of the application server functions (for example, xdmp:get-request-field, xdmp:login, etc.) are executable only on HTTP servers; those functions all have no effect and return the empty sequence when run from an XDBC server.
Function Summary
xdmp:add-response-header Adds an HTTP response header field.
xdmp:get-request-body Returns the POST body of this request, if it is not application/x-www-form-urlencoded.
xdmp:get-request-client-address Returns as a string the internet address of the client from which the HTTP server request is issued.
xdmp:get-request-field Returns the value of a named request field.
xdmp:get-request-field-names Returns a sequence of the request field names.
xdmp:get-request-header Returns the value of a named request header.
xdmp:get-request-header-names Returns a sequence of request header names.
xdmp:get-request-method Returns the HTTP request method.
xdmp:get-request-path Returns the HTTP request path.
xdmp:get-request-username Returns the logged-in username for the request.
xdmp:get-session-field Returns the value of a named HTTP session field.
xdmp:get-session-field-names Returns a sequence of the HTTP session field names.
xdmp:login Logs in a user on an application server that is using application-level authentication and deposits a session cookie.
xdmp:logout Sets the current user to the default user defined in application-level authentication.
xdmp:redirect-response Redirects the App Server response to a given location.
xdmp:set-response-code Sets the response code and message.
xdmp:set-response-content-type Sets the response content-type.
xdmp:set-session-field Sets the value of a named HTTP session field.
xdmp:uri-is-file Returns true if a given URI refers to a file which exists on the current application server.
xdmp:url-decode Converts URL-encoded string to plaintext.
xdmp:url-encode Converts plaintext into URL-encoded string.
Function Detail
xdmp:add-response-header(
$name as xs:string,
$value as xs:string
)  as   empty()
Summary:

Adds an HTTP response header field.

Parameters:
$name : The response header name.
$value : The value to set for this response header.

Example:
  xdmp:add-response-header("meta", "description")

xdmp:get-request-body(  ) as  xs:string?
Summary:

Returns the POST body of this request, if it is not application/x-www-form-urlencoded.

Returns the empty sequence if it is not called from an application server.


Usage Notes:

If the content-type of the POST body is application/x-www-form-urlencoded, it is not available here, but instead is available in its decoded form through xdmp:get-request-field-names() and xdmp:get-request-field().

If there is no content-type header in the request, then the request body defaults to application/x-www-form-urlencoded, and therefore xdmp:get-request-body will return the empty sequence. If you want to read the request body, then the POST must include a content-type header.

You can use this function to process certain types of web service SOAP requests with MarkLogic Server.


Example:
  xdmp:get-request-body()
  => "Contents of POST body."

xdmp:get-request-client-address(  ) as  xs:string?
Summary:

Returns as a string the internet address of the client from which the HTTP server request is issued.

Returns the empty sequence if it is not called from an HTTP server.


Usage Notes:

Use this function if you need to get the internet protocol (IP) address of the requesting client. For example, you can create an application that contains conditional code based on IP addresses (see the example below).

Example:

The following example shows logic which checks if the request was submitted from the "localhost" IP address (127.0.0.1).

  if (xdmp:get-request-client-address() eq "127.0.0.1")
  then "Submitted from localhost."
  else "Only localhost access is allowed for this application."
Example:
  xdmp:get-request-client-address()
  => "127.0.0.1"

xdmp:get-request-field(
$name as xs:string,
[$default as xs:string]
)  as   xs:string*
Summary:

Returns the value of a named request field.

Parameters:
$name : Request field name.
$default (optional): A default value to return if there is no request field.

Example:
  xdmp:get-request-field("index")
  => "10"

xdmp:get-request-field-names(  ) as  xs:string*
Summary:

Returns a sequence of the request field names.

Example:
  xdmp:get-request-field-names()
  => ("section", "name", ...)

xdmp:get-request-header(
$name as xs:string,
[$default as xs:string]
)  as   xs:string*
Summary:

Returns the value of a named request header.

Parameters:
$name : Request header name.
$default (optional): A default value to return if there is no request header.

Example:
  xdmp:get-request-header("A")
  => "foo"

xdmp:get-request-header-names(  ) as  xs:string*
Summary:

Returns a sequence of request header names.

Example:
  xdmp:get-request-header-names()
  => ("A", "B", ...)

xdmp:get-request-method(  ) as  xs:string
Summary:

Returns the HTTP request method.

Example:
  xdmp:get-request-method()
  => "GET"

xdmp:get-request-path(  ) as  xs:string
Summary:

Returns the HTTP request path.

Example:
  xdmp:get-request-path()
  => "/example.xqy"

xdmp:get-request-username(  ) as  xs:string
Summary:

Returns the logged-in username for the request.

Example:
  xdmp:get-request-username()
  => "fred"

xdmp:get-session-field(
$name as xs:string,
[$default as item()*]
)  as   item()*
Summary:

Returns the value of a named HTTP session field.

Parameters:
$name : The name of the session field.
$default (optional): A default value to return if there is no session field.

Example:
  xdmp:get-session-field("user")
  => "marklogic"

xdmp:get-session-field-names(  ) as  xs:string*
Summary:

Returns a sequence of the HTTP session field names.

Example:
  xdmp:get-session-field-names()
  => ("user", "role", "action", "index")

xdmp:login(
$name as xs:string,
[$password as xs:string?]
)  as   xs:boolean
Summary:

Logs in a user on an application server that is using application-level authentication and deposits a session cookie. Returns true on success, false on failure.

If the user calling this function has the xdmp:login privilege, this function can be called without a password or with the empty sequence as the password. In this case, login will succeed if the specified user exists.


Parameters:
$name : The username of the user to be logged in.
$password (optional): The user's password. The password is not needed if the user calling the function has the xdmp:login execute privilege.

Example:
  xdmp:login("mark","secret")
  => true() -- if user "mark" has password "secret"
Example:
  xdmp:login("username") or xdmp:login("username", ()) 
  => true() -- if user calling the function has the 
               xdmp:login privilege
Example:
  xdmp:login("username") or xdmp:login("username", ()) 
  => SEC-PRIV exception if the user calling the function does 
              not have the xdmp:login privilege
Example:
  xdmp:login("username")
  => true() -- if current user has the xdmp:login privilege
Example:
  xdmp:login("username")
  => SEC-PRIV exception if current user does not have the 
              xdmp:login privilege

xdmp:logout(  ) as  empty()
Summary:

Sets the current user to the default user defined in application-level authentication.

Example:
  xdmp:logout()
  => ()

xdmp:redirect-response(
$name as xs:string
)  as   empty()
Summary:

Redirects the App Server response to a given location.

Parameters:
$name : The redirect URL.

Example:
  xdmp:redirect-response("http://marklogic.com/howtobuy.xqy")

xdmp:set-response-code(
$code as xs:integer,
$message as xs:string
)  as   empty()
Summary:

Sets the response code and message.

Parameters:
$code : The response code.
$message : The response message.

Example:
  xdmp:set-response-code(204,"No Content")

xdmp:set-response-content-type(
$name as xs:string
)  as   empty()
Summary:

Sets the response content-type.

Parameters:
$name : The content type.

Example:
  xdmp:set-response-content-type("text/html")

xdmp:set-session-field(
$name as xs:string,
$value as item()*
)  as   item()*
Summary:

Sets the value of a named HTTP session field.

Parameters:
$name : The name of the session field.
$value : The value of the session field.

Example:
  xdmp:set-session-field("user", "marklogic")
  => "marklogic"

xdmp:uri-is-file(
$uri as xs:string
)  as   xs:boolean?
Summary:

Returns true if a given URI refers to a file which exists on the current application server. Returns false if the file does not exist. Returns the empty sequence if the URI is the empty sequence.

Parameters:
$uri : The URI to check. If the URI begins with a "/", it is relative to the root directory of the application server. Otherwise, it is relative to the current request URI.

Example:
  xdmp:uri-is-file("apppages/test.xml")
  => true if test.xml exists in "apppages" sub-directory 
  relative to the directory of the file containing the request.
Example:
  xdmp:uri-is-file("/sub-directory/test.xml")
  => true if test.xml exists in "sub-directory" relative 
  to the root directory of the application server.

xdmp:url-decode(
$encoded as xs:string
)  as   xs:string
Summary:

Converts URL-encoded string to plaintext.

Parameters:
$encoded : Encoded text to be decoded.

Example:
  xdmp:url-decode("Why+not%3f")
  => "Why not?"

xdmp:url-encode(
$plaintext as xs:string,
[$noSpacePlus as xs:boolean]
)  as   xs:string
Summary:

Converts plaintext into URL-encoded string.

Parameters:
$plaintext : Plaintext to be encoded.
$noSpacePlus (optional): True to encode space as "%20" instead of "+".

Example:
  xdmp:url-encode("Why not?")
  => "Why+not%3f"