AuroraDB - Interface methods to the AURORA database.
my $dbfile="./aurora.db";
my $db=AuroraDB->new(data_source=>"DBI:SQLite:dbname=$dbfile",user=>"",pw=>"");
# create a entity of type GROUP
my $id=$db->createEntity($db->getEntityTypeIdByName("GROUP"));
# set some metadata
my %md;
$md{".DublinCore.Creator"}="Albert Einstein";
$md{".DublinCore.Created"}="20190101";
if (!$db->setEntityMetadata($id,\%md)) {
print "Failed to set entity $id's metadata: ".$db->error()."\n";
}
# get the metadata
my $m;
$m=$db->getEntityMetadata($id);
use Data::Dumper;
print "METADATA: ".Dumper($m);This module interfaces with the AURORA database. AURORA stands for Archive and Upload Research Objects for Retrieval and Alteration and was created at the Norwegian University of Science and Technology (NTNU) in Trondheim, Norway to facilite retrieval of data from science labs, storage of the datasets and the ability to flexibly add metadata on each dataset.
The AURORA database module was written to be general enough to be used with most SQL engines, while still trying to optimize functions where necessary.
The AURORA database module was written by Bård Tesaker and Jan Frode Jæger
Instantiates the AuroraDB-class: new(data_source=>P,pw=>Q,pwfile=>R,user=>S,cachetime=>T)
Required parameters are:
data_source Perl DBI data_source parameter for the database chosen. See DBI's documentation.
pw Password to login to database with.
pwfile Filename to read password from. PW must be undef or blank.
user Username to login to database with.
depth Sets the maximum depth allowed on the entity tree. Optional. SCALAR. Default if not given is set to the global constant VIEW_DEPTH. This value should be set with care since it reflects what is possible to recurse with the various mandatory database views, such as ANCESTORS. The value should therefore reflect actual conditions in the AURORA database itself. Either this or expect a visit to the twilight zone, where entities both exists and do not exist at the same time. Or, is that just quantum reality even though we deny that entities are sub-atomic particles.
entitytypescache How often to update the cache of entity types. Default is every 3600 seconds.
templatescache How often to update template structures. Default is every 3600 seconds.
templateflagscache How often to update the template flag types. Default is every 3600 seconds.
entitiescache How often to update existing entity(ies). Default is every 120 seconds.
The method returns the reference to the instantiated class.
Adds a member to an entity.
Accepts these inputs in the following order:
object The entity to add a member to. Required.
subjects The entity(ies) to add as a member(s). Required. It can be one or more entity IDs as a LIST.
The method returns 1 upon success, 0 upon failure. Please check the error()-method for more information upon failure.
Assigns template(s) to an entity.
Input is in the following order:
entity The entity id to assign the template(s) to.
type The entity type that the template(s) are to be valid for. If not defined or 0 it will default to DATASET.
template The template id(s) to assign to the given entity. The value expected here is a LIST of one or more ids. The order of the list defines the order in which the templates take effect. If template is set to undef it will remove any template assignment of the given type on the entity.
Previous assignment on the given entity and type are overwritten with the new assignment.
Return value is 1 upon success or 0 upon failure. Check the error()-method for more information on the error.
Checks a set of metadata key->value pairs compliance with an entity's aggregated template.
Input for this method are in the following order:
entity The entity id to check the compliance for.
metadata The metadata HASH-reference with key->value pairs to check against the entity's aggregated template.
type The template type to use when checking the compliance. If type is undef, it will default to the entity id's type (see entity-option).
path The path to use to aggregate a template. If none given it uses the path of the entity itself.
The return value is a HASH-reference. Undef is returned upon failure. Check the error()-method for more information upon failure.
The format of the return HASH is as follows:
( compliance => VALUE,
noncompliance => LIST,
metadata => { KEYx => { value => SCALAR,
compliance => BOOLEAN,
default => SCALAR,
regex => SCALAR,
flags => BITMASK,
min => SCALAR,
max => SCALAR,
comment => SCALAR,
},
KEYy => { ... },
},
)The top compliance value gives the overall compliance of all the metadata in a boolean (1=success,0=failure). The noncompliance value is a LIST of keys that failed compliance (if any). The metadata sub-hash gives all the keys that the input metadata had and if they are compliant or not, their template and so on. It will also contain any missing keys and their value taken from the aggregated template of the entity when those keys are missing and the MANDATORY-flag has been set.
See also the getTemplate and setTemplate methods for documentation upon the format of the templates.
Clear bits in a bitmask.
Input is the bitmask to modify and bitmask with bits to clear. Default parameters is ''.
Return value is the resulting bitmask as a SCALAR. The input bitmask is unaltered.
Clear bits in a bitmask.
Input is the bitmask to modify and a list of bit numbers to clear. Default bitmask is ''.
Return value is the resulting bitmask as a SCALAR. The input bitmask is unaltered.
This method attempts to check if the we are connected to the database or not by quering the DBI-instance: connected()
Returns 1 upon being connected and 0 upon not being connected.
Creates a bitmask based upon the bit number specified in the input list - iterates on the vec-method in Perl.
Input is the bit numbers to set as a LIST.
Return value is the bitmask as a SCALAR.
Creates an entity of a given type in the database: createEntity([type],[parent])
Input are in the following order:
type Entity type id to create. Optional and it defaults to "DATASET".
parent Parent entity id for the newly created entity. Optional and will default to 1 if none specified.
Return value is the created entity's id or undef upon failure. Please call the error-method for more information on the failure.
Creates a metadata key in the database.
Input is the name of the metadata key to create (assign a metadata key id).
Return value is the metadata key id created or if it already exists its existing key id. Undef is returned upon failure. Please call the error-method to get more information about the error.
Creates a permission bitmask based upon a mix of names and bit position values.
Input is a LIST fo permission name(s) and/or bit position value(s).
Returns a bitmask of those name(s) and/or value(s). Undef is returned upon failure. Please check the error()-method in such cases.
Creates a template in the database and sets the given constraints.
Input for the method are these options in the following order:
parent The entity id of the parent which the template is to be created under.
constraints The template constraints that are to be set for the template. This is a reference to a HASH. See the setTemplate()-method for more information.
The method creates the template and sets the template constraints on the template.
Return value is the new template id upon success or 0 upon failure. Check the error-message by calling the error()-method.
Deconstruct a given bitmask into the bit numbers that have been set.
Input is the bitmask to deconstruct.
Return value is a LIST of bit numbers that have been set.
Deletes an entity of the given entity id from the database: deleteEntity(id)
Input is entity id to delete or it will default to the invalid entity id of zero.
It will delete all references to this entity in the database, including permission memberships, template assignments, log entries and metadata. A deletion will only succeed if the entity does not have any children entity(ies). Children must first be moved or deleted.
Return value is 1 upon success, 0 upon failure. Call the error-method to get more information on the failure.
Deletes metadata from an entity moderated by a set of metadata keys.
Input is in the following order:
entity Id of the entity to delete metadata from.
keys The metadata keys to remove as a LIST-reference. If no metadata keys are specified it will remove all of the entitys metadata. The metadata keys accept wildcards (*) in them.
Return value is 1 upon success, 0 when there are no rows to delete and undef upon failure. Please call the error-method to inquire about the details of the error in question.
Deletes a template and its constraints and assignments to it.
Input is the template id.
Return value is 1 upon success, 0 upon failure. Check the error()-method for more information upon a failure.
This method prepares and executes a SQL statement and then checks the result: doSQL(SQL-Statement)
Input is the SQL statement to execute as a SCALAR. Return values are the DBI-class's statement handle upon success, undef upon failure. Please check the error-method to find out more about the issue.
This method is called from most methods in the AuroraDB-class and handles every relevant side of executing SQL-statements and handling errors. It also connects to the database if not already connected.
Returns all entities of a certain type.
Input is entity type(s) as a LIST-reference. The entity type(s) are optional and if none is specified all entities will be returned.
Return value is a reference to a LIST entity id(s), if any.
It will return a reference to a LIST of entity id(s) upon success (it migth be an empty list), undef upon failure. Upon failure, call the error-method for more information on the failure.
Enumerates the entity type ids of the AURORA database: enumEntityTypes(). Returns a LIST of entity type IDs.
No input is required. It returns the list upon success, undef upon failure. Please check the error-method for more information on the failure.
Enumerates the loglevels in the database.
Input is none. It returns the loglevel ids on success as a LIST-reference, undef upon failure. Call the error()-method to check information on the error.
Enumerates the permission type names that exists in the AURORA database.
It accepts no input.
Return value is a LIST of permission type names.
Enumerates the template flags that exists in the database.
Returns a sorted LIST of template flag values.
Gets the last error message from the AuroraDB library and its methods. Its functionality is used and referred to by all methods.
No input required and the return value is the last error message that has happened or ""/blank if no error message found.
Checks to see if an entity exists or not? existsEntity(id).
Input is entity id to check or it will default to the invalid entity id of zero.
Return value is the entity id upon success, id zero if not existing, undef upon failure. Please call the error-method for more information.
This method attempt to return the DBI-object that AuroraDB creates: getDBI(). If it is not already created it attempts to connect to the database and then return the instance.
The method requires no input.
Return value is the instance of the DBI-class. Returns undef upon error. Check the error-method to get more information on the issue.
It is called from the most relevant method, such as doSQL.
Attempts to disconnect from database if already connected.
This method requires no input.
Returns 1 upon success, 0 upon some failure and undef if database is not connected already. Please check the error()-method for more information upon failures.
Retrieves the entity(ies) id that matches the criteria given. There must exist one or more metadata on the entity(ies) searched for in order for this method to succeed.
The method takes the following parameters in the following order:
metadata This options gives the metadata key->value pairs to search for state in a SQLStruct format (see SQLStruct-module for more information). This option can be set to undef (get all metadata). When given it has to be a HASH-reference.
offset This option gives the offset in a search result set to get. It optimizes search windows (where you want to only display a certain number of matches at a time) by using a SQL LIMIT-clause. Lowest value is 1. Can be undef (no LIMIT-clause used - all matches returned).
count This option gives the number of entity(ies)/rows to fetch in the search result. SCALAR. Optional. Defaults to 2^64-1 if not specified. It is part of the optimization using a SQL LIMIT-clause (see the offset option).
orderby This option specifies which metadata key to order the search matches after. It also optimizes searches by using the SQL ORDER BY clause. This option is mandatory as it is required for the method to work. The metadata key to order by must exist in all entity(ies) that are to be returned in the result. The orderby-option in conjunction with the offset- and count-options will give a ordered, SQL optimized search of entities based on metadata. The validity/existence of the orderby option is not checked. If set to undef it will default to "system.dataset.time.created", which is only valid for datasets (this default referring to a higher level is the only one coded into the AuroraDB-library).
order Sets the ordering part of the orderby-option. It refers to the SQL ordering keywords of ASC and DESC. Will default to "ASC" if invalid order-option specified or undef.
entities Sets the entities to constrain the search result with. Type expected is a reference to a LIST of entity ids. It is optional and will constrain the search result, independant of metadata structure, to the entities in the given LIST.
types Sets the entity types to return in the search result. Type expected is a reference to a LIST of type(s). It is optional and will constrain the search result only to entity(ies) of the given type(s). It can be undef and then no entity type constraints will be imposed.
tableopt Select between including parent metadata or not. SCALAR. Optional. Defaults to 0. Value can be either 0 (false) or 1 (true).
debug Sets if the method returns the actual SQL query being used or not. SCALAR. Optional. If not set it will default to false and no sql query will be returned. The settings is boolean, where something that evaluates to false or true, become that setting. When this option is set the method will return the debug string as the second reference after the result array:
$(myresult,$debug)=$db->getEntityMetadataByKeyAndType(.....,1)subject Entity ID that the perm-parameter is to be valid for. SCALAR. Optional. Defaults to undef. If subject is specified the method will attempt to get entities that also match whatever value is in the perm-parameter.
perm Permission mask that entities must match to be included. SCALAR. Optional.
lop Logical operator for the permission mask in the perm-parameter. SCALAR. Optional. Defaults to "ANY". Valid values are "ANY" (logical OR) or "ALL" (logical AND).
sorttype Sets if the orderby-option is to be sorted alphanumerical or numerical. 0 means alphanumerical case-insensitive (default), 1 means numerical and 2 means alphanumerical case-sensitive. Please note that the sorting is case-insensitive.
The return value is a reference to a LIST of entity id(s) upon success in the order stated by the orderby- and order-options, or undef upon failure. Call the error-method to know more about the failure.
When using the offset- and count-options to create search windows it will also set the total number of entity(ies) found independant of the search window. This count can be retrieved by calling the getLimitTotal()-method after a successful call to this method with the offset-options.
Gets entity(ies) based upon a permission mask and entity type(s).
The method takes these options in the following order:
subject This option specifies for which entity the permission mask is to be valid for? Typically it will be eg. a USER-entity id. This option is mandatory.
perm This option specifies the permission mask to use in the search. See createBitmask()-method for more information. Option can be undef for no bits set.
permtype This options specifies the search moderator type to use for the permission mask. It sets if the subject in question needs to have ALL the bits in the mask (logical AND) or ANY of the bits (logical OR). Valid setting is therefore either ALL or ANY. Will default to ALL if set to undef or an invalid value.
types This option specifies the entity types to moderate for in the search. The option is optional and if not set will search for the permission mask in all entity(ies). Type expected for option is a reference to a LIST.
entities Only include entities in this list if they match the other criteria. LIST-reference. Optional. Defaults to undef.
Return value from method is a reference to a HASH in the format: entity => PERM. The PERM gives the complete perm for the given entity for the stated subject.
Gets an entity's children.
Input is in the following order: entity id, entity type(s), recursive. The entity id is the entity parent to get the children of. The entity type(s) are the type(s) to get in the result (LIST-reference). It is optional and if not set will return entities of all types. The "recursive" sets if one is to fetch all children recursively for given parent and not only its immediate children.
It returns the parents children entity ids upon success as a LIST-reference, undef upon some failure. Please check the error()-method for more information upon failure.
Gets an entitys perm on a given entity's children: getEntityChildrenPerm
This method takes these options in the following order:
subject The ID of the entity that the permission mask is valid for.
object The entity to get the childrens permissions of.
recursive (optional) Specifies if one wants to recurse further down in the entity structure or not? It is optional and default to false. Set it to true for recursion.
types (optional) Sets the entity type IDs to include in the result. ARRAY-reference.
The method returns a reference to a HASH-structure in the following format:
( ID => PERM,
ID => PERM,
)where ID is the entity ID of ones of the object's children (see object-option). PERM is the permission mask on that child, relative to the subject (see subject-option).
Upon failure the method returns undef. Please check the error()-method for more information upon a failure.
Get all members of given entity.
Accepts one input and that is the entity id of the entity to list the members of.
Returns a LIST-reference of entity ids that are members of the given entity:
(entity id,entity id, entity id)The LIST can be empty. The LIST-reference is undef upon failure. Please check the error()-method for more information.
Gets an entity's metadata moderated by a set of metadata keys.
Required input is in the following order:
entity The id of the entity to get metadata of.
options A HASH-reference of options to the method. HASH-reference. Optional. Can be used to specified options to the method. As of today only "parent" is supported (boolean). If parent is 1 (true) the metadata is fetched from METADATA_COMBINED instead of METADATA in the database. If parent is 0 or anything else metadata is fetched from METADATA.
keys A LIST of metadata keys to be returned (instead of all). If no metadata LIST is specified it will default to undef (return all key->values of the entity). The metadata keys can contain wildcards (*).
Return value is the metadata HASH-referemce with key->values (it can be empty logically enough). Upon failure undef is returned. Please call the error-method to find out more about the error.
Returns a HASH-reference of entities metadata value for a given metadata-key.
Input is in the following order: metadata-keyname, entities. The metadata-keyname is the key-name for the key to get values for. The entities parameter is the entities to return that metadata-value for (LIST-ref). The entities-parameter is optional. If not given it will match against all entities in the database. And the last parameter accepted is "parent" that decides if the metadata is fetched from METADATA_COMBINED or just from METADATA. If parent is 1 (true) the metadata is fetched from METADATA_COMBINED instead of METADATA in the database. If parent is 0 or anything else metadata is fetched from METADATA.
Returns a HASH-reference upon success, undef upon failure. Please check the error()-method for more information upon failure.
The structure of the HASH returned is as follows:
(
entid => VALUE (SCALAR or LIST)
entid => VALUE (SCALAR or LIST)
.
.
entid => VALUE (SCALAR or LIST)
) The VALUE will either be a SCALAR or a LIST, depending upon if the metadata key in question has multiple values or not (ARRAY or not).
Returns a HASH-reference of entities metadata value for a given metadata-keys (or all keys).
Input is in the following order: metadata-keyname(s), entities, parent. The metadata-keyname is the key-name(s) for the key(s) to get values for as a LIST-reference. It can be undefined or empty upon which all metadata keys will be fetched. The entities parameter is the entities to return that metadata-value for (LIST-ref). The entities-parameter is optional. If not given it will match against all entities in the database. And the last parameter accepted is "parent" that decides if the metadata is fetched from METADATA_COMBINED or just from METADATA. If parent is 1 (true) the metadata is fetched from METADATA_COMBINED instead of METADATA in the database. If parent is 0 or anything else metadata is fetched from METADATA.
Returns a HASH-reference upon success, undef upon failure. Please check the error()-method for more information upon failure.
The structure of the HASH returned is as follows:
(
entid => {
KEYNAMEa => VALUE (SCALAR or LIST)
.
.
KEYNAMEz => VALUE (SCALAR OR LIST)
}
entid => {
KEYNAMEa => VALUE (SCALAR or LIST)
.
.
KEYNAMEz => VALUE (SCALAR or LIST)
) The VALUE will either be a SCALAR or a LIST, depending upon if the metadata key in question has multiple values or not (ARRAY or not). The metadata keys are given its full textual name which then points to the VALUE. Not all entities need to have all KEYNAME values present and depends upon what is available in the database for that given entity ID.
Gets an entity's parent.
Input is the entity id to get the parent of.
It returns the parent entity id upon success, 0 upon some failure. Please check the error()-method for more information upon failure.
Gets entity(ies)'s parent and their parents (ancestors): getEntityPath(id1,id2,id3..idN).
Input is the entity id(s) that one wants to get the parent and ancestors of.
Return value is dependant upon the number of IDs asked for. In all cases the return value for a given entity is a LIST of ancestral entities in descending order (including the entity itself).
If the caller asked for just one ID, the return structure is a LIST as follows (backwards-compatible):
(ANCESTOR1,ANCESTOR2,ANCESTOR3..ID)If the caller asked for more than just one ID, the return structure is a HASH-reference as follows:
(
ID1 => [ANCESTOR1,ANCESTOR2..ID1],
ID2 => [ANCESTOR1,ANCESTOR2,ANCESTOR3..ID2],
.
.
IDn => [ANCESTOR1..IDn],
)If some error occured the return value is undef. Check error()-method to get more information on a potential error.
Gets an entitys permissions on a given object/entity: getEntityPerm(subject,object).
Input is in the following order:
subject The id of the entity which you want to know which permission it has on the object.
object The id of the entity to get permission on.
Returns a bitmask that is an aggregate of permissions from the entity tree. The DENY mask is added before the GRANT. Returns undef upon failure. Please call the error-method for more details upon errors.
Gets the permissions on a specific entity (no ancestors):
Input are in the follwing order:
subject The entity id of the subject that the permissions are valid for.
object the id of the entity that the permissions are fetched from.
The return value is a LIST of grant and deny permission masks, in that order.
Returns undef upon failure. Call the error-method to find more details on the error in question.
Retrieves the entities that match the criteria of metadata and type and the permission on them for a given entity (subject). This method is a wrapper around the getEntityPerm()- and getEntityByMetadataKeyAndType()-methods.
The method takes these options in the following order:
subject The entity id of the entity that the PERM mask is valid for. See the getEntityPerm()-method.
metadata Metadata to moderate the search on. See explanation in the getEntityByMetadataKeyAndType()-method.
offset Offset of a search window to use. See explanation in the getEntityByMetadataKeyAndType()-method.
count Number of search entries to retrieve in a search window. See explanation in the getEntityByMetadataKeyAndType()-method.
orderby Which metadata key to order the search result by. See explanation in the getEntityByMetadataKeyAndType()-method.
order In what order to return the result in. See explanation in the getEntityByMetadataKeyAndType()-method.
types Entity types to moderate the search on. See explanation in the getEntityByMetadataKeyAndType()-method.
tableopt Select between including parent metadata or not. SCALAR. Optional. Defaults to 0. Value can be either 0 (false) or 1 (true).
sorttype See the sorttype option of the getEntityByMetadataKeyAndType()-method.
Return value is a reference to a HASH of permissions for entity(ies). Upon failure undef is returned. Check the error()-method for more information on error.
The format of the returned HASH is:
( POS => { entity => ID,
perm => PERM,
}
)where POS is the numbered position in the search result, ID the entity ID and PERM the permission mask on that entity ID.
Retrieves entity(ies) by a permission mask and moderated for by a metadata key->value structure and entity type(s). It is a wrapper around getEntityByPermAndType()- and getEntityByMetadataKeyAndType()-methods.
The method takes these options in the following order:
subject Entity id that the permission mask is valid for. See explanation in the getEntityByPermAndType()-method.
perm Permission mask. See explanation in the getEntityByPermAndType()-method.
permtype Logical match type to use for the permission mask. See explanation in the getEntityByPermAndType()-method.
metadata Metadata to moderate the search on. See explanation in the getEntityByMetadataKeyAndType()-method.
offset Offset of a search window to use. See explanation in the getEntityByMetadataKeyAndType()-method.
count Number of search entries to retrieve in a search window. See explanation in the getEntityByMetadataKeyAndType()-method.
orderby Which metadata key to order the search result by. See explanation in the getEntityByMetadataKeyAndType()-method.
order In what order to return the result in. See explanation in the getEntityByMetadataKeyAndType()-method.
types Entity types to moderate the search on. See explanation in the getEntityByPermAndType()-method.
tableopt Select between including parent metadata or not. SCALAR. Optional. Defaults to 0. Value can be either 0 (false) or 1 (true).
sorttype Sets how the search is performed. See the "sorttype" option in the getEntityByMetadatakeyAndType()-method.
Returns a reference to a HASH-structure upon success, undef upon failure. Check the error()-method for more information on a potential error.
The format of the returned HASH-structure is:
( POS =>
{ entity => ID,
perm => PERM,
},
)Where POS is the numbered position in the returned and ordered result (always starting from 1, even with search windows). ID is the entity ID in position POS and PERM is the permission mask in the same position.
This method checks if an entity has all the permission of the given bitmask on a specific object.
The method have these options in the following order:
subject Entity id of the entity which the mask is valid for.
object Entity id of the entity which you want to check if the subject entity have the required permissions on.
mask The bitmask to check if the subject entity has on the object entity.
The method returns 1 if the subject entity has the required permissions, 0 if not. Undef is returned upon failure. Please check the error()-method in such a case.
Gets the permissions on a object:
Input are in the following order:
object The entity id of the object.
perm mask An optional mask of permission bits we are looking for.
object type An optional subject type to filter for.
The return value is a HASH of object => permission of objects thet match the criteras.
Returns undef upon failure. Call the error-method to find more details on the error in question.
Gets the permissions held by a subject:
Input are in the follwing order:
subject The entity id of the subject.
perm mask An optional mask of permission bits we are looking for.
object type An optional object type to filter for.
The return value is a HASH of object => permission of objects thet match the criteras.
Returns undef upon failure. Call the error-method to find more details on the error in question.
Gets the permissions on an object:
Input are in the follwing order:
object the id of the entity that the permissions are fetched from.
The return value is a HASHREF of subjects with permissions on an object. Take into account the objects inheritance, but not implisit or explisit subject membership. Hash key is subject id, value is a hash with mask for inherit, deny, grant and perm ( grant | inherit & (~inherit ^ deny))
Returns undef upon failure. Call the error-method to find more details on the error in question.
Get a list of roles for an entity: getEntityRoles(id).
Roles are the entity itself,its ancestors and any entity tied directly or indirectly to any of them through the databases MEMBER-table.
Returns an unsorted list without duplicates. Undef upon error. Check the error()-method to get more information upon failure.
Get an aggregated template for an entity.
Input is in the following order:
type The entity type to get a template for. SCALAR. Optional. If not specified will attempt to default to DATASET-type.
entities The entity(ies) to get template for. ARRAYM of SCALAR. Required. The options expects a LIST of one or more entity(ies). If just one entity is specified it will attempt to return the template that is valid on just that entity itself (if any). If multiple entities are specified it assumes that it is a tree list to aggregate template constraints from going from element 0 to element N (inheritance).
The return value is a HASH-reference to a set of template constraints. If any of the constraints on a given metadatakey has not been set, it will revert to defaults. The defaults are as follows:
default undef (no default(s) set/default(s) do not exist)
regex .*
flags undef (no bit set)
min 0
max 1
comment Blank string.
Inheritance on templates works by going from the first entity specified in the entities-parameter LIST-ref to this method and down to the last entity in that list (often the entity you need to know the aggregated template of).
Only whole key-constraints will supplant another one while recursing the tree defined in the entities-parameter. This means that parts of the key, like say max or min, will not replace just max and min. All the constraints for the key in question will be replaced upon finding a replacement key constraint definition, even undef.
Similarly, the default-constraint will not accumulate defaults as in traverses down the entity tree, but replace any defaults earlier in the tree with the new defaults defined for that key in the template being processed.
Let us assume we have the entities GROUP, USER, DATASET in addition to the special TEMPLATE-entity type.
All entities in AuroraDB can have any number of templates assigned to them (up to the limits of the database), but all assignments are type- specific. This means that the templates assigned on an entity belong in an entity type group. Eg. one can assign any number of templates having effect for DATASET-entities on a GROUP-entity. The templates themselves are type- neutral and only gain templating effect once they are assigned on an entity (see the assignEntityTemplate()-method) and a entity type for that entity.
All entities can have template assignments for entity types that are not the same as itself, since this is about aggregated templates and inheritance. When calling the getEntityTemplate()-method is called it will require the entity type to be specified in order to figure out the aggregated template.
At the end of the aggregation process, any missing or undefined constraints for a specific key will be defaulted to standard values (see above).
Upon success this method will return a HASH-reference to a aggregated entity template, undef will be returned upon any error. Please call the error()-method for more information upon failure.
See the setTemplate()-method for more information on the format of the returned, aggregated template. Please note, however, that the getEntityTemplate()-method will add two fields to the template of each "key" that are called "template" and "assignedto". The "template" fields tell which template affected the last change on the definition and "assignedto" says on which entity that this template was assigned. This information enables the user to know if the aggregated template result for a given "key" is defined on the entity that one asked for the aggregated template of, or if it was inherited from above (the assignedto id is not the same as the entity asked for). It also says which template effected that result.
Gets template assignment(s) on an entity
Input is in the following order:
entity The entity id to get the assignments of. SCALAR. Required.
type The entity type to get assignments of. SCALAR. Optional. If not specified the method will return all assignments of all types on the entity in question.
This method gets template assignment(s) on an entity and optionally just of a given type. All templates are assigned to entities based upon what type the template is to have effect for. By giving a set type, only the assignment(s) for that type on the entity in question are returned. If no type is specified this method will return all template assignments set on the entity.
Upon success returns a HASH-reference of the assignments, undef upon failure. Please check the error()-method for more information upon failure.
The return structure upon success is as follows:
(
TYPEa => [TEMPLATEID1,TEMPLATEID2 .. TEMPLATEIDn]
.
.
TYPEz => [TEMPLATEID4,TEMPLATEID5 .. TEMPLATEIDn]
)where TYPEa and so on are the entity type id of the type assignment. TEMPLATEID1 and so on is the entity id of the template that are assigned on the given type. This is an ARRAY-reference of template entity ids and the array returns the assignments in the order that they are set, starting from element 0 and up.
If no assignments have been set on the entity in question (or of the chosen type), the HASH-structure will be empty.
Retrieve template assignments on a given entity(ies). This is actual template id's and not an aggregated template.
Input is entity type to fetch template for and entity id they belong to accordingly. Entity id is expected to be a LIST of one or more elements. We recommend not using more than one elements, since it will be impossible to know which template id belongs to which entity?
Return value is a LIST reference upon success, undef upon failure. Check the error()-method for more information upon failure.
The LIST returned contains template id's that belongs to the given entity. The list is ordered according to when the templates take effect.
Retrieves the path for an entity's templates. As of writing a wrapper around getEntityPath.
See getEntityPath()-method for more information.
Gets the entity tree from given entity id.
Input is in the following order:
entity Entity id to start from. 1 can be used to signify the top, ROOT entity. Defaults to 1 if none specified.
include LIST-reference of entity types to consider. Default to undef which will include all of the tree.
exclude LIST-reference of entity types to exclude from result. Default to no exluded.
depth The maximum depth from the depth of the start entity to return in the result. SCALAR. Optional. If not specified it will return all entity children of start entity independant of depth. Depth 0 is the same as all entites on the same level as the start entity, 1 is all on the level below it and so on.
Returns a HASH-reference of the entities in the tree and their children with attributes.
The return HASH-structure is as follows:
(
IDa => {
id => IDa,
type => INT,
children => [ IDb...IDn ],
}
IDb => {
id => IDb,
parent => IDa,
type => INT,
children => [],
}
)IDx is the INT entity id. The subhash specified the ID of that entity again in the key id. It also gives the entity's type and parent, except for the root entity 1 (IDa in example above), which has no parent (or technically itself). It also contains a LIST of children with IDs of its immediate children (that has it has its parent). The returned HASH is therefore flat and all entities in the tree can be addressed at its root level.
Returns undef upon failure. Check error()-method for more information on the failure.
Retrives the entity type of an entity id: getEntityType(entityid)
Input is entity id or it will default to the invalid id of zero.
Return value is the entity type of id referenced upon success, or 0 upon failure. Please call the error-method for more details.
Retrieves the entity type id based upon the textual name input to the method: getEntiyTypeIdByName([name1,name2..nameN]);
No input is required and then all entity type ids are returned. If one or more names are specified (comma separated), it will return the entity type ids as a LIST for the names it recognizes or undef for unknown ones.
Return value is a LIST.
Retrives the textual name of the entity type: getEntityTypeName (entityid)
Input is the entity id or it will default to the invalid id of zero.
Return value is the entity ids type name upon success, undef upon failure.
Please call the error-method for more details of the error.
Retrieves the entity type name by specifying the entity type id(s): getEntityTypeNameById([id1,i2..idN]).
No input is required and it will then return all entity type textual names. If one or more type id(s) are specified (comma separated), it will return the entity type name(s) for the entity type id(s) specified.
Return value is a LIST.
Gets the log entries of entity or if none given all log entries in the database.
Input is the entity id to get the logs for. If none given it will fetch log entries for all entites.
Return value is a HASH pointer of the resulting log entries. The format of the HASH is:
( NO => { time => TIME,
loglevel => LEVEL,
message => SCALAR,
idx => SCALAR,
tag => SCALAR
}
)the NO is the auto increment value of the database. time is given in hires time, loglevel is the level value from possible loglevels (see enumLoglevels()-method), message is the message of the log entry and idx is the log entries auto increment index in the database.
It will return undef upon failure. Please check the error()-method for more information in the case of an error.
Gets the loglevel id by giving its name.
Input is the loglevel name. Defaults to "" and will result in a "0" return value (does not exist).
Returns the id upon success, 0 if it does not exist, undef upon failure. Please check the error()-method for information on a potential error.
Gets the loglevel name by giving its value. Input is the loglevel value. If none given it defaults to 0 which will result in a "" return value (does not exist).
Return value is the loglevel name upon success, "" or blank if it does not exist, undef upon failure. Check the error-method for more information on an error.
Get the metadata key id by specifying the metadata key name.
Input is the metadata key name.
Return value is the metadata key id upon success, 0 if it does not exist, undef upon failure. Please call the error-method to find out more about the error.
This methods read modification time for tables and return the newest one.
Optional parameter: table names - tables to get mtime for, default all tables with set mtime.
Return value: the newest mtime found.
Time format is floating unis time.
Returns the permission type name(s) for the given permission type value(s).
Input is a LIST of permission type value(s).
Return value is a LIST of permission type name(s) for those value(s).
Returns the permission type value(s) for the given permission type name(s).
Input is a LIST of permission type name(s).
Return value is a LIST of permission type value(s) for those name(s).
Get a template and its constraints.
Input is the template id to get the constraints for.
Return value is HASH-reference with the constraints upon success (see setTemplate for more information on structure), or undef upon failure. Check the error()-method for more information upon failure. Undef-values in the keys are to be understood as there are no more values for that "value".
Retrieves all entities that the given template has been assigned to as well as type.
Input parameters are in the following order: template id (SCALAR, required), type (SCALAR, optional), duplicates (SCALAR, optional)
Template ID is the template that one wishes to get all assignments of. Type is the type id that one wishes to get assignments of (other type assignments of given template id are omitted). Duplicates sets if any duplicates of entities on the same entity type assignment will be removed or not? It is possible to assign the same template several times on the same entity and entitytype and this parameter controls if this will be visible in the returned result or not? It is evaluated as a boolean and if true will remove duplicates and if false will not remove duplicates. If parameter is undef it will default to true and duplicates will be removed.
Returns a HASH-reference upon success, undef upon failure. Please check the error()-method for more information upon failure.
The HASH structure is as follows:
(
all => [entity1,entity2,entity3 .. entityN]
types => {
typeA => [entity1 .. entityN]
typeB => [entity2, entity3 .. entityN]
.
.
typeZ
}
)Please note that the "all" key contains all the entities that have the given template assigned to them, without duplicates (no matter what the duplicates-parameter says). The "types" key contains the entity assignments ordered into entity types, so that one can easily check eg. what "DATASET" assignments have been put in place with the given template.
Gets a tree of template assignments and their metadata key definitions.
This method accepts the following parameters in this order:
entities Entity og entities ID(s) to get template assignments of. ARRAY-reference. Required. It can be one or more elements. If just one element is specified it will get the entity tree path down to that entity and generate a tree of assignments based on that. If more than one element is specified it will use that as the entity tree and generate assignments based on that.
type Entity type ID to get template assignments to. SCALAR. Optional. Will default to "DATASET". This decides which entity type to get template for, since all template assignments are assigned as a type and have effect on a given entity type in the tree.
include Moderates which template IDs to include in the result. ARRAY-reference. Optional. If not specified will include all template assignments found. If specified it will only include those template IDs that are specified in the ARRAY-reference. This makes it possible to analyze how just some template IDs have effect down the entity tree.
prune Decides if an empty entity in the generated tree should be included or not if it has no template assignments. SCALAR. Optional. If not specified will not prune away entities with no template assignments. The value is interpreted as a boolean and must be either true or false.
This method returns a tree of template assignments on the entity(ies) specified according to the use of the "entities"-parameter. It will also return the metadata key-definitions of all the template assignments.
Upon success this method returns a HASH-reference, undef upon failure. Please check the error()-method for more information upon failure.
The HASH-structure returned upon success looks like this:
(
1 => entity => SCALAR,
assigns => {
1 => {
TMPLIDa => {
KEYNAMEa => {
default => ...
regex => ...
flags => ...
min => ...
max => ...
comment => ...
}
.
.
KEYNAMEz
}
.
.
TMPLIDz
}
.
.
N
}
.
.
N
)The assignmenst are ordered from 1 to N in order to know which order to iterate on it. Inside each initial order number is two fields: "entity" and "assigns". "entity" defines which entity these assignments are valid for, if any? "assigns" gives the template assignments for that entity given any constraints set in the method-parameters (see above). The "assigns" sub-structure is also numbered from 1 to N and gives the order in which the template(s) are valid. After the number comes the template ID (TMPLIDa .. TMPLIDz) from the database. Each ordered assignment will only have one template ID here and is only there to inform what the template ID is for that assignment. After the template ID comes the textual metadata key-name (KEYNAMEa .. KEYNAMEz) and after that comes the actual definition of the key name (see the setTemplate()-method for more information).
If one uses the include-parameter the numbering in the assigns sub-structure will reflect which template that are included and are not a numbering reflecting the actual assignment order on that entity if the output then have been moderated.
This method optimizes the use of the getTemplate()-method to get the definition of the template by caching the response and eliminates the need to call it many times for the same template id. The method will be further optimized if one uses the include-parameter to narrow down which template ids that are to be included in the response.
Returns the template flag value(s) for the given name(s)
Input is a LIST of flag value name(s) to get flag value for.
Return value is a LIST of flag values of those names or undef for non-existing ones.
Returns the template flag value name(s) for the given flag value(s).
Input is a LIST of flag value(s) to get name(s) for.
Return value is a LIST of flag value name(s) for those flag value(s) or undef for non-existing ones.
Returns the individual flags set.
Input is the flag(s) bitmask to deconstruct.
Return value is a LIST of flag value name(s) for the flags set in the input bitmask.
Returns the bitmask of the flags that was input.
Input is the flag(s) to set in the bitmask.
Return value is a bitmask with the valid flags set.
Returns the maximum depth allowed on the entity tree.
No input is accepted.
Returns the maximum depth allowed on the tree as set through the constructor new() or the default from the global constant $VIEW_DEPTH. The value set through the constructor new() takes precedence if valid.
This methods moves an entity provided the new parent or to-entity exists.
Input are in the following order:
entity The entity to move.
parent The parent to move the entity to.
Returns 1 upon success, 0 upon failure. Call the error-method to get more information on the failure.
Removes member(s) from an entity.
The method accepts these parameters in the following order:
object The id of the entity to remove member(s) from. Required.
subjects The id of the entity(ies) to remove as member(s). Optional. If not set (not undef) all members of the object-entity will be removed. It can be one or more entity ids as a LIST.
Returns 1 upon success, 0 upon failure. Please check the error()-method for more information upon failure.
Remove all of an entity's permissions and roles in the AURORA database. Optionally all permissions other entity(ies) has/have on that entity.
This method accepts the following parameters in this order: id,others. ID is the entity ID of the entity to remove all permissions and roles of, SCALAR, Required. Others is the flag to tell the method to also remove all permissions and memberships that other entity(ies) might have on the given entity, BOOLEAN, optional. If not given will default to 0/false and do not remove permissions and roles others have on the given entity.
Returns 1 upon success, 0 upon not being able to remove it, undef upon some failure. Please check the error()-method for more information upon failure.
(Re)sequence an entity and any descendants. Done on createEntity and moveEntity to ensure parents is sequenced before child.
Input is entity. Returns count of sequenced entitys on success, 0 on failure.
Sets bits in a bitmask.
Input is the bitmask to modify and bitmask with bits to set. Default parameters is ''.
Return value is the resulting bitmask as a SCALAR. The input bitmask is unaltered.
Sets bits in a bitmask.
Input is the bitmask to modify and a list of bit numbers to set. Default bitmask is ''.
Return value is the resulting bitmask as a SCALAR. The input bitmask is unaltered.
Sets an entitys metadata. Old metadata keys are overwritten with new value or new keys are added. The values allowed to be set are moderated by the templates for this entity.
The method accepts these options in the following order:
entity The entity id of the entity to set the metadata on.
metadata The metadata HASH-reference of key->values to set on the entity. Can be undef.
type Template type to check the metadata entered against. If set to undef it will default to the entity id's type itself (see entity option).
path Entity-path to use for the aggregated template that the metadata is checked against as a LIST-reference. If set to undef it will use the path of the entity id itself (see entity option).
override Override template checking for metadata being set. Optional, default to false. If statement here evaluates to true it will ignore any template definitions that are valid for the metadata being set. This setting is to allow for critical system-updates and should be used with care. Should normally be false.
The method checks the metadata compliance against relevant aggregated template and if it fails returns the metadata keys it failed on in the error message (call the error()-method to read it). Please note that if the entity in question already have metadata on it, the existing metadata will be collected and used for the keys that are not in the input to the method. The input keys and values together with the keys that are not in the input will be checked against the aggregated template for compliance. This ensures that one can update just one key in the metadata without getting template compliance issues, since existing metadata will fill missing key-values.
This way of handling setting metadata on an entity means that the update follow the rule of the three musketeers: all for one and one for all. An update of a key or an addition of key value(s) will need to check all of the metadata for template compliance.
Please also be aware, that if you want to delete a metadata key while updating other keys, you can set that key to an empty LIST reference. Eg:
$hash->{KEYNAME}=\@listThe reason for this is that the method handles all value setting as lists (as does the database) and tries to optimize for using UPDATE/REPLACE-statements in SQL, so after setting values for a key, it removes any extra LIST values that are not needed anymore. If you set zero LIST values, it removes all LIST values afterwards since they are not needed anymore. Ergo thereby in effect performing a deletion of a key.
It return 1 upon success, 0 upon failure. Please call the error()-method to get more information on the error.
This function is simplified to work with basic and standardized SQL like UPDATE, INSERT and DELETE (no REPLACE or INSERT...on DUPLICATE UPDATE) for compability reasons. It is also optimized to favour UPDATE of values where possible (were there are existing metadatakeys), even for arrays. When no existing key or index of that key (in case of arrays) exists, it will insert new values. If the new array contains less values than the previous it will delete away surplus rows in the database. In addition it will skip running an UPDATE on values that are the same as before for a given key. This optimizes the function to work on most database engines, while also optimizing its speed and functionality. The working of the function is based upon some assumptions:
Most databases handles "REPLACE" or "INSERT on some conflict UPDATE" (and its variants) as a delete followed by an insert. This is sub-optimal if one can in many cases just execute a UPDATE statement.
Most metadata hashes given to the method contains key->value pairs that are already stored in the database. Ergo no need to either update or insert, but to skip.
We would rather want to update a row with a new value, than delete and then insert it of speed reasons.
It is faster to first read all metadata key-value pairs of an entity from the database (SELECT) and then do mostly skip or UPDATE, than use the "REPLACE" or "INSERT on some conflict UPDATE" strategy.
"REPLACE" and "INSERT on some conflict UPDATE" do not handle surplus values of a key (arrays). In order to know of the surplus one has to either fetch data by using SELECT or run a compulsive DELETE after each ended key->value writing to the database (all elements of array written). This is is circumvented by reading all key->value pairs before beginning in the method (the DELETE will be skipped if not needed).
These are the main considerations for the workings of the method.
Set the permissions on a specific entity.
This methods takes these options in the following order:
subject Entity id of the entity which the permission masks are to be set for. Required.
object Entity id of the entity witch the permission masks are set on. Required.
grant The grant mask to set. Accepts undef (no bits set).
deny The deny mask to set. Accepts undef (no bits set).
operation Defines how to apply the bitmasks. undef means replace bits, true (eg. 1) means set bits and false (eg. 0) means clear bits.
The method returns a reference to a LIST of the grant and deny permission masks after completion of the operation (in that order).
Undef is returned upon failure. Please check the exact error message by calling the error()-method.
Sets a log entry.
Input is in the following order:
time Time of log entry. If undef will default to current time.
entity Entity id which the log entry concerns. Required.
loglevel loglevel of the log entry. See the enumLogLevels()-method.
tag Tag the message entry in the log. Optional. SCALAR. Will default to "NONE". Valid characters are A-Z, a-z, 0-9, "-" and "_". Maximum size is 16 characters.
message Textual message for the log entry. Defaults to a blank string.
Return value is 1 upon success, 0 upon failure. Check the error-method for more information upon error.
This methods updates set modification time for a table.
Required parameter: table name - table to update mtime for.
Optional parameter: mtime - time to set, defaults to now.
Time format is floating unix time.
Return value: undef on failure, 1 otherwise.
Sets the constraints of a template.
Input parameters are in the following order:
id Entity ID of the template to set/change. SCALAR. Required.
constraints Constraint definition(s) to set on template. HASH-reference. Optional. If not set, will just not set any constraints on the template in question.
reset Whether to reset/delete all existing template contraints, before applying new ones (or do nothing). BOOLEAN. Optional. If not specified the method will just apply the new constraints given, ignoring keys that have been already set. Since booleans does not exist as a type in Perl, it is enough that the expression in "reset" evaluates to true, but is technically just a SCALAR.
The template constraints HASH has the following format:
( KEY => {
default => VALUE,
regex => VALUE,
flags => VALUE,
min => VALUE,
max => VALUE,
comment => VALUE,
}
)You can set any number of these KEY-constraints that you want on a given template. With KEY here is meant the textual name of the metadata key on an entity.
Please note that the values undef and not exists are interchangable concepts when it comes to templates. Undef is the same as the key does not exist and/or is not defined. So when setting a template, a value not specified will appear as an undef-value when loading that same template again (see the getTemplate-method). The exception to this behaviour is when getting the aggregated template of an entity by calling the getEntityTemplate()-method. Here it will default values at the end that has not been defaulted by the metadata definition. There are in other words no valid value in AuroraDB for undef. Undef just means that it is not existing or defined.
This method will also strip away flags bit-combinations that are not allowed, such as SINGULAR at the same time as MULTIPLE. Singular is preferred (conservative approach).
The meaning of the KEY-constraints are as follow:
default Default value(s) for the template key in question. Defaults to undef. It sets which values to be set by the template if user does not fill in anything. This constraint can contain one or more values. If it contains more than one value it is to be a pointer to a LIST. Several values can also be combined with the SINGULAR and MULTIPLE flag to indicate that the value entered is to be chosen from one or more values in this default (see the flags constraint). Then the default-constraint will act database-like (but not storing an ID or identifier like a database would).
regex The regex for checking the template key value in question (when used). Defaults to undef. You are not to include the slashes of the regex, just the regex-expression itself.
flags The flags of the template key in question (bitmask). Defaults to undef (no flag bit set). Supported flags are: MANDATORY, NONOVERRIDE, SINGULAR, MULTIPLE, PERSISTENT and OMIT. The meaning of these flags are as follows:
MANDATORY The key is mandatory to be answered. If default is defined, this will be chosen in the event of a missing value.
NONOVERRIDE The key definition is not allowed to be overridden. Template further down are not allowed to change the constraints and defaults of this key.
SINGULAR States that the key is to have a value from one of the value(s) in the constraint "default". The key will then act like in a database and the value entered will be checked against the default(s).
MULTIPLE States that the key is to have a value from one or more of the value(s) in the constraint "default". If enabled together with the SINGULAR-flag, the SINGULAR-flag will take precedence and the MULTIPLE-flag will be stripped away.
PERSISTENT States that key value is not to change once it has been set by any updates later on.
OMIT Omits a key from the template. This can be used to remove key-constraints further down the entity-tree.
min The minimum number of values to enter for this template key. Defaults to undef (not defined/default does not exist).
max The maximum number of values to enter for this template key. Defaults to undef (not defined/default does not exist). Multiple values on a template key equates to an array.
comment Textual comment upon the constraint that explain what is expected in a normal and understandable language. Defaults to undef (not defined/default does not exist).
Return value is 1 upon success, 0 upon failure. Check the error()-method for more information on a potential error.
Removes template assignment of given type on entity. A wrapper around assignEntityTemplate.
Input is entity id and entity type. See assignEntityTemplate()-method for more information.
Return value is 1 on success, 0 on failure. Check the error()-method for more information.
Updates the PERM_EFFECTIVE_* tables to keep PERM_EFFECTIVE up to date.
No input parameters
Return 1 on success, undef on failure.
Calls updateEffectivePerms() if mtime of the source tables differ from mtime of PERM_EFFECTIVE_PERMS.
Updates mtime for PERM_EFFECTIVE_PERMS to the mtime of the sources and return true on success.
Return undef on failure.
This methods returns a DBItransaction instance that keep track of who started a transaction, committing transaction and handling rollback and so no with minimal code in the methods: useDBItransaction()
The methods requires no input. Returns a DBItransaction-instance.
See the DBItransaction module for more information.