Global Resources And Resource Dependencies

Last modified: 28 Dec 2007

In version 2.5, the working scheme for global resources in H-Sphere was improved. To simplify describing and provide flexible access mechanism, it was logically split into two parts: 'globals' and 'resource dependencies'.

'Globals' is the mechanism to provide enabling/disabling some features (resources) both for the entire system and for separate reseller hosting systems. By now, we have the following Globals: H-Sphere resources, "key - value" like objects stored in db, Class managed key sets, Class maintained sophisticated objects (former "pseudo resources").

'Resource Dependencies' is a description of how resources/objects depend on other resources/objects. Not only chains of dependencies up to Globals can be defined here, there is also a possibility to describe parent-child and ancestor-descendant resource dependencies. Such resource dependencies are used to make a decision which resources can be added to user accounts and which cannot.

• globals.xml
• resource_dependences.xml
• List of Resource Dependencies

globals.xml

This file lists global resources. Location: ~cpanel/shiva/psoft/hsphere/globals.xml
Example of globals.xml

DTD scheme:

<!DOCTYPE globals [
<!ELEMENT globals (section+, special?)>
<!ELEMENT section ((object | plan_dependent_resource | set)*)>
<!ELEMENT object (check_config?)>
<!ELEMENT plan_dependent_resource (check_config?, user_plan*)>
<!ELEMENT set (check_config?)>
<!ELEMENT maintained_object EMPTY>
<!ELEMENT check_config (property+ | variant+)>
<!ELEMENT variant (property+)>
<!ELEMENT property EMPTY>
<!ELEMENT special (maintained_object+)>
<!ELEMENT user_plan EMPTY>

<!ATTLIST section id CDATA #REQUIRED>
<!ATTLIST section label CDATA #IMPLIED>
<!ATTLIST section description CDATA #IMPLIED>
<!ATTLIST section show (each | globals | plans | custom) "each">
<!ATTLIST section store (each | settings | plans | custom) "each">
<!ATTLIST section online_help CDATA #IMPLIED>
<!ATTLIST object name CDATA #REQUIRED>
<!ATTLIST object label CDATA #IMPLIED>
<!ATTLIST object label_enabled CDATA #IMPLIED>
<!ATTLIST object label_disabled CDATA #IMPLIED>
<!ATTLIST object default (enabled | disabled | unavailable) "enabled">
<!ATTLIST plan_dependent_resource name CDATA #REQUIRED>
<!ATTLIST set name CDATA #REQUIRED>
<!ATTLIST set label CDATA #REQUIRED>
<!ATTLIST set default (enabled | disabled | unavailable) "enabled">
<!ATTLIST set class CDATA #REQUIRED>
<!ATTLIST set managed (globally | reseller) "globally">
<!ATTLIST property key CDATA #REQUIRED>
<!ATTLIST property value CDATA "*">
<!ATTLIST maintained_object name CDATA #REQUIRED>
<!ATTLIST maintained_object class CDATA #REQUIRED>
<!ATTLIST user_plan type CDATA #REQUIRED>
<!ATTLIST user_plan label CDATA #IMPLIED>
<!ATTLIST user_plan default (enabled | disabled | unavailable) "enabled">
]

It can be seen that the root level consists of one or more 'section' elements. Section is the way to combine several 'global' objects or sets into a group and to show them in H-Sphere CP interface in a suitable form.

Beside this, there is also one more auxiliary section 'special' which is used to define "Class Maintained Global Objects".

Elements and attributes:

• section:
  • id: mnemonic identifier; mandatory attribute, the rest are non-mandatory
  • label: a key having correspondences in the language bundle files
  • description: a key, like the above one, for the text describing some peculiarities of the section
  • online_help: a key having correspondence in the online_help.xml file. You may choose which one of 'description' or 'online_help' is more suitable in each particular case.
  • show: by default is set to show always. If necessary, you may restrict this rule by specifying one of the following values:
    • globals: to show in master admin's 'globals' menu
    • plans: to show in reseller plan wizards only
    • invisible: to exclude the section from standard page flow and show it somewhere else on the page calling it by hand (e.g.: admin.getGlobalSection)
  • store: by default, it is set to "each" what means storing the "status" values of all objects in the section both into the 'settings' table of the "hsphere" database and in the table 'plan_value" for reseller plans. Normally, the attributes 'show' and 'store' should match to each other (have the similar values). Be careful with changing these attributes as it may lead to undesired results. For instance, if the attribute 'store' is set to "settings", whereas the section objects are shown in reseller plan wizards, these values won't be stored in the 'plan_value' table, so they won't affect separate reseller hosting systems. And one more case, if the attribute 'store' is set by default to "each", but the globals from this section are prohibited to be shown on the page 'Globals' (e.g. attribute 'show' is set to "plans"), the respective values will be set to "DISABLED" in the 'settings' table. So, all the object in the section will become "Disabled".
• 'Global' object: an H-Sphere resource or a simple "property" that has a mandatory attribute 'name' (treat this as a property key). An example of 'global' object is 'cp_ssl_ip_based'. By default, all global objects are "Enabled" unless you decide to change this by specifying the value explicitly (attribute 'default').
  • default: if necessary, you may change it to 'disabled'
  • name: mandatory attribute, the rest attributes are non-mandatory
  • label: the same as for 'section'
  • label_enabled, label_disabled: replace the 'label' attribute and are used to show the object as radio button instead of checkbox
• plan_dependent_resource ( in H-Sphere 3.1): added to provide solution for disabling resources for different plan types separately, frontpage for Unix and Windows platforms in particular
• set of keys: the way to describe a group of entities where each of them contains a unique key, description and status. An example of a set is "Logical Server Groups". Each server group has a key which is group id, description and status. Due to significant difficulties to describe each global set in XML, the behavior of this type of 'globals' is realized by a Java class specified with attribute 'class'. The other attributes 'label' and 'default' are described above.
  • managed: this attribute shows if this global resource, being managed by admin, is also manageable by reseller: managed="reseller". In particular, this is implemented in dedicated server template where resellers can set prices for templates provided by main hosting provider (admin).
    If managed is not set, it is considered to be "globally" by default (i.e., not manageable by resellers).
• maintained_object: "Class Maintained Global Objects" belong to special type of global objects. Each object is maintained by a java class specified in the attribute 'class' in the xml. To get a "Maintained Global Objects" working, all you need is to write a maintainer class maintainer. This class should extend standard class 'psoft.hsphere.global.ClassMaintainedGlobalObject?'. In your class you either
  (a) override the method boolean isEnabled() or
  (b) override all the 3 methods: boolean isEnabled(Reseller r), boolean isEnabled(int resellerPlanId), boolean isEnabled(ServletRequest rq) or
  (c) override all the methods: Globals.State getObjectState(Reseller r), Globals.State getObjectState(int resellerPlanId) and Globals.State getObjectState(ServletRequest rq).
  Doing (a) and (b), you can have only 2 possible statuses for the objects: ENABLED or UNAVAILABLE. The method (c) allows you to have any status you need (at least those ones defined in class Globals.State). Please note that the "Maintained Global Objects" are neither shown on 'Globals' page in the CP interface nor they are shown in Reseller plans. Their states cannot be stored in the database either. Besides, none of the true "H-Sphere resources" can be made "Maintained Global Object".
• check_config: each of the objects/sets described above may require additional checks whether it is configured to work properly in the ~cpanel/shiva/psoft_config/hsphere.properties file. To provide this, the additional structure is added:

  <check_config>
        <property key="..."/>
        <property key="..."/>
        ....
  </check_config>
  

  Here, an object will be considered as "configured" if all of the specified properties are defined in the hsphere.properties file, no matter what values they have. You may strengthening this by specifying the desired values in the 'property' elements (attribute 'value').

  If necessary, you may also implement the "OR" logic in conditions by including the following structure::

  <check_config>
      <!-- Variant 1 -->
      <variant>
          <property key="..."/>
          <property key="..."/>
          ....
      </variant>
      <!-- Variant 2 -->
      <variant>
          <property key="..."/>
          <property key="..."/>
          ....
      </variant>
  ...
  </check_config>
  

  This means that an object has either Variant 1 of each of the specified properties set, or Variant 2 with its list of properties set, etc.

  Note: The same scheme works for describing resource dependencies in resource_dependences.xml (see below). For example:

  <resource name="hosting">
      <variant>
          <requires name="domain" relation="parent"/>
      </variant>
      <variant>
          <requires name="parked_domain" relation="parent"/>
      </variant>
      <variant>
          <requires name="3ldomain" relation="parent"/>
      </variant>
  </resource>
  

  Here, the hosting resource can be a child resource for either domain (Transfered Domain), or 3ldomain (Third-Level Domain), or parked_domain (Parked Domain) resources.

resource_dependences.xml

This file describes relationships between parent and dependent resources. Location: ~cpanel/shiva/psoft/hsphere/resource_dependences.xml
Example of resource_dependences.xml

This xml file is based on the following DTD:

<!DOCTYPE dependences [
  <!ELEMENT dependences (resource+)>
  <!ELEMENT resource (requires+ | variant+)>
  <!ELEMENT variant (requires+)>
  <!ELEMENT requires EMPTY>

  <!ATTLIST resource name CDATA #REQUIRED>
  <!ATTLIST requires name CDATA #REQUIRED>
  <!ATTLIST requires relation (parent) #IMPLIED>
]>

As you can see, this is quite a simple structure, so it is very easy to write resource dependence rules. E.g. to become available, resource 'vps_ip' requires enabling resource 'vps':

<resource name="cf_dsn_record">
    <requires name="odbc"/>
    <requires name="cf"/>
</resource>

Using the attribute 'relation' you may specify that the required resource is a direct parent or ancestor for the current resource.

List of Resource Dependencies

Note: This table of resource dependencies is listed here as an example for H-Sphere 2.5 Beta 1. It will be modified with subsequent H-Sphere versions.