Parallels H-Sphere Documentation Developer Guide

 

FreeMarker Access Control List (FMACL) Objects

 

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

 

Purpose

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.

 

Implementation

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:

obj.domreg.getTLDPrice()

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:

<objects>
<object key="reports" class="psoft.hsphere.reports.ReportManager">
<object key="domreg" class="psoft.hsphere.admin.DomainRegistration">
...
</objects>

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

where:

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



© Copyright 2017. Parallels Holdings. All rights reserved.