H-Sphere Documentation Developer Guide


FreeMarker Access Control List (FMACL) Objects

(2.4.2 patch 3 and up)


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 TemplateHashModel.

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 psoft/hsphere/admin/DomainRegistration.acl file.


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 access_mask


  • 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):

getTLDPrice aru
setTLDPrice ar
lookup e
enableTLD a

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.

User comments
No comments for this page.
Sorry, adding new comments is temporary unavailable

Home   Products   Services   Partners   Support   News   Contact   Forum
© 2020 psoft.net.
All rights reserved.