Contains the classes of the second core of the program that processes the search of rights in the open views. It provides also « facade » classes for the ACS and the views. The ACS are built up by the AcsFactory class.
Generally speaking, the Access Road software is based on a solid object-oriented design. The best way to provide great software at the best cost is to concentrate the efforts on clear and structured data, clear and structured patterns, clear and structured documentation, in layers of abstraction. This is an iterative structure-driven and abstraction-driven development process, rather than a test-driven process. This point is presented in the gBase package documentation.
We love the idea of a strong database model from which the software structures and the algorithms emerge, since this is the true nature of a simulation software. This is also true for the path search algorithms, which are the most complex part of the code. The concept of access path is modelled in the DisplayableLinkImpl class, and the concept of access link between two path nodes is modelled in the AccessControlLinkImpl class. In this case, the structures in the gWork package to find the paths may be see as oriented by the semantic geometry of the possible links between the path nodes. Again, the path search algorithms are the result of an iterative structure-driven and abstraction-driven development process.
The Access Road classes are first Plain-Old Java Objects (POJO), because we think that well-structured POJO is the proven way to have great software. Interfaces and methods are stable, and their genericityprovides high-level operations. Some robust coding patterns may then appear through the use of these classes in varied contexts, in an iterative process.
Several architectural patterns have emerged during the Access Road development, even if they are not always presented as pattern in the code documentation:
The little decision maker pattern in the gDMak package is responsible to manage the basic operations from the events of the menu.
The little internal frame pattern in the Gui1 package is responsible to handle the internal frames in the Access Road desktop.
The gBaseBeanInfo package applies an extended JavaBean pattern called the BeanInfoPattern, to set the handling of gBase objects in the GUI. This pattern covers the display of each property of the base object in the right GUI editor, and the policy to create, edit and delete the property. It is applied mainly by the gBaseBeanInfo and the Gui1 packages.
The embedded class pattern provides a form of multiple class inheritance for the classes in the gBase packages.
The event management pattern for the views is responsible to update a displayed view when a relevant property is changing, from a view node or an intermediate node in any access path of the view. It is described in the documentation of Gui2.GraphicViewBaseListener.
The thread management pattern for the views is responsible to provide a dedicated thread to each displayed view, for processing its own access path searches.
The access path search pattern is the most complex one. It includes mainly the generic gWork package and the AcsAddon gWork packages which contain the search algorithms. There is also the Gui2 package with the GraphicViews, and the CNot package which contains the notification interfaces and classes for the data flow between the gWork packages and the GUI-oriented packages.
The pattern for the AcsAddons is explicit and well documented, covering the coding for each of the classes and methods which belong to it. It is mainly implemented in the gBase and the gWork packages. This pattern allows to add easily some Java classes to do specific gBase and gWork functions. More precisely, it inserts "hooks" (upcalls to the AcsAddon code, through overridden methods) at every point in the generic code where the concept or the algorithm is about to result in product a wrong simulation of access control.
As a framework for simulators, Access Road needs to offer all these coding patterns. It provides powerful capacities to simulate a new software, and to integrate it into the GUI and the other simulations.
The generic gWork package contains the algorithms of the generic (or core) rights search. The first aim is to build up and update the current DisplayableLinkImpls in the views. Most of these DisplayableLinkImpls will be displayed in the view diagram of a full view. A NoMore-NoLess view uses DisplayableLinkImpls without displaying. Another exception is for the MySQL server AcsAddon for a full view. When it finds a 3-nodes path like GroupID/acl/Actor/run_under/GroupID, since such a path has no effect, it is not visible in a view diagram, although it is put in the 'See Why' text of the view. The only case where the 'See Why' text does not display a DisplayableLinkImpl is when too many paths contain the same 3-nodes sequence, for a couple of view objects. This gives an uselessly large list of DisplayableLinkImpls. For such a view couple, only 5 of these paths are displaying in the 'See Why' text. Studying the class ThreeNodesRightsFactoryImpl is a good start to understand the logic of access path searches.
The classes in a gWork package may handle any gBase entities and concepts, and the classes of the generic gWork package handle all the generic gBase entities and concepts. This includes the Account/Group rights, the ACL rights, the Privilege rights, the Bridge rights. They handle also the CNot package concepts, like the varied relations between view nodes that AccessControlLink defines. The generic gWork package proceeds searchs in the core algorithms also on the gBase entities of the AcsAddons. On the other hand, the AcsAddons gWork packages contains subclasses of some generic gWork classes. They have to handle properly the entities of their AcsAddon and any entity from a gBase package. For a given view, most of the algorithms in this package are naturally not used, since the processing is based on the true properties of each node in the view. But this package is designed, coded and tested to be used for all the possible states in the gBase package objects, including the about 100 properties of an ACS. The access paths are detected at the request of the views in the package Gui2. This set defines a set of classes and a required behavior which is called the access path pattern, that includes also the CNot package.
The interfaces in gBaseInterface are used extensively to analyze different ACSObjects from different AcsAddons in the generic algorithms. The AcsAddon pattern provides a mean to change the generic algorithms, and not simply to add new algorithms without modifying the generic ones.
This package contains some classes based on a classic object-oriented design. But the gWork packages are rather grounded, for the main classes, on functional programming. This approach allows to implement the access paths algorithms. The classes xxxRightsFactoryImpl are stateless. Their methods implement pure functions without secondary effects. The only instance variables are the instances of the other xxxRightsFactoryImpl classes which collaborate with it. Functions are without secondary effects since there is no instance property to update, and all the properties are in the method arguments. Thus, all the access path algorithms may be viewed as building up new ARoad0.CNot.DisplayableLinkImpls, as the result of the analysis of the rights and the structures. This is why the method main argument is the map of all the current DisplayableLinkImpls, usually named _m_l_DisplayableLinks (or _upd_m_l_DisplayableLinks to indicate it may be updated by the method, but this not a mandatory naming rule). At each method call, this map may be filled with new DisplayableLinkImpls, and at the end, Gui2.GraphicView reads the map to display the view diagram and the view 'See why' text. Managing the sequence of method calls in the rights search through the gWork classes is the responsibility of the class RightsFactory_Facade.
There are varied uses of the search paths methods:
For a gBase.EPRViewInBase class, RightsFactory_Facade passes on the called methods the view and its graphic view as arguments.
For a gBase.NoThanViewInBase class, RightsFactory_Facade passes on to the called methods a transient EPRViewInBase and the graphic view of the initial NoThanViewInBase. Each transient view contains a pair of nodes from the NoThanViewInBase to analyze, with one EligibleParty and the first target.
For a gBase.SketchViewInBase class, RightsFactory_Facade passes on the classical arguments, like for an EPRViewInBase, but for a view which has been filled by the method ViewInBase_Facade.populateSketchView().
The classes in the generic gWork package are designed following the design pattern Visitor, in the GoF design pattern collection. The package is organized by right type (AG, ACL, ...), and by path size. The gWork package is well structured, not only at the class level, but also in the body of the large methods it is necessary to have. Into the functional style, patterns of code are used and reused, and it is recommended to keep them in the future evolutions.
The path search is always from the source to the target. For processing the large paths, the DisplayableLinkImpls list of a view grows up like a bunch of flowers, where the new stalks are longer and longer. At the end, only the 'flowers' which belong to the view remain, and the result appears like a spindle-shaped bunch. A second search in the sens target-to-source would improve the search speed, but this is not done for the moment.
The main searching pattern is presented hereinafter, to find the new paths from an ACSObject A at the end of in a given DisplayableLinkImpl:
The nature and the properties of the ACSObject A defines the methods to call in the search of a new extension of the current access path. The nature and the properties of A also define the types of link this path extension may have, in the context of its ACS. For instance, if A is an UserID in an ACS managing the Account and the Account Rights, a possible path extension will be the owning relation on any Resource this UserID owns.
The path extension is added at the end of the current DisplayableLinkImpl having A as second node, if it is compatible to the properties of the current DisplayableLinkImpl nodes. This defines new DisplayableLinkImpls which are added to the map of the current DisplayableLinkImpls of the view. The last AccessControlLink of a new DisplayableLinkImpl describes the nature of the new relation, while the other AccessControlLinks and nodes are copied from the initial DisplayableLinkImpl. A searching method may sometimes update a current DisplayableLinkImpl, to add a comment for instance, whitout extension of the path.
These paths are passed on from searching method to searching method in a map generally called _m_l_DisplayableLinks or _upd_m_l_DisplayableLinks. They are in dedicated gWork classes following the nature of the relation to find, like AclEntries or Privileges, or the size of the path, since the 3-nodes paths are found by a dedicated ThreeNodesRightsFactoryImpl class, while the paths greater than 3 nodes are also searched by a dedicated gWork CompoundRightsFactoryImpl class.
The access path search ends for a DisplayableLinkImpl, (1) when the second end belongs to the view, (2) when there is no more relation to discover from the second end, or (3) if the number of nodes is greater than 40.
Some filtering methods exist at different steps of the search to remove a DisplayableLinkImpl when a priority rule has to be fulfilled, like for instance between the UserID rights and the groupID rights.
This generic gWork package contains complex algorithms. The processing from an intermediate node to another intermediate node, in a large path, requires numerous tests. This implies to consider 19 cases, including 7 tests if the first intermediate node is an Actor, 8 tests for a GroupIDMember, 4 tests for a VirtualFolder, and 3 special tests for the AcsAddons on Actor, GroupIDMember and VirtualFolder. To have a look on the complexity of the access paths among the generic gBase objects, let's see the list of such paths in the documentation of the method detectOneHiddenNodeCompoundRights(), in the class gWork.ThreeNodesRightsFactoryImpl. This method detects about 100 different forms of paths of 3 nodes.
The generic gWork package is associated in the GUI to the Gui2.GraphicView and its subclasses. They are responsible to display the DisplayableLinkImpls the gWork packages provide. Gui2.GraphicView and its subclasses also belong to the access path pattern.
The generic gWork classes are presented hereinafter:
AclRightsFactoryImpl is a class for the generic processing of Access Control Lists and Bridges. AgoRightsFactoryImpl is a class for Account/Group rights. PrivilegeRightsFactoryImpl is a class for PrivilegeForType and PrivilegeForLinks rights. ThreeNodesRightsFactoryImpl handles all the 3-nodes paths, processing all the types of rights and relations. CompoundRightsFactoryImpl is the most complex class for searching the access paths of more than 3 nodes. It has also specialized methods for some specific links like Bridges, VirtualMembers and Aliases.
RightsMediatorImpl is responsible for listening the property changes in all the nodes and the intermediate nodes of a view. The aim is to detect when such a change requires an updating of the view, on its nodes or its access paths. This class has also the responsibility to manage the core algorithms instances of its view - see the thread management.
There are several levels of methods for the access paths processing. Some methods are dedicated to the search of the simple 2-nodes access paths, or DisplayableLinkImpls. Another level is for the methods dedicated to one ACSObject, and they are in NodeRights. The last level is in LinkRightsImpl for handling the priorities among the rights, like through a filtering of the access paths. There is also a set of common methods that are called from these different levels, including varied general utilities on access paths and rights.
The generic rights processing in this package is designed to be overridden or changed for the rights processing in each AcsAddon. An AcsAddon may add a complementary processing to each view node that has a gBase class from the AcsAddon. In the AcsAddon, this is done in the subclasses of the two generic classes NodeRightsImpl and LinkRightsImpl. It is possible to code varied hooks in these subclasses, for which the methods are empty in the generic super classes.
There is an important rule for driving all the tests on the searching of access path. Whatever the size of an access path (2 nodes, 3 nodes or more), the result must be consistent. Typically, if there is a path A-B-C-D, then the following paths must also exist in the relevant views : A-B, B-C, C-D, A-B-C, B-C-D. On the other hand, if there are the paths A-B-C and C-D, then the path A-B-C-D may have to be found in a view which contains A and D, but only if C is such a 'proxy' node. To test the access path searching, it is recommanded to use a scale of paths from 2-nodes paths to paths of 5 nodes. The most complex method CompoundRightsFactoryImpl.detectHiddenCompoundEpRights() has 3 parts, and finding a 5-nodes path requires one iteration in the central part of this method. This rule helps to deliver a reliable code, since the code for finding the 2-nodes paths, the 3-nodes paths and the larger paths is partially independant.
It is quite easy to add a new access path search in the generic gWork package, if the responsibility of each class and the code patterns are well understood. For instance, the VirtualFolder type EP_VFolder was, in a first non-published version, reserved for having only EligibleParties as members. It appears this was too restricted, for example to model the MySQL views where table columns (as Resources) and stored functions (as Actors) may be members. To add Resources in EP_VFolder VirtualFolder, the controls in the method addEorBaseObject() was simply changed in the class VirtualFolderImpl of the gBase package. There was no change to do in the GUI packages. For the access path search, the single evolution was in the processing of a VirtualFolder member being the source of a relation, as an EligibleParty, since there is now the case where the member is not an EligibleParty. This was analyzed in two methods of the core algorithms: ThreeNodesRightsFactoryImpl.selectOneHiddenNodePathsForVirtualFolder(), and CompoundRightsFactoryImpl.detectHiddenCompoundEpRights(). Handling Resources in EP_VFolder VirtualFolders needs to add no more than 10 lines of code in these two generic gWork methods.
A more complex example of gWork evolution is for the Alias relation. Two ACSObjects may be associated by an alias relation, where the first object is called a reference and the second object is called its alias. This is used in the MySQL AcsAddon. After the adding of the CAliasImpl class in the gBase package, there are numerous new access paths to detect in the gWork package. Considering only the 3-nodes paths, many new paths become possible because alias is applicable to all the ACSObjects. 41 new paths appear in the ThreeNodesRightsFactoryImpl class, like the path 'ep virtual folder/virtual member/actor/alias/reference'. Three methods are added in CompoundRightsFactoryImpl to detect the direct and indirect Alias paths. The searching for large paths has to be completed. The overall effort to handle the Alias relation in the generic gWork package has produced about 130 lines of new code in CompoundRightsFactoryImpl, and the same number of lines in ThreeNodesRightsFactoryImpl. In this specific example, the ratio 'number of new paths'/'number of new lines of code' is quite good, but there is a large number of test cases for validating the new code.
The thread management pattern and the event management pattern for the views are described in the documentation of Gui2.GraphicViewBaseListenerImpl. With the view threads, the first aim is to update quickly the access paths of a view when a property has changed in a view node. This is why it is done outside the event dispatch thread and the main thread, in a pool of worker threads managed by Gui2.ViewModel. The worker threads work also at the view creation or opening. The maximal number of worker threads for the views is set to 3 by code in Gui2.ViewModel. For the generic gWork package, the main principles are:
the classes xxxRightsFactoryImpl provides the core algorithms. Each view has an instance of each of these classes, to perform an efficient multi-threading without thread collision. These classes are stateless.
this is also true for the classes DisplayableLinkUtilities, FactoryUtilities and gBase.UtilityImpl. They implements core algorithms for the access paths search. The 0.6 version solution, that is to use synchronized methods, would produce too much loss of time.
A node in a view, and a found node that should be an intermediate node in an effective access path, use a dedicated NodeRights instance and a dedicated LinkRights instance for each view it belongs to. Each instance of NodeRights and LinkRights is called by only one thread. The two effective classes may be subclasses from the AcsAddon of the node, or may be the NodeRightsImpl and LinkRightsImpl classes of this generic gWork package. These classes are stateless.
A node may be in several DisplayableLinkImpls of the same view, but only one time in a given DisplayableLinkImpl. An ACS may have several ACSObjects in a view. At the analysis level, it needs only one LinkRights instance for each view, but RightsMediatorImpl handles one instance per node.
The RightsMediatorImpl instance of the view manages the associations between 1/ a node and its NodeRights instance, from its AcsAddon or from this generic gWork, 2/ a node and its LinkRights instance, from its AcsAddon or from this generic gWork, 3/ a view and the xxxRightsFactoryImpl, yyyUtilities and UtilityImpl instances for this view, always from this generic gWork.
From the point of view of RightsFactory_Facade, there are small differences in the use of worker threads for updating a view. For a gBase.EPRViewInBase or a NoThanViewInBase class, RightsFactory_Facade is called in a worker thread, as it is describes later. For a gBase.SketchViewInBase class, RightsFactory_Facade is called in the main thread by the method ViewInBase_Facade.populateSketchView().
With the AcsAddon pattern, the path search algorithms are designed in an object-oriented structure. This pattern allows to make use of the generic nature of the gBase concepts in the algorithms. It is possible to add an additional processing, or to alter the generic algorithms, by the mean of new AcsAddons gWork packages.
A simple example of use is the simulation of high-level requirements for roles, in the Workbench software, to design the MySQL Server rights. The generic algorithms deliver an efficient simulation of roles, like for the RBAC application. But it is not suffisant to simulate the roles in the MySQL Workbench, where the ACL of the role has to be copied, in the ACS of the targetted MySQL Server, as the ACL of each user that is member of the role. The MySQL Workbench software is simulated as a subACS into the MySQL Server ACS. In the gBase package of the ACS addon for MySQL, a subclass of GroupIDMySQLImpl, called WorkbenchRoleMySQLImpl, models the Workbench role. It creates and updates each ACL of user from the role ACL. The WorkbenchRoleMySQLImpl BeanInfo displays the role ACL in the beamer as 'high-level requirements', so they cannot be seen as an effective ACL for the access paths. To get this behavior, in the gWork package of the ACS addon for MySQL, the class NodeRightsMySQLImpl has a method detectL_aclEntryRights which returns no right for all the ACL of a Workbench role. That's all! The AcsAddon pattern has allowed us, with about 100 lines of code, to define, implement and explain the concept of high-level requirements for the Workbench roles.
The use of the gWork package in the AcsAddon pattern is presented hereinafter:
The AcsAddon pattern allows a programmer to add more easily to Access Road some Java classes for implementing new gBase and/or new gWork functions. This pattern may be used when these packages do not provide the required functions for the simulation of a given software.
The first solution to study is always to code the creation of a new type of ACS in gDMak.ActionNewACSyst and gWork.AcsFactory, using the current gBase and gWork packages. Otherwise, a first alternative is to modify directly the code of these generic packages. This is more powerful, but may become much more complex, like for adding the Alias relation. Furthermore, the compatibility with Access Road becomes then an important issue, since this compatibility may be lost, and it requires in all cases acareful testing.
On the other hand, with the AcsAddon pattern, the interfaces of the new classes with the Access Road generic packages are designed to be stable and relatively small. With the AcsAddon pattern, only the new functions are coded, and most of the current Access Road code is reused. For these reasons, the resulting code is much more easy to test and maintain. An AcsAddon may be based on another AcsAddon.
Each AcsAddon has specific Java packages. They are named from the AcsAddon name, like 'ARoad0.AcsAddon.Accbee.Ubuntu.gBase' for the gBase package for the AcsAddon Ubuntu from the editor ACCBEE. The AcsAddon may include a gBase package, with its gBaseBeanInfo and its gBaseInterface packages. It always includes a gWork package, with at least an ARoad0.Pattern.AcsFactoryForAcsAddon implementation to create the ACS of the AcsAdddon. In the simplest case, an AcsAddon contains only one AcsFactoryForAcsAddon and one subclass of any generic gBase or gWork class, to change the generic behavior of the class. Ubuntu may be studied to understand a complex use of the AcsAddon pattern.
The core algorithms are the larger part of the generic gWork package code. 5 generic xxxRightsFactoryImpl classes contain these algorithms. They are based on the semantic of the gBase classes, and contain functional programming that works for all the ACSs, from an AcsAddon or not, using the generic gBaseInterface interfaces. These classes are so independent to the AcsAddon packages.
The utility methods are in the classes DisplayableLinkUtilities, RightsFactoryUtilities and UtilityImpl. They cannot be overridden by the AcsAddons.
The NodeRights and LinkRights generic methods are called by the core methods to process each node and the paths. They use the generic properties of an ACSObject and its environment, like the generic properties of a Resource. For instance, in ThreeNodesRightsFactoryImpl, the 3-nodes path groupidmember/is_member/group/is_member/group is analyzed. It uses for this only the core algorithms, some utility methods and generic methods like NodeRights.selectHiddenDirectGroupIDForGroupIDMember(). These generic methods work for all the ACS. They are always called by the core algorithms. An AcsAddon may however choose to override them, for instance to handle differently the rights inheritance in the 'ThroughNodesTree' methods.
There are also in NodeRights and LinkRights some AcsAddon methods, with the name pattern detectAddon... or selectAddon... The core algorithms include the test of the getXXXAddonYYY methods for the node, and if one method returns true, the relevant AcsAddon method is called. For instance, in ThreeNodesRightsFactoryImpl, to take account of the AcsAddon additions in the GroupIDMember relations, the AcsAddon method selectAddonLastViewNodeAfterGroupIDMember() is called on the central group of the 3-nodes path, to detect any path like groupidmember/is_member/group/any AcsAddon relation/group. These AcsAddon methods are empty in the NodeRightsImpl and LinkRightsImpl classes - all the getXXXAddonYYY methods return false - and they may be overridden in the subclasses to write a code that calls some specialized AcsAddon methods.
The specialized methods of an AcsAddon for searching the access paths are in a NodeRightsImpl or LinkRightsImpl subclass. They are called by an AcsAddon method. For instance, in ThreeNodesRightsFactoryImpl, a developer may add a specific SPREAD relation between two GroupIDs in its AcsAddon. He will do it simply by overriding the AcsAddon method selectAddonLastViewNodeAfterGroupIDMember() in his subclass of NodeRightsImpl. selectAddonLastViewNodeAfterGroupIDMember() calls there a specialized method addAliasGroupRelationToDisplayableLink(). In such a case, there is no name pattern for the specialized methods. They use the generic properties of a node and its environment, but naturally they also handle the specific properties of the AcsAddon node. To define the specific relations between the nodes, the AcsAddon use the standard types of CNot.AccessControlLink, but it may add new comments to explain better the link in the 'See why' text. For instance, the MySQL AcsAddon uses an ALIAS link to describe the link between a proxy account and its proxied account.
Since an AcsAddon may be based on another AcsAddon, a subclass may be extended from another NodeRightsImpl or LinkRightsImpl subclass.
In an AcsAddon, to process the AclEntry or Privilege inherited rights, it is necessary to code how the Directory or VirtualFolder subclass updates the inherited rights in its children, since the generic algorithms do not provide this feature. Sometimes, it is also necessary to code the LinkRightsImpl subclass. An example is for overriding some of the six 'ThroughNodesTree' methods which implement the default rights inheritance algorithms.
A typical application of the AcsAddon pattern is for adding a new search algorithm. For instance, it may necessary to handle the typed privileges differently. In that case, a LinkRightsImpl subclass is necessary to override the four 'PrivilegeForType' methods.
Of course, changing a new property in an ACS addon may produce some changes in the access paths. The interface methods ACSObjectAddon.getAddonInnerPropertiesToListen() and getAddonParentPropertiesToListen() describe the AcsAddon property change events any view has to listen, if it contains a node from such an AcsAddon.
This AcsAddon pattern has been described for the case where a dedicated NodeRights is associated to a view node. Since varied relations are always internal to an ACS, it is possible to use the NodeRights of another node from the same ACS. This is done for instance to find the UserID and the GroupID under which an Actor starts its running.
The main limitation of the AcsAddon pattern is to not allow any evolution of the GUI for a given ACS addon. For instance, the Sketcher is not able to display the main EligibleParties having inherited AclEntry or Privilege on a Resource, since the selection of the objects to associate to a Resource, in the Sketcher, is done in a core class, outside the AcsAddon responsibility.
The main limits in the performance of the access paths search, in the 0.7.0 version, are presented hereinafter:
During a search, a DisplayableLinkImpl may have to be removed after its insertion in the final result. The reason is the filtering of access paths to apply some priority rules among the AG, PRI, ACL or the BDG rights. Some of these priority rules may be from an AcsAddon, through the call to a method LinkRights.detectAddonPriorityInXXX(). These methods have the property to detect a priority link which enforces to remove one or several longer links in the final result. The inverse is not true, since a long link cannot produce, by its existence, the removing of a shorter link.
Ease-of-use: medium. The core algorithms are complex, and it is necessary to well understand the CNot and gBase packages before any change. Nevertheless, the AcsAddon pattern provides powerful and simple means to add new simulations, even if all the code in this package is not well understood.
Reliability: medium. There are no known bugs.