|role( $role_name )||
Factory method, returns a Tree::Authz::Role subclass
Sets up two permitted actions on the group - the singular and plural of the group name. <B>This might be too cute, and could change to just the group name in a near future releaseB>. Opinions welcome.
|new( $role_name )||
Use role instead.
|get_group( $group_name )||
Use role instead.
|role_exists( $role_name )||Returns true if the specified group exists <B>anywhereB> within the hierarchy.|
|group_exists( $group_name )||
Use role_exists instead.
|subrole_exists( $subrole_name, [ $role_name ] )||
<B>Method not implemented yetB>.
Give me a nudge if this would be useful.
|list_roles()||Returns an array or arrayref of all the role names in the hierarchy, sorted by name.|
Use list_roles instead.
|dump_hierarchy( [ $namespace ] )||
Get a simple printout of the structure of your hierarchy.
This method requires Devel::Symdump.
If you find yourself parsing the output and using it somehow in your code, let me know, and Ill find a Better Way to provide the data. This method is just intended for quick and dirty printouts and could <B>change at any timeB>.
|setup_hierarchy( $groups, [ $namespace ] )||
Sets up a hierarchy of Perl classes representing the group structure.
The hierarchy will be contained within the $namespace top level if supplied. This makes it easy to set up several independent hierarchies to use within the same process, e.g. for different websites under mod_perl.
Returns a class name through which group objects can be retrieved and other class methods called. This will be Tree::Authz if no namespace is specified.
If called with a $namespace argument, then all loaded packages within the $namespace::Tree::Authz symbol table hierarchy are removed (using Symbol::delete_package from the symbol table. This is experimental and may lead to bugs, the jury is still out. The purpose of this is to allow re-initialisation of the setup within a long-running process such as mod_perl. It could also allow dynamic updates to the hierarchy.
Tree::Authz can be used independently of a persistence mechanism via setup_hierarchy. However, if you want to manipulate the hierarchy at runtime, a persistence mechanism is required. The implementation is left up to you, but the API is defined. The persistence API should be implemented by the object passed to setup_from_database.
setup_from_database( $database, [ $namespace ] ) $database should be an object that responds to the persistence API defined below. The object is stored as class data and is available via the _database method.
The following methods are passed on to the database object, after checking whether any changes would result in a recursive inheritance pattern, in which case they return false. The database methods should return true on success.
get_roles_data() Returns a hashref. Keys are role names, values are arrayrefs of subroles.
setup_from_database calls this method on the database object, then passes the data on to setup_hierarchy.
add_role( $new_role, $parent, [ $children ] ) Adds a new role to the scheme.
At the moment I am assuming no multiple inheritance, but things are shaping up to look like theres no great difficulty about allowing it. If allowed, this method should check if $new_role already exists. If it does, ignore any $children (probably raise a warning), add <$new_role> to the sub-roles list of $parent, and return without trying to insert $new_role into the database (because it already exists).
remove_role( $role ) Removes the role from the database, including finding and removing any occurrences of $role in the sub-role lists of other roles.
Returns the list of subroles for the role that was removed, in case you want to put them somewhere else.
move_role( $role, $to ) Makes $role a sub-role of $to, and deletes it from the sub-roles list of its current parent. add_subrole( $role, $subrole ) Adds a subrole to a role. Must remove base from the subroles list if present. remove_subrole( $role, $subrole ) Removes a subrole from a role. If the resulting list of subroles would be empty, must insert base.
setup_permissions_on_role( $role_name, $cando ) Class method version of Tree::Authz::Role::setup_permissions. setup_permissions_on_group( $group_name, $cando ) DEPRECATED.
Use setup_permissions_on_role instead.
setup_abilities_on_role( $role_name, %code ) Class method version of Tree::Authz::Role::setup_abilities. setup_abilities_on_group( $group_name, %code ) DEPRECATED.
Use setup_abilities_on_role instead.
setup_plugins_on_role( $role_name, $plugins ) Class method version of Tree::Authz::Role::setup_plugins. setup_plugins_on_group( $group_name, $plugins ) Deprecated version of setup_plugins_on_role.
The deprecation policy is:
1) DEPRECATED methods issue a warning (via carp) and then call the new method. They will be documented next to the replacement method.
2) OBSOLETE methods will croak. These will be documented in a separate section.
3) Removed methods will be documented in a separate section, in the first version they no longer exist in.
Main changes in 0.02
- changed terminology to refer to I<roles> instead of I<groups>. Deprecated all methods with I<role> in their name. These methods now issue a warning via C<carp>, and will be removed in a future release. - added a new class to represent a role - L<Tree::Authz::Role|Tree::Authz::Role>. L<Tree::Authz|Tree::Authz> is now a static class (all its methods are class methods). The objects it returns from some methods are subclasses of L<Tree::Authz::Role|Tree::Authz::Role>.
Roles are now represented by their own class. This should make it easier to add constraints and other RBAC features.
More methods for returning meta information, e.g. immediate subroles of a role, all subroles of a role, list available actions of a role and its subroles.
Might be nice to register users with roles.
Under mod_perl, all setup of hierarchies and permissions must be completed during server startup, before the startup process forks off Apache children. It would be nice to have some way of communicating updates to other processes. Alternatively, you could run the full startup sequence every time you need to access a Tree::Authz role, but that seems sub-optimal.
Optional - Devel::Symdump.
Sub::Override for the test suite.
Please report all bugs via the CPAN Request Tracker at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tree-Authz>.
Copyright 2004 by David Baird.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
David Baird, firstname.lastname@example.org
|perl v5.20.3||TREE::AUTHZ (3)||2016-03-17|