RestTools Module with shared, general utility/tool methods for the AURORA REST-server
use RestTools;
# merge metadata with same keys from several entity sources
my $md=mergeMetadata($db,"DATASET",0,0,@my_entities);
# check if a subject has given permissions on an entity object (all permissions, on any level).
# we ask for levels: effective, inherit and grant.
my $ok=hasPerm($db,$subject,$object,["DATASET_CREATE","DATASET_DELETE"],"ALL","ANY",1,1,undef,1);
# get invalid textual permissions in list
my $invalid=getInvalidPermArrayElements($db,["DATASET_BLIPP","DATASET_CREATE"]);
# deconstruct a bitmask into its textual permission names and deliver as an array
my $perms=permToArray($db,$mask)
# create a bitmask based on a list-reference of permission names
my $mask=arrayToPerm($db,$perms);
# get invalid textual flag names returned as a list-reference
my $invalid=getInvalidFlagArrayElements($db,["OMIT","BLIPPBLAPP","MANDATORI"]);
# convert flag bitmask into its textual flag names and deliver as an array
my $flags=flagsToArray($db,$flagmask);
# convert textual flag names into a flag bitmask
my $flagmask=arrayToFlags($db,["OMIT","MANDATORY"]);
# extract and clean parameters from query hash
my ($id, $token, $expire) = _get_params( $query,
id => [$Schema::CLEAN{entity}],
token => [$SysSchema::CLEAN{token}],
expire => [$Schema::CLEAN_GLOBAL{trueint}],
);
# return an error message
my $result=_with_error($content, "User does not have the $required permission on the dataset $id. Unable to fulfill request.")
# return a success message
my $return=_with_success($content);
# get closest task of an entity
my $task=getEntityTask($db,$entity);Collection of general utility/tool functions used by the REST-server. All functions are exported and can be used directly in the namespace of the code that uses it.
Extract and clean parameters from query hash
Input parameters:
query HASH-reference to values that are to be cleaned. This refers to the query-HASH that are delivered automatically to all REST-server methods in AURORA.
params A list of parameters and their cleaning function. One can deliver 1-N number of these parameters in the list as a list of key->value assignments (HASH) where the value is a LIST-reference, eg: my_param_name => [$Schema::CLEAN{entity}]. Any value in the LIST-reference after the cleaning function is optional parameters to the cleaning function.
Returns a LIST of cleaned parameters in return in the same order as they were delivered to the function.
It is useful to assign the LIST to single parameters right away, like so:
my ($my_param1,$my_param2) = _get_param($query,my_param1=>[Schema::CLEAN{entity}],my_param2=>[Schema::CLEAN{entitytype}]);
Returns a correctly formatted error message for the AURORA REST-server.
Accepts input in the following order: content,reason. Content is a HASH-reference to the hash that will contain the error-message and its values. Reason is the textual reason given for the error that just happened.
Always returns 0
Returns a correctly formatted success message for the AURORA REST-server.
Accepts input in the following order: content. Content is the HASH-reference to the hash that will contain the success-message and its values.
Always returns 1
Converts a textual array of flag names into its bitmask
Accepts the following input in this order: db, array. Db is the reference to the AuroraDB-instance used by the REST-server. Array is a LIST-reference to the textual flag names that are to be converted into a bitmask (as if all the flag names are set in the bitmask).
Returns a bitmask.
Convert a textual array of permission names into its bitmask.
Accepts the following input in this order: db, array. Db is the reference to the AuroraDB-instance used by the REST-server. Array is the LIST-reference to the textual permission names that are to be converted into a bitmask (as if all the permission names are set in the bitmask).
Returns a bitmask.
Convert flag bitmask into its textual flag names
Accepts the following input in this order: db, bitmask. Db is the reference to the AuroraDB-instance used by the REST-server. Bitmask is the bitmask of flags that are to be converted to its textual counterpart.
Returns a LIST-reference of the textual flags names that have been set in the bitmask.
Get closest task on an entity in the entity tree.
This method accepts this input in the following order: db, id. Db is the reference to the AuroraDB-instance used by the REST-server. Id is the entity ID from the AURORA database that one wants to get the task of (if any defined).
This method will search from the entity ID specified in id and up the tree to find the closest matching task. If several tasks are defined in the same place in the entity tree, it will select the one that comes first alphabetically on display name of the task entity.
Returns the task ID or 0 if not anyone found or something failed.
Returns the textual flag names in the array that are not valid names for flags.
Accepts the following input in this order: db, array. Db is the reference to the AuroraDB-instance used by the REST-server. Array is the LIST-reference to the list of textual flag names to check for possible invalid items.
Returns a LIST-reference to the flag names that were invalid (if any). If none were invalid, the returned array is empty.
Returns the textual permission names in the array that are not valid names for permissions.
Accepts the following input in this order: db, array. Db is the reference to the AuroraDB-instance used by the REST-server. Array is the LIST-reference to the list of textual permission names to check for possible invalid items.
Returns a LIST-reference to the permission names that were invalid (if any). If none were invalid, the returned array is empty.
Checks if a subject has the specified permission(s) on an object.
Accepts the following input in this order: db, subject, object, perms, pop, oop, effective, inherit, deny, grant.
The meaning of these inputs are as follows:
db Reference to the AuroraDB-instance used by the REST-server.
subject The subject entity id from the AURORA database for which we want to check if has the permission(s).
object The object entity id from the AURORA database for which we want to check the permission(s) on.
perms The textual permission(s) that we want to check for. LIST-reference. The LIST must contain one or more textual permission names that one wants to check if the subject has permission(s) on the object. Be aware that if no permissions are specified the method will return 1 (true) since it has nothing to evaluate. Also note that if you specify a refernce here that is not a LIST or an undefined value, the method will return undef (false).
pop Logical operator for the permissions. If several permissions are specified in the "perms" option, this option decides if one needs to match ALL (logical AND) or ANY (logical OR) of them. Defaults to "ALL". Valid values are "ALL" or "ANY".
oop Logical operator for the entity tree permission levels (effective, inherit, grant and deny). This option decides if one need to match ALL (logical AND) or ANY (logical OR) of the given permission(s) on the levels that one have enabled to be targeted (see the effective-, inherit-, deny- and grant-options below). Defaults to "ALL". Valid values are "ALL" or "ANY". Please note that if one specifies logically absurd conditions, such as this OOP-option set to ALL, while not targeting/enabling any of the four levels (effective, inherit, deny or grant), this method will return 1 (true): it is in other words true that we do not care for the result on all of the levels. So beware of logical monsters.
effective This option decides if one wants to enable/target the effective permission level when checking if the subject has the given permission(s) on the object (effective on the object that is). Defaults to undef (false). Valid values are undef, 0 and 1. Both undef and 0 basically says to not check this level, however, the difference is that if one specifies undef, the method will not attempt to retrieve the effective permissions of the subject on the object, thus saving time and resources. If 0 is specified the effective permissions will be retrieved. 1 means that we want to enable/target the effective permission level.
inherit This option decides if one wants to enable/target the inherited permission level when checking if the subject has the given permission(s) on the object (inherited from above on the object that is). Defaults to undef (false). Valid values are undef, 0 and 1. Both undef and 0 basically says to not check this level, however, the difference is that if one specifies undef, the method will not attempt to retrieve the inherited permissions of the subject on the object, thus saving time and resources. If 0 is specified the inherited permissions will be retrieved. 1 means that we want to enable/target the inherited permission level.
deny This option decides if one wants to enable/target the deny permission level when checking if the subject has the given permission(s) on the object (denied on the object itself that is). Defaults to undef (false). Valid values are undef, 0 and 1. Both undef and 0 basically says to not check this level, however, the difference is that if one specifies undef, the method will not attempt to retrieve the permissions of the subject on the object itself, thus saving time and resources. If 0 is specified the permission(s) on the object will be retrieved. 1 means that we want to enable/target the deny-level. Please note that if one has disabled the deny-level, but enabled the grant-level, the permission(s) on object will still be retrieved. The reason for this is that both the deny- and grant-level resides on the object itself, so one has to retrieve it if one of deny- or grant is enabled.
grant This option decides if one wants to enable/target the grant permission level when checking if the subject has the given permission(s) on the object (granted on the object itself that is). Defaults to undef (false). Valid values are undef, 0 and 1. Both undef and 0 basically says to not check this level, however, the difference is that if one specifies undef, the method will not attempt to retrieve the permissions of the subject on the object itself, thus saving time and resources. If 0 is specified the permission(s) on the object will be retrieved. 1 means that we want to enable/target the grant-level. Please note that if one has disabled the grant-level, but enabled the deny-level, the permission(s) on object will still be retrieved. The reason for this is that both the deny- and grant-level resides on the object itself, so one has to retrieve it if one of deny- or grant is enabled.
Will return an expression that either evaluates to true or false. In the case of false it will be either undef or 0. In the case of true it will be a value >= 1. If the expression returned is false, the subject does not fulfill the given permission(s) on the object. If true is returned, the subject has the given permission(s) on the object (and on the levels enabled with the stated logical operators).
List a folder and its subfolders if so specified and return the result in a hash.
Accepts input in the following order: path, recursive, md5sum, tag.
The meaning of these input options are as follows:
path Path to the root of the folder(s) to list. It should be given as an absolute path. If none is specified it will default to /dev/null.
recursive Sets if the listing is to be done recursive down into possible sub-folders. The default setting is true/1. You can use any expression you want to on this, but it needs to evaluate to true or false.
md5sum Sets if files that are discovered will be md5-summed or not? Default setting is true/1. You can use any expression you want to on this, but it needs to evaluate to true or false.
tag Sets if the folder- and file names are to be tagged as UTF8 or not? Default is true/1. This parameter must evaluate to either true or false. Usually one wants to tag I/O content going in/out so that characters are handled correctly.
This method will return a HASH-reference upon success. Undef upon some failure.
The structure of the HASH-reference is as follows:
%result = (
"FolderA" => {
"." => {
name => "FolderA",
type => "D",
size => SCALAR,
atime => SCALAR,
mtime => SCALAR,
},
"FolderB" => { ... }
"FileX" => { ... }
"FileA" => {
"." => {
name => "FileA",
type => "F",
size => SCALAR,
atime => SCALAR,
mtime => SCALAR,
ctime => SCALAR,
md5 => SCALAR,
},
.
.
"FileZ" > { ... }
)Information on the folder entry itself is stored in the dot-folder ".". This is true for both files and folders and is done for consistency between files and folders. Any entry within a folder is stored inside that folders sub-hash with a entry equal to its name. The "recursive" parameters governs if method recurses into sub-folders or not. Also, the md5-sum of a file might not be present if the md5sum parameters is set to false/undef/0. Errors performing md5-sum will also be saved in the md5-attribute on the sub-hash. It might also be undef, such as when no md5-summing has been requested.
Error-messages on the md5 attribute will have the form: "N/A: Some Error Message", such as when failing to open or sum the file in question.
Merge metadata with same keys from several entity sources
Accepts this input in the following order: db, entitytype, notemplate, noentity, entities.
The meaning of these input options are as follows:
db Reference to the AuroraDB-instance used by the REST-server.
entitytype The textual entitytype to fetch templates for the entities specified in the entities-option. Defaults to DATASET. This option will be ignored if the notemplate-option is true.
notemplate Disables the fetching of template data for the entities specified in the entities-option. Defaults to 0 (false). Valid values are 0 (false) and 1 (true - do not fetch template metadata). If false the method will fetch template metadata for the entities in the entities-option and merge that with metadata from the entity itself (if not the noentity-option is enabled).
noentity Disables the fetching of metadata for the entities specified in the entities-option. Defaults to 0 (false). Valid values are 0 (false) and 1 (true - do not fetch entity metadata). If false the method will fetch entity metadata for the entities in the entities-option and merge that with metadata from the template (if not the notemplate-option is enabled).
entities The entities that we want to merge metadata for. LIST of entity IDs from the AURORA database.
This method will merge metadata from the enabled sources (template and/or entity itself) and from all the entities in the entities-option into one HASH with key->value entries. In other words it merges metadata from both templates and entities into one hash as if the result is for one entity. The merging will take precedence in the order of the entities-option for keys with the same name, where first entity specified is antecedent to the next and so on and the last entity in the list takes precedence over all the previous.
Returns a HASH-reference with all the merged data in a key=>value structure.
Convert permission bitmask into its textual permission names
Accepts the following input in this order: db, bitmask. Db is the reference to the AuroraDB-instance used by the REST-server. Bitmask is the bitmask of permission that are to be converted to its textual counterpart.
Returns a LIST-reference of the textual permission names that have been set in the bitmask.
Recurse a listing from the listFolders()-method and produce a iterable array with textual entries.
Accepts these parameters in the following order: listing, newlist, level, path.
The meaning of these parameters are as follows:
listing HASH-reference to the listing produced by the listFolders()-method.
newlist Reference to the array list being produced by this method. All results of the recursion is added to this list.
level The level we are at for a specific run of this method. Should be started with the number 0.
path The preceeding path at any given moment of calling the recurseListing()-method. Is is used to know which folder/part of the listFolders structure one is in at any given moment. Should start with just a blank string ("") and the rest is handled internally by the recursing method.
Returns an array list reference in the newlist-option as explained above.