| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) W3C XQuery/XSLT Reference W3C XQuery Functions W3C XQuery Language W3C XSLT Language
This page was generated September 12, 2012 5:59 AM | XQuery & XSLT Built-In & Modules Function Reference
Module: Security
The security function module is installed as the following file: `install_dir/Modules/MarkLogic/security.xqy` where `install_dir` is the directory in which MarkLogic Server is installed. To use the security.xqy module in your own XQuery modules, include the following line in your XQuery prolog: `import module "http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy"` The library uses the `sec:` namespace, predefined in the server. NOTE: When using these functions to administer security for an application, be sure to execute them against the security database configured for your application's database. Function calls in this library can only be executed against a a security database (for example, Security); the database named Security is automatically configured when MarkLogic Server is installed, and it is the default security database. To execute these functions against the security database, you can specify the `database` option in `xdmp:eval` or `xdmp:invoke`, or you can run it in an App Server that has your security database configured as its database.
Function Summary
sec:amp-add-roles | Adds the roles ($role-names) to the list of roles granted to the amp ($namespace, $local-name, $document-uri).
sec:amp-doc-collections | Returns a sequence of strings corresponding to the collection uri's that amps belong to.
sec:amp-doc-permissions | Returns a sequence of permission elements that all newly created amp documents receive.
sec:amp-exists | This function returns true if the specified amp exists in the security database.
sec:amp-get-roles | Returns a sequence of role names for the roles directly assigned to the amp ($namespace, $local-name, $document-uri).
sec:amp-remove-roles | Removes a role ($role-name) from the set of roles included by the amp ($namespace, $local-name, $document-uri).
sec:amp-set-roles | Assigns the amp identified by $namespace, $local-name and $document-uri to have the roles identified by $roles-names.
sec:amps-collection | Returns a string corresponding to the uri for the amps collection.
sec:check-admin | Throws an error if the current user does not have the admin role.
sec:collection-add-permissions | Add the permissions $permissions to the protected collection identified by $uri.
sec:collection-get-permissions | Returns a sequence of permission elements corresponding to the current permissions granted to the protected collection identified by $uri.
sec:collection-remove-permissions | Removes the permissions $permissions from the protected collection identified by $uri.
sec:collection-set-permissions | Sets the permissions of a protected collection identified by $uri to $permissions.
sec:collections-collection | Returns a string corresponding to the uri for the protected collections collection.
sec:compartment-get-roles | This function returns a list of roles in the specifed compartment.
sec:create-amp | Creates a new amp in the system database for the context database.
sec:create-privilege | Creates a new privilege and returns the new privilege-id.
sec:create-role | Creates a new role in the system database for the context database.
sec:create-user | Creates a new user in the system database for the context database.
sec:create-user-with-role | Creates a new user in the system database for the context database.
sec:get-amp | Returns an sec:amp element corresponding to an amp identified by ($namespace, $local-name, $document-uri).
sec:get-collection | Gets the security document corresponding to a protected collection with uri equal to $uri.
sec:get-compartments | This function returns a list of all of the compartments.
sec:get-distinct-permissions | Returns a sequence of permission elements made up of a concatenation of $output-perms and the distinct permission elements of $input-perms.
sec:get-privilege | Returns a sec:privilege element corresponding to a privilege identified by ($action,$kind).
sec:get-role-ids | Returns sequence of unique sec:role-id's that corresponds to the sequence of role names $role-names.
sec:get-role-names | Returns sequence of unique sec:role-name's that corresponds to the sequence of role IDs $role-ids.
sec:get-user-names | Returns sequence of unique sec:user-name's that corresponds to the sequence of user IDs $user-ids.
sec:priv-doc-collections | Returns a sequence of strings corresponding to the collection uri's that privileges belong to.
sec:priv-doc-permissions | Returns a sequence of permission elements that all newly created privilege documents receive.
sec:privilege-add-roles | Adds the roles ($role-names) to the list of roles assigned to the privilege ($action,$kind).
sec:privilege-exists | This function returns true if the specified privilege exists.
sec:privilege-get-roles | Returns a sequence of role names for the roles assigned to the privilege ($action,$kind).
sec:privilege-remove-roles | Removes roles ($role-names) from the roles assigned to the privilege ($action,$kind).
sec:privilege-set-name | Changes the sec:privilege-name of a sec:privilege to $new-privilege-name.
sec:privilege-set-roles | Assigns the privilege ($action,$kind) to have the roles identified by $role-names.
sec:privileges-collection | Returns a string corresponding to the uri for the privileges collection.
sec:protect-collection | Protects a collection $uri with the given permissions ($permissions).
sec:remove-amp | Removes the amp ($namespace, $local-name, $document-uri, $database) and returns true after completion.
sec:remove-privilege | Removes the privilege identified by ($action,$kind).
sec:remove-role | Removes the role ($role-name).
sec:remove-role-from-amps | Removes references to the role ($role-name) from all amps.
sec:remove-role-from-privileges | Removes references to the role ($role-name) from all privileges.
sec:remove-role-from-roles | Removes references to the role ($role-name) from all other roles.
sec:remove-role-from-users | Removes references to the role ($role-name) from all users.
sec:remove-user | Removes the user with name $user-name.
sec:role-add-roles | Adds new roles ($new-roles) to the role specified by $role-name.
sec:role-doc-collections | Returns a sequence of strings corresponding to the collection uri's that roles belong to.
sec:role-doc-permissions | Returns a sequence of permission elements that all newly created role documents receive.
sec:role-exists | This function returns true if the specified role exists in the security database.
sec:role-get-compartment | This function returns the compartment for the specified role.
sec:role-get-default-collections | Returns a sequence of strings correspondinig to the uri's of the role's default collections.
sec:role-get-default-permissions | Returns a sequence of permission elements correspondinig to the role's default permissions.
sec:role-get-description | Returns the description for the specified role.
sec:role-get-roles | Returns a sequence of role names for the roles directly assigned to the given role ($role-name).
sec:role-privileges | Returns a set of privilege elements corresponding to all privileges that a role has.
sec:role-remove-roles | Removes the roles ($role-names) from the set of roles included by the role ($role-name).
sec:role-set-default-collections | Sets the default collections of a role with name $role-name to $collections.
sec:role-set-default-permissions | Sets the default permissions for a role with name $role-name.
sec:role-set-description | Changes the description of the role identified by $role-name to $description.
sec:role-set-name | Changes the sec:role-name of a role from $role-name to $new-role-name.
sec:role-set-roles | Assigns roles (named $role-names) to be the set of included roles for the role ($role-name).
sec:roles-collection | Returns a string corresponding to the uri for the roles collection.
sec:security-collection | Returns a string corresponding to the uri for the Security collection.
sec:security-installed | Returns fn:true() if security has been installed on the current database.
sec:security-namespace | Returns a string corresponding to the uri of the security namespace.
sec:security-version | Returns the current version of the security database.
sec:set-realm | Changes the realm of this security database to $realm.
sec:uid-for-name | Returns the uids for the named user or () if no such user exists.
sec:unprotect-collection | Removes the protection of a collection $uri.
sec:user-add-roles | Adds the roles ($role-names) to the list of roles granted to the user ($user-name).
sec:user-doc-collections | Returns a sequence of strings corresponding to the collection uri's that users belong to.
sec:user-doc-permissions | Returns a sequence of permission elements that all newly created user documents receive.
sec:user-exists | This function returns true if the specified user exists in the security database.
sec:user-get-default-collections | Returns a sequence of strings correspondinig to the uri's of the user's default collections.
sec:user-get-default-permissions | Returns a sequence of permission elements correspondinig to the user's default permissions.
sec:user-get-description | Returns the user's description.
sec:user-get-password-extra | This function returns the extra information for the specified user.
sec:user-get-roles | Returns a sequence of role names for the roles directly assigned to the user ($user-name).
sec:user-privileges | Returns a set of privilege elements corresponding to all privileges that a user has.
sec:user-remove-roles | Removes the roles ($role-names) from the list of roles granted to the user ($user-name).
sec:user-set-default-collections | Sets the default collections of a user with name $user-name to $collections.
sec:user-set-default-permissions | Sets the default permissions for a user with name $user-name.
sec:user-set-description | Changes the description of the user identified by $user-name to $description.
sec:user-set-name | Changes the name of the user from $user-name to $new-user-name.
sec:user-set-password | Changes the password for the user identified by $user-name to $password.
sec:user-set-password-extra | This function sets extra information for the specified user.
sec:user-set-roles | Assigns the user with name $user-name to have the roles identified by $role-names.
sec:users-collection | Returns a string corresponding to the uri for the users collection.
sec:validate-permissions | This function throws the SEC_NOPERMCAP exception if a permission has no capability specified and it throws the SEC-NOPERMROLEID exception if there is no role specified in the permission.
Function Detail
sec:amp-add-roles(
| $namespace as xs:string,
| $local-name as xs:string,
| $document-uri as xs:string,
| $database as xs:unsignedLong,
| $role-names as xs:string*
) as empty-sequence()
Summary: Adds the roles ($role-names) to the list of roles granted to the amp ($namespace, $local-name, $document-uri).
Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify `xs:unsignedLong(0)`.
$role-names : Roles that should be temporarily assumed while the amp is in effect.
Required Privilege: `http://marklogic.com/xdmp/privileges/amp-add-roles` and for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: If an amp with the given identifiers ($namespace, $local-name, $document-uri) is not found, an error is returned. If one of $role-names does not correspond to an existing role, an error is returned. If the current user is limited to granting only his/her roles, and $role is not a subset of the current user's roles, then an error is returned. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:amp-add-roles(
        "http://marklogic.com/my_modules/myspace",
        "my-amp",
        "/MarkLogic/MyModule.xqy",
        0,
        "Contractor")

    (: Adds the "Contractor" role to the list of roles granted to the "my-amp" amp. :)
sec:amp-doc-collections( ) as xs:string*
Summary: Returns a sequence of strings corresponding to the collection uri's that amps belong to.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:amp-doc-collections()

    =>

    http://marklogic.com/xdmp/security
    http://marklogic.com/xdmp/amps
sec:amp-doc-permissions( ) as element(sec:permission)*
Summary: Returns a sequence of permission elements that all newly created amp documents receive.
sec:amp-exists(
| $namespace as xs:string,
| $local-name as xs:string,
| $document-uri as xs:string,
| $database as xs:unsignedLong
) as xs:boolean
Summary: This function returns true if the specified amp exists in the security database.
Parameters:
$namespace : The namespace for the amped function.
$local-name : The local-name of the amped function.
$document-uri : The URI of the module containing the amped function.
$database : The database ID of the module containing the amped function.
Usage Notes: This function must be executed against the security database.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

       sec:amp-exists("my/namespace/uri", "my-function", "/my/module.xqy",
          xdmp:database("my-database"))
sec:amp-get-roles(
| $namespace as xs:string,
| $local-name as xs:string,
| $document-uri as xs:string,
| $database as xs:unsignedLong
) as xs:string*
Summary: Returns a sequence of role names for the roles directly assigned to the amp ($namespace, $local-name, $document-uri).
Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify `xs:unsignedLong(0)`.
Required Privilege: `http://marklogic.com/xdmp/privileges/amp-get-roles`
Usage Notes: If an amp is not found with the given identifiers, an error is returned. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:amp-get-roles(
        "http://marklogic.com/my_modules/myspace",
        "my-amp",
        "/MarkLogic/MyModule.xqy",
        0)
    =>

    Contractor
    Developer
    Temporary
sec:amp-remove-roles(
| $namespace as xs:string,
| $local-name as xs:string,
| $document-uri as xs:string,
| $database as xs:unsignedLong,
| $role-names as xs:string*
) as empty-sequence()
Summary: Removes a role ($role-name) from the set of roles included by the amp ($namespace, $local-name, $document-uri).
Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify `xs:unsignedLong(0)`.
$role-names : Roles that should be temporarily assumed while the amp is in effect.
Required Privilege: `http://marklogic.com/xdmp/privileges/amp-remove-roles` and for role removal: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: If one of $role-names does not correspond to an existing role, an error is returned. If an amp idnetified by ($namespace, $local-name, $document-uri) is not found then an error is returned. If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:amp-remove-roles(
        "http://marklogic.com/my_modules/myspace",
        "my-amp",
        "/MarkLogic/MyModule.xqy",
        0,
        "Developer")

    (: Removes the "Developer" role from the list of roles granted to the "my-amp" amp. :)
sec:amp-set-roles(
| $namespace as xs:string,
| $local-name as xs:string,
| $document-uri as xs:string,
| $database as xs:unsignedLong,
| $role-names as xs:string*
) as empty-sequence()
Summary: Assigns the amp identified by $namespace, $local-name and $document-uri to have the roles identified by $roles-names. Removes previously assigned roles. If an amp with the given identifiers does not exist, an error is returned. If a role name in $role-names does not correspond to an existing role, an error is returned. If $role-names is the empty sequence, all roles assigned to the amp are removed. If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.
Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify `xs:unsignedLong(0)`.
$role-names : Roles that should be temporarily assumed while the amp is in effect.
Required Privilege: `http://marklogic.com/xdmp/privileges/amp-set-roles` and for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:amp-set-roles(
        "http://marklogic.com/my_modules/myspace",
        "my-amp",
        "/MarkLogic/MyModule.xqy",
        0,
        ("Developer", "Temporary"))

    (: Sets the "Developer" and "Temporary" rolea as the roles granted to the "my-amp" amp.
       Any other roles previously in the list are removed. :)
sec:amps-collection( ) as xs:string
Summary: Returns a string corresponding to the uri for the amps collection.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:amps-collection( )

    =>

    http://marklogic.com/xdmp/amps
sec:check-admin( ) as empty-sequence()
Summary: Throws an error if the current user does not have the admin role.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";

    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:check-admin()

    =>  [0.9-ml] SEC-NOADMIN: User does not have admin role.
sec:collection-add-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: Add the permissions $permissions to the protected collection identified by $uri.
Parameters:
$uri : The URI of a collection.
$permissions : New permissions to add to that protected collection. If $permissions is the empty sequence, the function will have no effect.
Required Privilege: `http://marklogic.com/xdmp/privileges/collection-add-permissions`
Usage Notes: If a protected collection with uri equal to $uri is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:collection-add-permissions("http://marklogic.com/dev_modules",
                                   (xdmp:permission("Developer", "insert")))

    (: Adds the Developer(insert) permission to the "dev_modules" collection. :)
sec:collection-get-permissions(
| $uri as xs:string
) as element(sec:permission)*
Summary: Returns a sequence of permission elements corresponding to the current permissions granted to the protected collection identified by $uri.
Parameters:
$uri : The URI of a collection.
Required Privilege: `http://marklogic.com/xdmp/privileges/collection-get-permissions`
Usage Notes: If a protected collection with uri equal to $uri is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:collection-get-permissions("http://marklogic.com/dev_modules")

    =>

    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:capability>read</sec:capability>
      <sec:role-id>5444982746628127945</sec:role-id>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:capability>insert</sec:capability>
      <sec:role-id>5444982746628127945</sec:role-id>
    </sec:permission>
sec:collection-remove-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: Removes the permissions $permissions from the protected collection identified by $uri.
Parameters:
$uri : The URI of a collection.
$permissions : Permissions to be removed from that protected collection. If $permissions is the empty sequence, the function will have no effect.
Required Privilege: `http://marklogic.com/xdmp/privileges/collection-remove-permissions`
Usage Notes: If a protected collection with uri equal to $uri is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:collection-remove-permissions("http://marklogic.com/dev_modules",
                                      (xdmp:permission("Developer", "update")))

    (: Removes the Developer(update) permission from the "dev_modules" collection. :)
sec:collection-set-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: Sets the permissions of a protected collection identified by $uri to $permissions.
Parameters:
$uri : The URI of a collection.
$permissions : New permissions. If the empty sequence is provided, deletes the existing permissions.
Required Privilege: `http://marklogic.com/xdmp/privileges/collection-set-permissions`
Usage Notes: If a protected collection with uri equal to $uri is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:collection-set-permissions("http://marklogic.com/dev_modules",
                                   (xdmp:permission("Developer", "read"),
                                    xdmp:permission("Developer", "update")))

    (: Sets the permissions on "dev_modules" to Developer(read) and Developer(update).
       Any previous permissions on the collection are removed. :)
sec:collections-collection( ) as xs:string
Summary: Returns a string corresponding to the uri for the protected collections collection.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:collections-collection( )

    =>

    http://marklogic.com/xdmp/collections
sec:compartment-get-roles(
| $compartment-name as xs:string
) as element(sec:role)*
Summary: This function returns a list of roles in the specifed compartment.
Parameters:
$compartment-name : The name of the compartment.
Required Privilege: `http://marklogic.com/xdmp/privileges/compartment-get-roles`
Usage Notes: This function must be executed against the security database.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

      sec:compartment-get-roles("my-compartment")
sec:create-amp(
| $namespace as xs:string,
| $local-name as xs:string,
| $document-uri as xs:string,
| $database as xs:unsignedLong,
| $role-names as xs:string*
) as xs:unsignedLong
Summary: Creates a new amp in the system database for the context database. If the tuple ($namespace, $local-name, $document-uri, $database) is not unique, an error is returned. If one of the $role-names does not identify a role, an error is returned. If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned. Returns the amp-id.
Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the module in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify `xs:unsignedLong(0)`.
$role-names : Roles that should be temporarily assumed while the amp is in effect.
Required Privilege: `http://marklogic.com/xdmp/privileges/create-amp` and for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:create-amp(
        "http://marklogic.com/my_modules/myspace",
        "my-amp",
        "/MarkLogic/MyModule.xqy",
        0,
        "Developer")

     (: Creates an amp for the function "my-amp" in the MyModule.xqy module that
        temporarily grants users the "Developer" role. :)
sec:create-privilege(
| $privilege-name as xs:string,
| $action as xs:string,
| $kind as xs:string,
| $role-names as xs:string*
) as xs:unsignedLong
Summary: Creates a new privilege and returns the new privilege-id. For execute privileges, the privilege is initially nothing more than a name. Use the `xdmp:security-assert()` function in your code to associate the privilege with a protected operation. For URI privleges, the `$action` parameter identifies the base URI to be protected. Users must have this privilege to access any of the documents or code under the specified URI. If $action is not unique, an error is returned. If $kind is not one of ("execute", "uri") then en error is returned. If one of the $role-names names a role that does not exist, an error is returned. If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.
Parameters:
$privilege-name : The name of the privilege to create (unique within security database).
$action : Action protected by this privilege. For an Execute Privilege, this is usually a URI describing an activity. For a URI Privilege, this is a base URI used to filter database activities with certain document URIs.
$kind : Either "execute" or "uri".
$role-names : The names of the roles which can perform this action.
Required Privilege: `http://marklogic.com/xdmp/privileges/create-privilege` and for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:create-privilege("mypriv",
                         "http://marklogic.com/xdmp/privileges/mypriv",
                         "execute",
                         "Developer")

    (: Creates an execute privilege, named "mypriv," and assigns it to the
       "Developer" role. :)
sec:create-role(
| $role-name as xs:string,
| $description as xs:string?,
| $role-names as xs:string*,
| $permissions as element(sec:permission)*,
| $collections as xs:string*,
| [$compartment as xs:string?]
) as xs:unsignedLong
Summary: Creates a new role in the system database for the context database. If $role-name is not unique, an error is returned. If one of the $role-names does not identify a role, an error is returned. If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned. Returns the role-id.
Parameters:
$role-name : The name of the role to be created.
$description : A description of the role to be created.
$role-names : A sequence of role names to which the role is assigned.
$permissions : The default permissions for the role.
$collections : The default collections for the role.
$compartment (optional): The compartment to assign to the role.
Required Privilege: `http://marklogic.com/xdmp/privileges/create-role` and for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:create-role(
        "Temporary",
        "Temporary worker access",
        ("filesystem-access"),
        (),
        ("testDocument"))

    (: Creates a new role, named "Temporary," with the default collection,
       named testDocument. :)
sec:create-user(
| $user-name as xs:string,
| $description as xs:string?,
| $password as xs:string,
| $role-names as xs:string*,
| $permissions as element(sec:permission)*,
| $collections as xs:string*
) as xs:unsignedLong
Summary: Creates a new user in the system database for the context database. Returns the user ID of the created user.
Parameters:
$user-name : A unique username. If $user-name is not unique, an error is returned.
$description : A description of the user.
$password : The initial password for this user.
$role-names : The roles (if any) assigned to this user. If one of the $role-names names a role that does not exist, an error is returned.
$permissions : The default permissions granted to this user.
$collections : The URIs for the default collections to which this user has access.
Required Privilege: `http://marklogic.com/xdmp/privileges/create-user` and, for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:create-user(
        "Jim",
        "Jim the temp",
        "newtemp",
        "Temporary",
        (xdmp:permission("security", "read")),
        ("http://marklogic.com/dev_modules"))

     (: Creates a new user, named "Jim," with the role, "Temporary."  "Jim"
        is assigned the default permission, security(read), and the default
        collection, "http://marklogic.com/dev_modules". :)
sec:create-user-with-role(
| $user-name as xs:string,
| $description as xs:string?,
| $password as xs:string,
| $role-names as xs:string*,
| $permissions as element(sec:permission)*,
| $collections as xs:string*
) as xs:unsignedLong
Summary: Creates a new user in the system database for the context database. Returns the user ID of the created user. Also creates a role by the same name and assigns the newly-created user to the newly-created role. Parameters that define roles, permissions, and collections are only applied to the new user.
Parameters:
$user-name : A unique username. If $user-name is not unique, an error is returned.
$description : A description of the user.
$password : The initial password for this user.
$role-names : Additional roles (if any) assigned to this user. If one of the $role-names names a role that does not exist, an error is returned.
$permissions : The default permissions granted to this user.
$collections : The URIs for the default collections to which this user has access.
Required Privilege: `http://marklogic.com/xdmp/privileges/create-user` `http://marklogic.com/xdmp/privileges/create-role` and, for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:create-user-with-role(
        "Jim",
        "Jim the temp",
        "newtemp",
        "Temporary",
        (xdmp:permission("security", "read"),
         xdmp:permission("security", "update")),
        ("http://marklogic.com/dev_modules"))

    (: Creates a new user, named Jim, with the roles, Jim and Temporary.
       Jim is assigned the default permissions, security(read) and security(update),
       and the default collection, "http://marklogic.com/dev_modules". :)
sec:get-amp(
| $namespace as xs:string,
| $local-name as xs:string,
| $document-uri as xs:string,
| $database as xs:unsignedLong
) as element(sec:amp)?
Summary: Returns an sec:amp element corresponding to an amp identified by ($namespace, $local-name, $document-uri). If no such amp is found, an error is returned.
Parameters:
$namespace : Namespace of the function to which the amp applies.
$local-name : Name of function to which the amp applies.
$document-uri : URI of the document in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify `xs:unsignedLong(0)`.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:get-amp(
        "http://marklogic.com/xdmp/alert",
        "action-insert",
        "/MarkLogic/alert.xqy",
        0)
    =>

    <sec:amp xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:amp-id>2840630016131588040</sec:amp-id>
      <sec:namespace>http://marklogic.com/xdmp/alert</sec:namespace>
      <sec:local-name>action-insert</sec:local-name>
      <sec:document-uri>/MarkLogic/alert.xqy</sec:document-uri>
      <sec:database>0</sec:database>
      <sec:role-ids>
        <sec:role-id>4235709426772438321</sec:role-id>
      </sec:role-ids>
    </sec:amp>
sec:get-collection(
| $uri as xs:string
) as element(sec:collection)
Summary: Gets the security document corresponding to a protected collection with uri equal to $uri.
Parameters:
$uri : The URI of a collection.
Required Privilege: `http://marklogic.com/xdmp/privileges/unprotect-collection` or `http://marklogic.com/xdmp/privileges/collection-set-permissions` or `http://marklogic.com/xdmp/privileges/collection-add-permissions` or `http://marklogic.com/xdmp/privileges/collection-remove-permissions`
Usage Notes: If a protected collection with uri equal to $uri is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:get-collection("http://marklogic.com/cpf/domains")

    =>

    <sec:collection xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:collection-id>403495114666638078</sec:collection-id>
      <sec:uri>http://marklogic.com/cpf/domains</sec:uri>
    </sec:collection>
sec:get-compartments( ) as xs:string*
Summary: This function returns a list of all of the compartments.
Required Privilege: `http://marklogic.com/xdmp/privileges/get-compartments`
Usage Notes: This function must be executed against the security database.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

      sec:get-compartments()
sec:get-distinct-permissions(
| $input-perms as element(sec:permission)*,
| $output-perms as element(sec:permission)*
) as element(sec:permission)*
Summary: Returns a sequence of permission elements made up of a concatenation of $output-perms and the distinct permission elements of $input-perms.
Parameters:
$input-perms : The input permissions.
$output-perms : The output permissions. This is typically an empty sequence.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:get-distinct-permissions(
        (xdmp:permission("security", "read"),
         xdmp:permission("security", "update")),
         ())
    =>

    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:capability>update</sec:capability>
      <sec:role-id>16363340809666818373</sec:role-id>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:capability>read</sec:capability>
      <sec:role-id>16363340809666818373</sec:role-id>
    </sec:permission>
sec:get-privilege(
| $action as xs:string,
| $kind as xs:string
) as element(sec:privilege)?
Summary: Returns a sec:privilege element corresponding to a privilege identified by ($action,$kind). If no such privilege is found, an error is returned.
Parameters:
$action : Action protected by this privilege. For an Execute Privilege, this is usually a URI describing an activity. For a URI Privilege, this is a base URI used to filter database activities with certain document URIs.
$kind : Either "execute" or "uri".
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:get-privilege(
        "http://marklogic.com/xdmp/privileges/admin-module-read",
        "execute")

    =>

    <sec:privilege xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:privilege-id>17293336516617295309</sec:privilege-id>
      <sec:privilege-name>admin-module-read</sec:privilege-name>
      <sec:action>http://marklogic.com/xdmp/privileges/admin-module-read</sec:action>
      <sec:role-ids>
        <sec:role-id>5444982746628127945</sec:role-id>
        <sec:role-id>6629014463670416824</sec:role-id>
      </sec:role-ids>
      <sec:kind>execute</sec:kind>
    </sec:privilege>
sec:get-role-ids(
| $role-names as xs:string*
) as element(sec:role-id)*
Summary: Returns sequence of unique sec:role-id's that corresponds to the sequence of role names $role-names. Duplicate names return a single id. If a role name in $role-names does not correspond to an existing role, an error is returned.
Parameters:
$role-names : A sequence of role names.
Required Privilege: `http://marklogic.com/xdmp/privileges/get-role-ids`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
       "/MarkLogic/security.xqy";

    sec:get-role-ids(("writer", "editor"))

    =>

    <sec:role-id xmlns:sec="http://marklogic.com/xdmp/security">6629014463670416824</sec:role-id>
    <sec:role-id xmlns:sec="http://marklogic.com/xdmp/security">6615337390848046012</sec:role-id>
sec:get-role-names(
| $role-ids as xs:unsignedLong*
) as element(sec:role-name)*
Summary: Returns sequence of unique sec:role-name's that corresponds to the sequence of role IDs $role-ids. Duplicate IDs return a single name.
Parameters:
$role-ids : A sequence of role IDs.
Required Privilege: `http://marklogic.com/xdmp/privileges/get-role-names`
Usage Notes: If a role ID in $role-ids does not correspond to an existing role, an error is returned. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:get-role-names((6629014463670416824,
      	             6615337390848046012))
    =>

    <sec:role-name xmlns:sec="http://marklogic.com/xdmp/security">editor</sec:role-name>
    <sec:role-name xmlns:sec="http://marklogic.com/xdmp/security">writer</sec:role-name>
sec:get-user-names(
| $user-ids as xs:unsignedLong*
) as element(sec:user-name)*
Summary: Returns sequence of unique sec:user-name's that corresponds to the sequence of user IDs $user-ids. Duplicate IDs return a single name.
Parameters:
$user-ids : A sequence of user IDs.
Required Privilege: `http://marklogic.com/xdmp/privileges/get-user-names`
Usage Notes: If a user ID in $user-ids does not correspond to an existing user, an error is returned. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
       "/MarkLogic/security.xqy";

    sec:get-user-names((18325468190304151823,
                        5673246250406350379,
                        11765239768744971597))

    =>

    <sec:user-name xmlns:sec="http://marklogic.com/xdmp/security">Jim</sec:user-name>
    <sec:user-name xmlns:sec="http://marklogic.com/xdmp/security">Sue</sec:user-name>
    <sec:user-name xmlns:sec="http://marklogic.com/xdmp/security">Tom</sec:user-name>
sec:priv-doc-collections( ) as xs:string*
Summary: Returns a sequence of strings corresponding to the collection uri's that privileges belong to.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:priv-doc-collections()

    =>

    http://marklogic.com/xdmp/security
    http://marklogic.com/xdmp/privileges
sec:priv-doc-permissions( ) as element(sec:permission)*
Summary: Returns a sequence of permission elements that all newly created privilege documents receive.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:priv-doc-permissions()

    =>

    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>read</sec:capability>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>update</sec:capability>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>insert</sec:capability>
    </sec:permission>
sec:privilege-add-roles(
| $action as xs:string,
| $kind as xs:string,
| $role-names as xs:string*
) as empty-sequence()
Summary: Adds the roles ($role-names) to the list of roles assigned to the privilege ($action,$kind). If a privilege identified by ($action,$kind) is not found, an error is returned. If one of $role-names does not correspond to an existing role, an error is returned. If the current user is limited to granting only his/her roles, and $role is not a subset of the current user's roles, then an error is returned.
Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
$role-names : Additional roles for the privilege. If $role-names is the empty sequence, the function has no effect.
Required Privilege: `http://marklogic.com/xdmp/privileges/privilege-add-roles` and for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:privilege-add-roles(
        "http://marklogic.com/xdmp/privileges/unprotected-collections",
        "execute",
        ("Temporary"))

    (: Adds the unprotected-collection execute privilege to the Temporary role. :)
sec:privilege-exists(
| $action as xs:string,
| $kind as xs:string
) as xs:boolean
Summary: This function returns true if the specified privilege exists.
Parameters:
$action : The URI of the privilege.
$kind : The kind of privilege: "execute" or uri".
Required Privilege: `http://marklogic.com/xdmp/privileges/get-privilege`
Usage Notes: This function must be executed against the security database.
Example:
    xquery version "1.0-ml";

    (: execute this against the security database :)
    import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

    sec:privilege-exists("http://marklogic.com/xdmp/privileges/get-privilege",
          "execute")
sec:privilege-get-roles(
| $action as xs:string,
| $kind as xs:string
) as xs:string*
Summary: Returns a sequence of role names for the roles assigned to the privilege ($action,$kind). If a privilege with action equal to $action is not found, an error is returned.
Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
Required Privilege: `http://marklogic.com/xdmp/privileges/privilege-get-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:privilege-get-roles(
        "http://marklogic.com/xdmp/privileges/create-role",
         "execute")
    =>

    security
sec:privilege-remove-roles(
| $action as xs:string,
| $kind as xs:string,
| $role-names as xs:string*
) as empty-sequence()
Summary: Removes roles ($role-names) from the roles assigned to the privilege ($action,$kind). If a privilege identified by ($action,$kind) is not found, an error is returned. If one of $role-names does not correspond to an existing role, an error is returned. If the current user is limited to granting only his/her roles, and $role is not a subset of the current user's roles, then an error is returned.
Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
$role-names : Additional roles for the privilege. If $role-names is the empty sequence, the function has no effect.
Required Privilege: `http://marklogic.com/xdmp/privileges/privilege-remove-roles` and for role removal: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:privilege-remove-roles(
        "http://marklogic.com/xdmp/privileges/mypriv",
        "execute", "Contractor")

    (: Removes the specified privilege from the "Contractor" role. :)
sec:privilege-set-name(
| $action as xs:string,
| $kind as xs:string,
| $new-privilege-name as xs:string
) as empty-sequence()
Summary: Changes the sec:privilege-name of a sec:privilege to $new-privilege-name. If a privilege with the given $action and $kind is not found, an error is returned. If $new-privilege-name is not unique, an error is returned.
Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
$new-privilege-name : The new name for the privilege.
Required Privilege: `http://marklogic.com/xdmp/privileges/privilege-set-name`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:privilege-set-name(
        "http://marklogic.com/xdmp/privileges/mypriv",
        "execute",
        "new_name")

    (: Renames the execute privilege with the specified action to "new_name." :)
sec:privilege-set-roles(
| $action as xs:string,
| $kind as xs:string,
| $role-names as xs:string*
) as empty-sequence()
Summary: Assigns the privilege ($action,$kind) to have the roles identified by $role-names. Removes the prviously assigned roles. If a privilege identified by ($action,$kind) is not found, an error is returned. If a role name in $role-names does not correspond to an existing role, an error is returned. If $role-names is the empty sequence, all existing roles for the privilege are removed. If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.
Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
$role-names : New roles that can perform this action. All previously assigned roles will be removed. If $role-names is the empty sequence, the privilege will have no roles assigned.
Required Privilege: `http://marklogic.com/xdmp/privileges/privilege-set-roles` and for role assignment ($role-names not empty sequence): `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:privilege-set-roles(
        "http://marklogic.com/xdmp/privileges/mypriv",
         "execute", "Contractor")

    (: Assigns the privilege with the specified action to the "Contractor" role.
       The privilege is removed from any other roles that had previously been
       assigned the privilege. :)
sec:privileges-collection( ) as xs:string
Summary: Returns a string corresponding to the uri for the privileges collection.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:privileges-collection( )

    =>

    http://marklogic.com/xdmp/privileges
sec:protect-collection(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as xs:unsignedLong
Summary: Protects a collection $uri with the given permissions ($permissions). Returns the unique id of the protected collection. If the protected collection at the specified URI does not exist, it is created.
Parameters:
$uri : The URI of a collection.
$permissions : Permissions governing the collection.
Required Privilege: `http://marklogic.com/xdmp/privileges/protect-collection`
Usage Notes: If $uri is empty or can not be cast as an xs:AnyURI, an error is raised. If a collection with the same uri is already protected, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:protect-collection("http://marklogic.com/dev_modules",
                           (xdmp:permission("Developer", "read"),
                            xdmp:permission("Developer", "insert")))

    (: Users with the "Developer" role can read and insert files in "dev_modules." :)
sec:remove-amp(
| $namespace as xs:string,
| $local-name as xs:string,
| $document-uri as xs:string,
| $database as xs:unsignedLong
) as empty-sequence()
Summary: Removes the amp ($namespace, $local-name, $document-uri, $database) and returns true after completion.
Parameters:
$namespace : The namespace of the function to which the amp applies.
$local-name : The name of the function to which the amp applies.
$document-uri : The URI of the module in which the function is located.
$database : Database ID in which the module is located. If the module is on the filesystem (in the Modules directory), specify `xs:unsignedLong(0)`.
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-amp`
Usage Notes: If an amp ($namespace, $local-name, $document-uri) is not found, an error is returned. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:remove-amp(
        "http://marklogic.com/my_modules/myspace",
        "my-amp",
        "/MarkLogic/MyModule.xqy",
        0)

    (: Removes the "my-amp" amp. :)
sec:remove-privilege(
| $action as xs:string,
| $kind as xs:string
) as empty-sequence()
Summary: Removes the privilege identified by ($action,$kind). If a privilege identified by ($action,$kind) is not found, an error is returned.
Parameters:
$action : The action URI for the privilege. If $kind is a URI privilege, then use the URI to protect for the action parameter.
$kind : Either "execute" or "uri".
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-privilege`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:remove-privilege(
        "http://marklogic.com/xdmp/privileges/mypriv",
        "execute")

    (: Removes the execute privilege with the specified action. :)
sec:remove-role(
| $role-name as xs:string
) as empty-sequence()
Summary: Removes the role ($role-name). If a role with name equal to $role-name is not found, an error is returned. This function also removes all references to the role (privileges, amps, permissions and users).
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-role`
Usage Notes: This function must be executed against the security database.
Example:
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:remove-role("Temporary")

    (: Removes the role, named Temporary. :)
sec:remove-role-from-amps(
| $role-name as xs:string
) as empty-sequence()
Summary: Removes references to the role ($role-name) from all amps. If a role with name equal to $role-name is not found, an error is returned. If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-role-from-amps` and for role removal: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:remove-role-from-amps("Developer")

    (: Removes the "Developer" role from all amps. :)
sec:remove-role-from-privileges(
| $role-name as xs:string
) as empty-sequence()
Summary: Removes references to the role ($role-name) from all privileges. If a role with name equal to $role-name is not found, an error is returned. If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-role-from-privileges` and for role removal: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:remove-role-from-privileges("Developer")

    (: Removes the "Developer" role from all privileges. :)
sec:remove-role-from-roles(
| $role-name as xs:string
) as empty-sequence()
Summary: Removes references to the role ($role-name) from all other roles. If a role with name equal to $role-name is not found, an error is returned. If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-role-from-users` and for role removal: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:remove-role-from-roles("Developer")

    (: Removes the "Developer" role from all other roles. :)
sec:remove-role-from-users(
| $role-name as xs:string
) as empty-sequence()
Summary: Removes references to the role ($role-name) from all users. If a role with name equal to $role-name is not found, an error is returned. If the current user is limited to granting only his/her roles, and $role-name is not a subset of the current user's roles, then an error is returned.
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-role-from-users` and for role removal: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:remove-role-from-users("Contractor")

    (: Removes the "Contractor" role from all users. :)
sec:remove-user(
| $user-name as xs:string
) as empty-sequence()
Summary: Removes the user with name $user-name. If a user with name equal to $user-name is not found, an error is returned.
Parameters:
$user-name : The name of a user.
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-user`
Usage Notes: This function must be executed against the security database.
Example:
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:remove-user("Jim")

    (: Removes the user, named Jim. :)
sec:role-add-roles(
| $role-name as xs:string,
| $new-roles as xs:string*
) as empty-sequence()
Summary: Adds new roles ($new-roles) to the role specified by `$role-name`. If a role with name equal to $role-name is not found, an error is returned. If one of $new-roles does not correspond to an existing role, an error is returned. If the current user is limited to granting only his/her roles, and $new-role is not a subset of the current user's roles, then an error is returned.
Parameters:
$role-name : The name of the role.
$new-roles : The roles to add to the role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-add-roles` and for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-add-roles("Contractor", "filesystem-access")

    (: Adds the "filesystem-access" role to the "Contractor" role and leaves
       any previously assigned roles intact. :)
sec:role-doc-collections( ) as xs:string*
Summary: Returns a sequence of strings corresponding to the collection uri's that roles belong to.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-doc-collections()

    =>

    http://marklogic.com/xdmp/security
    http://marklogic.com/xdmp/roles
sec:role-doc-permissions( ) as element(sec:permission)*
Summary: Returns a sequence of permission elements that all newly created role documents receive.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-doc-permissions()

    =>

    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>read</sec:capability>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>update</sec:capability>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>insert</sec:capability>
    </sec:permission>
sec:role-exists(
| $role-name as xs:string
) as xs:boolean
Summary: This function returns true if the specified role exists in the security database.
Parameters:
$role-name : The role name.
Required Privilege: `http://marklogic.com/xdmp/privileges/get-role`
Usage Notes: This function must be executed against the security database.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

      sec:role-exists("my-role")
sec:role-get-compartment(
| $role-name as xs:string
) as xs:string?
Summary: This function returns the compartment for the specified role.
Parameters:
$role-name : The name of the role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-get-compartment`
Usage Notes: This function must be executed against the security database.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

      sec:role-get-compartment("my-compartmented-role")
sec:role-get-default-collections(
| $role-name as xs:string
) as xs:string*
Summary: Returns a sequence of strings correspondinig to the uri's of the role's default collections.
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-get-default-collections`
Usage Notes: If a role with name $role-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-get-default-collections("Developer")

    =>

    http://marklogic.com/dev_modules
    http://marklogic.com/dev_docs
sec:role-get-default-permissions(
| $role-name as xs:string
) as element(sec:permission)*
Summary: Returns a sequence of permission elements correspondinig to the role's default permissions.
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-get-default-permission`
Usage Notes: If a role with name $role-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-get-default-permissions("Developer")

    =>

    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:capability>update</sec:capability>
      <sec:role-id>16363340809666818373</sec:role-id>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:capability>read</sec:capability>
      <sec:role-id>16363340809666818373</sec:role-id>
    </sec:permission>
sec:role-get-description(
| $role-name as xs:string
) as xs:string
Summary: Returns the description for the specified role.
Parameters:
$role-name : The name of the role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-get-description`
Usage Notes: If a role with name equal to $role-name is not found, an error is returned. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-get-description("Developer")

    => Developer-level access
sec:role-get-roles(
| $role-name as xs:string
) as xs:string*
Summary: Returns a sequence of role names for the roles directly assigned to the given role ($role-name).
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-get-roles`
Usage Notes: If a role with name equal to $role-name is not found, an error is returned. If a role is assigned to itself, the sequence returned from `sec:role-get-roles` does not include itself. To find all of the roles this role inherits (that is, the roles assigned directly to this role, the roles assigned to those roles, and so on), use the `xdmp:role-roles` built-in function. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
     xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-get-roles("Developer")

    =>

    filesystem-access
    pipeline-execution
sec:role-privileges(
| $role-name as xs:string
) as element(sec:privilege)*
Summary: Returns a set of privilege elements corresponding to all privileges that a role has. (Roles are flattened to give a complete set of privileges).
Parameters:
$role-name : The name of a role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-privileges` if the current role is not $role-name.
Usage Notes: If a role with name equal to $role-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:role-privileges("Developer")

    =>

    <sec:privilege xmlns:sec="http://marklogic.com/xdmp/security">
     <sec:privilege-id>12387631775818383068</sec:privilege-id>
      <sec:privilege-name>xdmp:save</sec:privilege-name>
      <sec:action>http://marklogic.com/xdmp/privileges/xdmp-save</sec:action>
      <sec:role-ids>
        <sec:role-id>13749738523688002780</sec:role-id>
      </sec:role-ids>
      <sec:kind>execute</sec:kind>
    </sec:privilege>
    (:  ..... and all other privileges assigned to "Developer." :)
sec:role-remove-roles(
| $role-name as xs:string,
| $role-names as xs:string*
) as empty-sequence()
Summary: Removes the roles ($role-names) from the set of roles included by the role ($role-name). If a role with name equal to $role-name is not found, an error is returned. If one of $role-names does not correspond to an existing role, an error is returned. If the current user is limited to granting only his/her roles, and $old-role is not a subset of the current user's roles, then an error is returned.
Parameters:
$role-name : The name of a role.
$role-names : The name of the roles to remove from the role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-remove-roles` and for role removal: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-remove-roles("Contractor", ("Developer", "alert-internal"))

    (: Removes the "Developer" and "alert-internal" roles from the "Contractor" role. :)
sec:role-set-default-collections(
| $role-name as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: Sets the default collections of a role with name $role-name to $collections.
Parameters:
$role-name : The name of a role.
$collections : A sequence of collections.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-set-default-collections`
Usage Notes: If a role with name $role-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:role-set-default-collections("Developer",
        ("http://marklogic.com/dev_modules",
         "http://marklogic.com/dev_docs"))

    (: Sets the default collections for the role, "Developer," to
    "http://marklogic.com/dev_modules" and "http://marklogic.com/dev_docs".
     Any other previously set collections are removed.
sec:role-set-default-permissions(
| $role-name as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: Sets the default permissions for a role with name $role-name.
Parameters:
$role-name : The name of the role to which the default permissions are set.
$permissions : New permissions. If the empty sequence is provided, deletes the existing permissions.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-set-default-permissions`
Usage Notes: If a role with name $role-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:role-set-default-permissions(
        "Developer",
         (xdmp:permission("security", "read"),
          xdmp:permission("security", "update")))

    (: Sets the default permissions for the "Developer" role to security(read) and
       security(update). :)
sec:role-set-description(
| $role-name as xs:string,
| $description as xs:string
) as empty-sequence()
Summary: Changes the description of the role identified by $role-name to $description.
Parameters:
$role-name : The name of the role.
$description : A description of the role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-set-description` if the currrent role is not $role-name.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-set-description(
        "Developer",
        "Developer-level access")

    (:  Changes the description of the role, "Developer." :)
sec:role-set-name(
| $role-name as xs:string,
| $new-role-name as xs:string
) as empty-sequence()
Summary: Changes the sec:role-name of a role from $role-name to $new-role-name. If $new-role-name is not unique, an error is returned.
Parameters:
$role-name : The name of the role to change.
$new-role-name : The new name for the role.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-set-name`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-set-name("Temporary", "Contractor")

    (: Changes the name of the "Temporary" role to "Contractor."  :)
sec:role-set-roles(
| $role-name as xs:string,
| $role-names as xs:string*
) as empty-sequence()
Summary: Assigns roles (named $role-names) to be the set of included roles for the role ($role-name). Removes previously assigned roles. If a role with name equal to $role-name is not found, an error is returned. If a role name in $role-names does not correspond to an existing role, an error is returned. If $role-names is the empty sequence, all included roles for the role are removed. If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles, then an error is returned.
Parameters:
$role-name : The name of a role.
$role-names : A sequence containing the names of roles to assign to $role-name.
Required Privilege: `http://marklogic.com/xdmp/privileges/role-set-roles` and for role assignment ($role-names not empty sequence): `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:role-set-roles("Contractor", ("Developer", "alert-internal"))

    (: Assigns the "Developer" and "alert-internal" roles to the "Contractor"
       role and removes any other roles previously assigned to "Contractor." :)
sec:roles-collection( ) as xs:string
Summary: Returns a string corresponding to the uri for the roles collection.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:roles-collection( )

    =>

    http://marklogic.com/xdmp/roles
sec:security-collection( ) as xs:string
Summary: Returns a string corresponding to the uri for the Security collection.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:security-collection()

    =>

    http://marklogic.com/xdmp/security
sec:security-installed( ) as xs:boolean
Summary: Returns fn:true() if security has been installed on the current database. Otherwise, returns false.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:security-installed()

    => true
sec:security-namespace( ) as xs:string
Summary: Returns a string corresponding to the uri of the security namespace.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:security-namespace()

    =>

    http://marklogic.com/xdmp/security
sec:security-version( ) as xs:double
Summary: Returns the current version of the security database.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";

    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:security-version()

    => 40100
sec:set-realm(
| $realm as xs:string
) as empty-sequence()
Summary: Changes the realm of this security database to $realm. If the realm is different from the old value this function also invalidates all the existing digest passwords since they will no longer work with the new realm. Warning: this invalidates all user's digest passwords, including the user running this function and users of the Admin Interface (if the Admin Interface is set to digest authentication, which is the default setting); once a user's digest password is invalidated, that user will no longer be able to log in with digest authentication.
Parameters:
$realm : The new realm name to which the security database name is changed.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:set-realm("public")

    (: Sets the realm to "public." :)
sec:uid-for-name(
| $name as xs:string
) as xs:unsignedLong*
Summary: Returns the uids for the named user or () if no such user exists.
Parameters:
$name : The named user.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:uid-for-name("Jim")

    =>

    18325468190304151823
sec:unprotect-collection(
| $uri as xs:string
) as empty-sequence()
Summary: Removes the protection of a collection $uri. This does not remove the collection or any of its documents, but it does remove the protected collection from the security database.
Parameters:
$uri : The URI of the collection from which to remove protections.
Required Privilege: `http://marklogic.com/xdmp/privileges/unprotect-collection`
Usage Notes: If a protected collection with uri equal to $uri is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:unprotect-collection("http://marklogic.com/dev_modules")

    (: Removes protection from the "dev_modules" collection. :)
sec:user-add-roles(
| $user-name as xs:string,
| $role-names as xs:string*
) as empty-sequence()
Summary: Adds the roles ($role-names) to the list of roles granted to the user ($user-name). If a user with name equal to $user-name is not found, an error is returned. If one of the $role-names does not correspond to an existing role, an error is returned. If the current user is limited to granting only his/her roles, and $role is not a subset of the current user's roles, then an error is returned.
Parameters:
$user-name : The name of a user.
$role-names : A sequence of role names.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-add-roles` and for role assignment: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-add-roles("Jim", ("merge", "alert-user"))

    (:  Adds the roles, "merge" and "alert-user," to Jim's existing roles. :)
sec:user-doc-collections( ) as xs:string*
Summary: Returns a sequence of strings corresponding to the collection uri's that users belong to.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-doc-collections()

    =>

    http://marklogic.com/xdmp/security
    http://marklogic.com/xdmp/users
sec:user-doc-permissions( ) as element(sec:permission)*
Summary: Returns a sequence of permission elements that all newly created user documents receive.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-doc-permissions()

    =>

    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>read</sec:capability>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>update</sec:capability>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:role-id>16363340809666818373</sec:role-id>
      <sec:capability>insert</sec:capability>
    </sec:permission>
sec:user-exists(
| $user-name as xs:string
) as xs:boolean
Summary: This function returns true if the specified user exists in the security database.
Parameters:
$user-name : The user name.
Required Privilege: `http://marklogic.com/xdmp/privileges/get-user`
Usage Notes: This function must be executed against the security database.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

      sec:user-exists("my-user")
sec:user-get-default-collections(
| $user-name as xs:string
) as xs:string*
Summary: Returns a sequence of strings correspondinig to the uri's of the user's default collections.
Parameters:
$user-name : The name of a user.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-get-default-collections`
Usage Notes: If a user with name $user-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-get-default-collections("Jim")

    =>

    http://marklogic.com/jims_modules
    http://marklogic.com/jims_docs
sec:user-get-default-permissions(
| $user-name as xs:string
) as element(sec:permission)*
Summary: Returns a sequence of permission elements correspondinig to the user's default permissions.
Parameters:
$user-name : The name of a user.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-get-default-permission`
Usage Notes: If a user with name $user-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-get-default-permissions("Jim")

    =>

    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:capability>update</sec:capability>
      <sec:role-id>16363340809666818373</sec:role-id>
    </sec:permission>
    <sec:permission xmlns:sec="http://marklogic.com/xdmp/security">
      <sec:capability>read</sec:capability>
      <sec:role-id>16363340809666818373</sec:role-id>
    </sec:permission>
sec:user-get-description(
| $user-name as xs:string
) as xs:string
Summary: Returns the user's description. If a user with name equal to $user-name is not found, an error is returned.
Parameters:
$user-name : The name of a user.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-get-description` or the current user is the same as the $user-name.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-get-description("Jim")

    =>

    Jim the temp
sec:user-get-password-extra(
| $user-name as xs:string
) as element(sec:password-extra)?
Summary: This function returns the extra information for the specified user. If the user does not exist, an exception is thrown.
Parameters:
$user-name : The name of the user for whom to return the extra information.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

      sec:user-get-password-extra("Jim")

      (: Returns the extra information for the user, Jim. :)
sec:user-get-roles(
| $user-name as xs:string
) as xs:string*
Summary: Returns a sequence of role names for the roles directly assigned to the user ($user-name). Does not flatten the roles to include "inherited roles." If a user with name equal to $user-name is not found, an error is returned.
Parameters:
$user-name : The name of a user.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-get-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-get-roles("Jim")

    =>

    Developer
    admin
    admin-builtins
sec:user-privileges(
| $user-name as xs:string
) as element(sec:privilege)*
Summary: Returns a set of privilege elements corresponding to all privileges that a user has. (roles are flattened to give a complete set of privileges).
Parameters:
$user-name : The name of a user.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-privileges` if the current user is not $user-name.
Usage Notes: If a user with name equal to $user-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:user-privileges("Jim")

    =>

    <sec:privilege xmlns:sec="http://marklogic.com/xdmp/security">
     <sec:privilege-id>12387631775818383068</sec:privilege-id>
      <sec:privilege-name>xdmp:save</sec:privilege-name>
      <sec:action>http://marklogic.com/xdmp/privileges/xdmp-save</sec:action>
      <sec:role-ids>
        <sec:role-id>13749738523688002780</sec:role-id>
      </sec:role-ids>
      <sec:kind>execute</sec:kind>
    </sec:privilege>
    (:  ..... and all other privileges assigned to "jim." :)
sec:user-remove-roles(
| $user-name as xs:string,
| $role-names as xs:string*
) as empty-sequence()
Summary: Removes the roles ($role-names) from the list of roles granted to the user ($user-name). If a user with name equal to $user-name is not found, an error is returned. If one of $role-names does not correspond to an existing role, an error is returned. If the current user is limited to granting only his/her roles, and one of $role-names is not a subset of the current user's roles, then an error is returned.
Parameters:
$user-name : The name of a user.
$role-names : A sequence of role names.
Required Privilege: `http://marklogic.com/xdmp/privileges/remove-role-from-user` and for role removal: `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-remove-roles("Jim", ("admin", "admin-builtins"))

    (: Removes the "admin" and "admin-builtins" roles from the user, "Jim." :)
sec:user-set-default-collections(
| $user-name as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: Sets the default collections of a user with name $user-name to $collections.
Parameters:
$user-name : The name of a user.
$collections : A sequence of collections.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-set-default-collections`
Usage Notes: If a user with name $user-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
         "/MarkLogic/security.xqy";

    sec:user-set-default-collections("Jim",
        ("http://marklogic.com/jim_modules",
         "http://marklogic.com/jim_docs"))

    (: Sets the default collections for the user, "Jim," to "http://marklogic.com/jim_modules"
       and "http://marklogic.com/jim_docs". Any other previously set collections are removed.
sec:user-set-default-permissions(
| $user-name as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: Sets the default permissions for a user with name $user-name.
Parameters:
$user-name : The name of the user.
$permissions : New permissions. If the empty sequence is provided, deletes the existing permissions.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-set-default-permissions`
Usage Notes: If a user with name $user-name is not found, an error is raised. This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-set-default-permissions(
       "Jim",
        (xdmp:permission("security", "read"),
         xdmp:permission("security", "update")))

    (: Sets the security(read) and security(update) permissions for user, "Jim." :)
sec:user-set-description(
| $user-name as xs:string,
| $description as xs:string
) as empty-sequence()
Summary: Changes the description of the user identified by $user-name to $description.
Parameters:
$user-name : The name of the user.
$description : A description of the user.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-set-description` if the current user is not $user-name.
Usage Notes: This function must be executed against the security database.
Example:
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-set-description(
        "Bill",
        "Senior QA Engineer")

    (:  Changes the description of the user, "Bill." :)
sec:user-set-name(
| $user-name as xs:string,
| $new-user-name as xs:string,
| $password as xs:string
) as empty-sequence()
Summary: Changes the name of the user from $user-name to $new-user-name.
Parameters:
$user-name : The existing name of the user.
$new-user-name : The new name of the user.
$password : The password to set for the user. This can be either the original password for the user or a new password.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-set-name` if the currrent user is not $user-name.
Usage Notes: If a user with name equal to $user-name is not found, an error is returned. If $new-user-name is not unique, an error is returned. This function must be executed against the security database.
Example:
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-set-name(
        "William",
        "Bill",
        "temp")

    (: Changes the username from "Wiiliam" to "Bill" and resets the password to
       "temp". :)
sec:user-set-password(
| $user-name as xs:string,
| $password as xs:string
) as empty-sequence()
Summary: Changes the password for the user identified by $user-name to $password.
Parameters:
$user-name : The name of the user.
$password : The new password. If $password is the empty string, an error is returned.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-set-password` if the currrent user is not $user-name.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-set-password("Jim", "temp")

    (: Changes the password for the user, "Jim," to "temp." :)
sec:user-set-password-extra(
| $user-name as xs:string,
| $extra as element(sec:password-extra)
) as empty-sequence()
Summary: This function sets extra information for the specified user. If the user does not exist, an exception is thrown.
Parameters:
$user-name : The name of the user for whom to set the extra information.
$extra : The extra information to be set for the user.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

      let $extra := <sec:password-extra>
                       <p>Change this password in 30 days</p>
                    </sec:password-extra>

      return sec:user-set-password-extra("Jim", $extra)

      (: Sets the extra information for the user, Jim. :)
sec:user-set-roles(
| $user-name as xs:string,
| $role-names as xs:string*
) as empty-sequence()
Summary: Assigns the user with name $user-name to have the roles identified by $role-names. Removes previously assigned roles. If a user with name equal to $user-name is not found, an error is returned. If a role name in $role-names does not correspond to an existing role, an error is returned. If $role-names is the empty sequence, all existing roles for the user are removed. If the current user is limited to granting only his/her roles, and $role-names is not a subset of the current user's roles or one of the removed roles is not a subset of the current user's roles, then an error is returned.
Parameters:
$user-name : The name of a user.
$role-names : A sequence of role names.
Required Privilege: `http://marklogic.com/xdmp/privileges/user-set-roles` and for role assignment ($role-names not empty sequence): `http://marklogic.com/xdmp/privileges/grant-all-roles` or `http://marklogic.com/xdmp/privileges/grant-my-roles`
Usage Notes: This function must be executed against the security database.
Example:
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:user-set-roles("Jim", ("Developer", "Temporary"))

    (:  Resets the roles for "Jim" to "Developer" and "Temporary. :)
sec:users-collection( ) as xs:string
Summary: Returns a string corresponding to the uri for the users collection.
Usage Notes: This function must be executed against the security database.
Example:
    (: execute this against the security database :)
    xquery version "1.0-ml";
    import module namespace sec="http://marklogic.com/xdmp/security" at
        "/MarkLogic/security.xqy";

    sec:users-collection( )

    =>

    http://marklogic.com/xdmp/users
sec:validate-permissions(
| $permissions as element(sec:permission)*
) as node()*
Summary: This function throws the SEC_NOPERMCAP exception if a permission has no capability specified and it throws the SEC-NOPERMROLEID exception if there is no role specified in the permission.
Parameters:
$permissions : Zero or more permission elements to check.
Usage Notes: This function must be executed against the security database.
Example:
      xquery version "1.0-ml";

      import module namespace sec = "http://marklogic.com/xdmp/security"
          at "/MarkLogic/security.xqy";

      sec:validate-permissions(xdmp:permission("my-role", "read"))

© Copyright 2002-2012 MarkLogic Corporation. All rights reserved.