Package ARoad0.gBase

CORE OF THE PROGRAM This package contains the fresh object-oriented database management system for Access Road; this package documentation page is recommended as a first reading for all the Access Road developers.

See:
          Description

Class Summary
AclEntryImpl This important class is responsible for modeling an access control entry which manages some access rights or some access restrictions from an eligible party to a resource.
ACSFactoryImpl This class is responsible for creating a new ACS, defining its structure, and creating the restrictions on the objects, rights, privileges and types values when an ACS is created.
ACSFactoryUtilityImpl This class is an important utility class for ACSFactoryImpl, with only static methods.
ACSImpl This class is responsible for modeling an Access Control System (ACS) which is the main unit of modelization for software.
ActorImpl This class is responsible for modeling an acting entity which may have access to controlled resources.
AssociateUtilityImpl This class is a utility class for gBase to manage the association scripts.
BaseManagerImpl This large class is the single manager for the Access Road object-oriented database.
BaseUtilityImpl This class is an utility class for all the ACS, with only static methods.
BasicImpl This class is responsible for modeling the member of a folder (VirtualFolder or ViewInBase) in an ACS, and it ensures the handling of Privileges.
CAliasImpl This class is an embedded class responsible for modeling an ACSObject as reference to an alias, and/or as alias of a reference.
CFolderMemberImpl This class is an embedded class responsible for modeling a folder member which is contained in a EPRViewInBase or in a VirtualFolder.
CNodeImpl This class is an embedded class responsible for modeling a node which contains children (leaves and nodes) as a private attribute of a composite class instance, called the master instance.
CPrivilegeUserImpl This class is an embedded one, responsible for modeling a privilege user.
DirectoryImpl This class is responsible for modeling a directory which contains children, as resources and other directories.
EligiblePartyImpl This class is responsible for modeling the simplest rights user for which an ACS grants access or denies access to some targets through AclEntries or Privileges.
EPRViewInBaseImpl This class is responsible for modeling in the base, a view about access control issues between eligible parties (EP of EPRViewInBase) or virtual folders as access sources, and resources (R of EPRViewInBase) or virtual folders as access targets.
FolderAbst This abstract class is responsible for managing a folder of BaseObjects (even if most of the code is adapted to ACSObjects folder), where the members are added and removed from the container _without_ object deleting.
GroupIDImpl This class is responsible for modeling a GroupIDMember that owns a set of members, and which has Account/Group rights on Resources.
GroupIDMemberImpl This class is responsible for modeling the entity which is a GroupID member.
ISFactoryUtilityImpl This class is responsible to define the IS constraints and controls to use for an ImmutableNameISTree by BaseManager and other classes.
ISNodeImpl This class is responsible for describing the IS nametree nodes and composites for displaying them in the GUI.
NameImpl This class is responsible for managing the names for all the database objects.
NameISTreeImpl This class is responsible to manage for IS nametrees, a tree of ImmutableNames with specialized links to the other nodes.
NameTreeImpl This class is responsible for managing a fast-methods tree of ImmutableNames.
NoThanViewInBaseImpl This class is responsible for managing the No-More-Than and No-Less-Than views.
PrivilegeAbst This abstract class is used by its subclasses for creating the Privileges.
PrivilegeForLinksImpl This class is responsible for modeling the direct links which manages some access rights from a EligibleParty list (or only one GroupID) to a privilege targets list (or only one target).
PrivilegeForTypeImpl This class is responsible for modeling a set of rights from a source with a given type, to an access target with another given type.
ResourceImpl This class is responsible for modeling a resource, that is an access target, in an access control system on which it is registered.
SketchViewInBaseImpl This class is responsible for modeling in the base, a sketch view about access control issues between access sources and an ACSObject, called the center, and between this center and access targets (Resources or VirtualFolders).
StringMetaRightImpl This class is responsible for managing the canonical (or generic) rights for all the base objects.
StringRightImpl This class is responsible for managing a right.
UserIDImpl This class is responsible for modeling an account in an ACS, as a kind of GroupIDMember that owns some resources and a primary groupID.
UtilityImpl This class is an utility class for BaseObjects, StringRights, the BeanInfo and the AcsAddon management.
ViewInBaseImpl This class is responsible for modeling a view which is the backing data of a GraphicView in the GUI.
VirtualFolderImpl This class is a container of Resources belonging to one ACS, responsible for being a PrivilegeTarget, an alias or an alias reference.
 

Package ARoad0.gBase Description

CORE OF THE PROGRAM

This package contains the fresh object-oriented database management system for Access Road; this package documentation page is recommended as a first reading for all the Access Road developers. This page contains an overview of the design principles, the functions, the design patterns and the architecture of the Access Road software. The second recommended reading is the package documentation page of ARoad0.gWork, where the design of the access path searching is described. This page describes also the general principles this package applies to provide a mature, fast and extensible in-memory database management system.

All the object-oriented database management system for Access Road is into this gBase package, and this is its unique responsibility. In Access Road, the modelling of the access controls of a given software is provided by one or several Access Control Systems (ACS) and its inner components. One ACS is suffisant in most of the cases. The ACS are modelled in this package by the ACSImpl class, which may be subclassed into the ACS addons.

The Access Road user may define the properties of a new ACS through the GUI. If it is a generic, non-addon ACS, it uses directly the ACSFactoryImpl class and its BeanInfo class. An advanced user may creates through the GUI a new ACS from another one, typically by editing some limited properties like the type policies. For the Java developers, it is possible to configure extensively a new ACS, like for the RBAC application in the class gWork.AcsFactory. In all cases, it is recommanded to well understand the class ACSFactoryImpl before the study of the ACS addons. The AcsAddon pattern may provide a complex simulation with a minimal effort, like for Linux Ubuntu and MySQL, when the generic features of this gBase package are not enough. The main principle is to subclass the generic gBase and gWork classes in dedicated packages. It represents the second way to define a new ACS, for the Java developpers only. The last level of coding, of course, is to extend or modify the Java classes of this generic gBase package, and to be then beyond the AcsAddon pattern. The main risk is to impact without control the access paths search into the generic gWork package. This is to reserve to the cases which cannot be managed by the AcsAddon pattern. It is recommanded then to code a new version of Access Road including the new features as generic ones, to allow any AcsAddon to use it in the future.

PRESENTATION OF THE MAIN CLASSES

Before the overview on the design, this section provides a quick look on the main Java classes Access Road handles in the gBase package to simulate a software. An ACS contains a catalog of components, so-called ACSObjects, which are registered into the ACS at their creation. The relation ACS/ACSObject is strong, since the deleting of an ACS deletes all its ACSObjects. The main ACS components, implementing the interface ACSObject, are made with the following classes:

OVERVIEW OF THE DESIGN AND THE TEST STRATEGY

We provide in this section an overview on the Access Road design. Generally speaking, Access Road 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, all in layers of different abstraction levels. Like a diamond flashing under the light that goes across it, a great software is transparent to the human understanding because its internal structure is trully coherent. It is just as the diamond atoms are, after the great pressure of the design effort. This requires an iterative structure-driven and abstraction-driven development process. Starting from the true issue, that is to master the code, testing and improving the code is based on a solid ground. SOLID (Single responsibility, Open-closed, Liskov substitution, Interface segregation and Dependency inversion) is a mnemonic acronym introduced by Robert C. Martin in the early 2000s which stands for five basic principles of object-oriented programming and design. Access Road does apply the SOLID way. This is why the design and the documentation of Access Road represents about 50% of the overall development effort.

Software testing is always mandatory, but the need of testing may be lowered by the best use of structures and abstractions. For instance, if I code a method '2+5', I has to test the result is '7', but if I code 'x+y', I put more abstraction in the code. The first tests may be with a limited set of arguments for x and y. The next iterations will allow to write the code easilly, if I master this 'x+y' abstraction. If I find a bug in the 'x+y' computing for a new couple of argument, it will be the time to debug it. Through this process, abstraction simplifies the understanding of the code, and limits the number of testing cases. This does not mean that hidden bugs are totally avoided, but layered abstraction drives to a natural use of the code where the hidden bugs are rarely met, and more easy to fix. But because we are in the real life, there are also some good conter-exemples. A first conter-exemple is for the type-oriented policy for the ACS. Our choice there is to allow the Access Road user to define extended properties through the GUI, at the creation of an ACS, even if this produces a code rather difficult to validate. With the structure-driven and abstraction-driven development process, it is a good idea to put integrity controls in the code, as method entry controls and consistency controls. Of course, they are based on the semantic of the abstractions. These controls remains generally very stable during the improvement of the software. Last but not least, an abstraction-driven code is smaller, more clear and more dense, simply because there is more smartness in it.

It is not very efficient to test the simplest test cases in programmed tests. The unit testing of a method does not usually check the internal values of the method nor the values of the class properties the method change. This is why the careful reading of the code is the best way to detect the bugs, typically when the developer wants to improve it in an iterative process. Code review is efficient but boring, while improving the code enforces to perform an implicit but careful code review. This is the strength of the agile development. Secondly, with the help of the integrity controls, running tests have to cover the complex cases, and above all, the cases delivered by the higher levels of the layered abstraction. The more efficient way to valid the code is not to apply some unit and integration predefined tests, where the errors by omission are very difficult to see. It is better to monitor the internal data of the implied classes, then to review their values carefully. This approach works even for validating the cases far beyond the current test cases. Well-chosen test cases are fine, but do not hesitate to apply almost random entry data if necessary. This way of testing uses more efficiently the skills of the developer. Again, this is why it is more powerful. As it is not focused on final test results but on the intermediate data, of course this way of work helps the tester to valid the inner logic of the code. The code behavior is more readable.

A first general mean to monitor the internal data for testing requires simply to print them during the execution of the code. 'System.out.println()' calls are required. The Access Road code is full of such calls the code maintainer may easily enable and disable at any moment. The beauty of this testing approach is that no heavy development tool is needed, but a text editor, a Java compiler, and above all, the clear mind of a skilled developer. A second way to monitor the internal data for testing is to read the access paths of a view, because this contain useful descriptions about the paths search logic. With the functionnal-programming style of the access paths search, in the gWork packages, providing a detailled human review of these paths is an efficient way against bugs. Some comparisons between the access paths from two successive versions of Access Road may also be powerful to help the developer to trully understand its new code. We love the continous testing approach through automated tests based on a risk analysis. The previous principles may be seen as an extension of this well-known way. It is easy to convert the 'System.out.println()' calls into calls to a BaseError instance, to collect all the execution points and to use them as criteria of some automated integration tests, or, as Google says, medium-size tests. These criteria complete the classical set of input/output test data.

The Access Road classes are first Plain-Old Java Objects (POJO), because we think that well-structured and 'well-abstracted' POJO is the proven way to have great software. Interfaces and methods are stable, and their generic nature provides high-level operations. Some robust architectural patterns may then appear through the use of these classes in varied contexts, in an iterative process. The convention-over-configuration approach lets avoid needless work. Without the right property, a given feature is not delivered by the generic classes of the Access Road core. Without ACS addon to include a specific class, the core offers a generic class to get a default behavior. This is completed by the specific ACS configurations of the software simulations, like for Linux Ubuntu or MySQL Server, which may be easily copied and edited.

In the code, the naming convention for the classes, the methods and the properties is clear. Its application is very consistent. Each name is chosen to describe precisely the function of the object, like 'Resource' or 'EligibleParty'. In the gBase packages, a class 'XXXImpl' implements an interface 'XXX' in the relevant gBaseInterface package. It is associated to a BeanInfo class named 'XXXImplBeanInfo'. The AcsAddon class names are derived from the generic class names. The instance-level properties have a name ending with '_'. The method-level properties have a name without '_'. The method arguments have a name starting with '_'.

The Access Road structures are driven by data, rather than by algorithm. We stand for the idea of a strong database model from which the software structures and the algorithms grow up, since this is the true nature of a simulation software. This is the responsibility of this gBase package, with the secondary packages gBaseInterface and gBaseBean. The database model is also the best place for most of the data integrity controls. However, there is an exception for the type-oriented policy. It is not enforced by the gBase package, but by the GUI packages, typically in the Gui1.SimplePropertyEditor class and the gDMak.ActionNewResource class. The data-centric approach is also applied to the path search algorithms, the most complex part of the code. The concept of access path is modelled in the CNot.DisplayableLinkImpl class, and the concept of access link between two path nodes is modelled in the CNot.AccessControlLinkImpl class. In this case, the structures in the gWork package to find the paths may be seen 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 intermediate-data testing is able to test efficiently large constructors and large methods, contrary to the classical way. The path search algorithms are implemented with a functional programming approach, using large static methods. Very large methods with numerous loops are sometimes mandatory for providing the fastest implementations. These methods are strongly structured, to facilitate their editing.

THE ARCHITECTURAL PATTERNS

Several architectural patterns have emerged during the Access Road development, even if they are not always fully presented as pattern in the code documentation:

As a framework for simulators, Access Road needs to offer all these architectural patterns. It provides powerful capacities to simulate a new software, and to integrate it into the GUI and into the other simulations. Interface multiple inheritance, Java reflection in Java and dependency injection are used extensively in the patterns. On the other hand, Java annotations and aspects are never used. They have not proved their usefulness yet. The OSGi standard is much more complex than the AcsAddons pattern. It is not used mainly because the loading of a Java module during the Access Road execution is not a need.

ROLE OF THIS gBASE PACKAGE

The gBase package is responsible to model simple and complex software as access control systems (ACS). It provides models for all the ACS objects and for the views that contain a set of objects for which the access paths are defined. In the spirit of the 'thick database' paradigm, this package drives the display of the base object properties in the GUI, through the BeanInfoPattern pattern, and it drives also the access path search in the gWork package, through the access path search pattern.

The gBase classes protect their internal variables from external editing outside the control of given methods. At every property change, they check in the compliance with the integrity constraints coming down from the generic ACS, then they fire a matched property change event to the external listeners. In the gBase package, the integrity constraints are managed in each Java class in a true object-oriented design. It is not in separate tables like in a relational database. By this way, the reliability, the extensibility and the performance of the database may target a very high level.

In the gBase generic package, the class BaseManagerImpl is responsible for the management of the database. BaseManagerImpl handles the storing of all the data in files, with the Java class serialization. This includes mainly the Access Control System data, the ViewInBase and the Information System data. ACS is the main structure, since it simulates a given software, or a part of software, with its structure, its behavior and its access control functions. Each ACS may be independently created, opened, saved and closed. This is also true for the ViewInBases. To open a view, since the view objects are objects from some ACS, these ACS have to be open.

The Information Systems are tree structures to handle the varied relations between the ACS. They are created, opened, saved and closed with the ACS they use. They may contain passive nodes, for example a physical component. An ACS may have a subACS which is managed as a separated set of components and rights. Among the relations from an ACS to another, there is the tied relation forcing an ACS to be open with its ACS parent. A second relation is the visible space of Information System nodes on which an ACS may be connected around it. A third relation is the alternate relation where an ACS or a subACS is replaced in its access decisions by another ACS or subACS. With the combination of ACS, subACS, tied child ACS and alternate ACS/subACS, it is possible to design powerful structures for simulating complex software. With the concept of visible space, it is possible to manage the space of an ACS network where the relations among ACS are not predefined in each ACS, but are discovered by the nodes search algorithm in each ACS.

The classes ACSFactoryImpl and ACSImpl are used respectively for the construction and the handling of Access Control Systems. ACSFactoryImpl is the most complex class of the program. Its responsibility is to allow the setting of more than 100 properties in an ACS to create. This is the first key of the Access Road versatility. ACSFactoryImpl defines a generic ACS to simulate a given software, its structure and its access control functions.

HOW TO CONFIGURE A NEW ACS

Access Road uses four generic tools to provide the level of flexibility the varied software simulations require in the ACS. They are introduced hereinafter:

To configure a generic ACS without any coding in Java, an advanded user may use three possible ways, offering varied levels of complexity:

THE BASIC CLASSES

In the gBase generic package, some basic classes are used by the ACS main components. They are:

A Directory may manage container-for-target cascading rights to its Resource children, both for the Account/Group (AG), AclEntry and Privilege rights. Nonetheless, the generic packages handles only the AG inherited rights. The two other inherited rights should be managed in the AcsAddon packages. In fact, the creation/removing of an inherited Privilege or AclEntry in a child is not handled by the generic gBase package, while their right updatings are handled.

The container-for-target relation is an inner principle in VirtualFolder to deliver rights to its members as targets, and it manages also container-for-target cascading Privilege rights to the VirtualFolder children (not to the members). At the source side, the container-for-source relation is an inner function of GroupID to deliver rights to its members, and in GroupIDMember to deliver rights to its members and running Actors. On the other hand, Directory and VirtualFolder do not deliver source rights to the sources that are their children or members. The container-for-source principle is managed in DirectoryEP (in a future version) to deliver source rights to its children.

In the generic gBase package, there are several embedded classes with a name starting with 'C', like CNodeImpl. Such a class provides a common large function, like privilege handling or node handling. They are used in different ACSObject classes. Each instance creates one single dedicated instance of an embedded class only when it is necessary. This structure provides a form of multiple class inheritance. It avoids for example to replicate the code for node children in DirectoryImpl and VirtualFolderImpl, since both handle a CNodeImpl instance to do the work. Furthermore, it allows to reduce the memory print of an instance when the object does not use the function, since the embedded class instance in the object is then null. This defines the gBase embedded class pattern. This pattern may be useful for a new function used by several classes in an AcsAddon package. The embedded classes in the generic gBase are never directly used by the other packages, but they may be sub-classed by an AcsAddon, just like the other gBase classes.

THE VIEWS

In the gBase generic package, ViewInBaseImpl and its subclasses manage the views. A view is a passive container on which Access Road processes the access paths search to find the paths between all the nodes of the view. There are several types of views:

The other package classes may listen the property changes in the gBase objects, and the generic gBase package uses only the interfaces of the gBaseInterface package. Most of the classes in the generic gBase package are designed to be sub-classed in the AcsAddon gBase packages. There is a dedicated interface the AcsAddons use to declare the specific property changes the other packages have to listen on their AcsAddon objects (see the documentation of the Gui2 and gWork packages).

THE THREADS MANAGEMENT

The threads management and the event management for the views are described in Gui2.GraphicViewBaseListenerImpl. From the multi-threading point of view, the aim is to provide the best use of the processor capacities for searching the paths. The principles of the thread management are presented there only for the gBase package, as following:

THE MANAGEMENT OF THE ACS ADDONS

The principles of the AcsAddon management for the gBase package are presented hereinafter:

FOR FUTURE VERSION: The principles of the tied AcsAddons are presented hereinafter:

THE LIMITATIONS OF THE MODEL

In the version 0.7.2, Access Road has some limits. They are presented hereinafter:

ACCESS ROAD KNOWN BUGS

Ease-of-use: medium. The package is well structured, but the database concepts have to be well understood. There are medium-complexity algorithms to set dynamically the references between the variables, to apply the ACS structure, to define and to apply the ACS policy.

Reliability: medium-high. The main execution paths have been well tested.