Last modified: 28 Dec 2007
WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the
official Parallels site.
FreeMarker Access Control List (FMACL) Objects provide an easy and effective way to manage H-Sphere resources and grant
different levels of access to their methods from FreeMarker templates.
This technology is especially useful for making changes in third-party products implemented as
H-Sphere packages (e.g., custom plans and reports).
Formerly, when we needed to handle the same functionality related to different objects
(take domain registration as an example),
we would split the code among these resources. For example, some of the methods would be in BillViewer,
some in BillManager, CreateUser, HsphereToolbox, etc...
This led to problems with changing the code - it had to be changed across a wide variety of classes.
Also, due to that, the same code was often repeated.
Especially, it was hard for third parties to integrate such functionality to H-Sphere.
In particular, to add a custom resource manager, the resource should be added and should be represented in all admin plans,
which, in turn, required changes in the system database.
The idea comes from the fact that some functionality is not really a "resource",
but a set of facilities of common purpose (for example, report generation),
accessed differently on different levels. This solution is implemented in FMACL objects.
To provide access to required methods, the new FreeMarker obj tag is introduced.
Now the methods will be accessible in FreeMarker templates as obj.key.method.
For example, to call the getTLDPrice method
of the psoft.hsphere.admin.DomainRegistration class from a template, we simply write:
Here, domreg is a key associated with psoft.hsphere.admin.DomainRegistration
in the acl_objects.xml file.
Each object is instantiated via default constructor (without params) and
must implement the FreeMarker's
Access permissions to class methods must be set in the corresponding .acl files for each class,
located in the same directory and bearing the same name as the class files.
For example, access permissions for the psoft.hsphere.admin.DomainRegistration class must be set in the
FMACL Objects XML File
The objects are defined in ~cpanel/shiva/psoft/hsphere/acl_objects.xml in the following format:
<object key="reports" class="psoft.hsphere.reports.ReportManager">
<object key="domreg" class="psoft.hsphere.admin.DomainRegistration">
Here, each unique key corresponds to an H-Sphere class. Each class defined here must have its .acl file
in the same directory and with the same name. For example, for psoft.hsphere.admin.DomainRegistration there must be
the psoft/hsphere/admin/DomainRegistration.acl file with access permissions for used methods of this class.
See more on setting levels of access to class methods.
To re-define or customize (merge) the default acl_objects.xml file, set the ACL_OBJECTS property
in a package properties file. See Customizing XMLs With Packages for details.
Setting Levels of Access to Class Methods
Access permissions to class methods are set in hsphere_class.acl files in the following lines:
- key is template hash model key;
- access_mask is a combination of the following characters defining the level of access:
a - H-Sphere admin
r - reseller admin
u - user
e - everyone, including access from the outside of H-Sphere.
Access mask specifies on which level a key is accessible (the level will be determined by checking the plan of a user logged in).
If the key is not accessible, the system will throw TemplateModelException.
Example for setting access permission for domain registration (domreg):
This means that the getTLDPrice method will be accessible by admin, reseller admin and user, setTLDPrice
by admin and reseller admin, lookup by everyone (even if user is not logged in), enableTLD only by admin.
The access will be provided by calling obj.domreg.lookup, obj.domreg.geTLDPrice, etc., in H-Sphere templates.