Parallels H-Sphere Documentation Developer Guide

 

Creating Unix-Hosted Resources

 

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.

A Unix-hosted resource is created as follows:

  1. Login as cpanel user to CP server.

  2. Create a class that implements this resource.

    Create a new H-Sphere resource class in the ~cpanel/shiva/psoft/hsphere/resource directory. For example:

    package psoft.hsphere.resource;
    import psoft.hsphere.*;
    import java.util.Collection;
    
    public class MyResource extends Resource {
        public MyResource(int type, Collection init) throws Exception {
            super(type, init);
            ...........
        }
        public MyResource(ResourceId rid) throws Exception {
            super(rid);
            ...........
        }
    }
    

    The class must have 2 constructors, as illustrated in the above example.

    1. The first constructor, MyResource(int type, Collection init), is used on the resource creation and its init argument contains the list of the String class objects. The MyResource method's arguments starting from the third are parameters passed from the HTML form. For example:

      <assign result=parent.addChild(request.resource_name,"", db_id, user_id)>

      Here, db_id and user_id are parameters taken from the HTML form.

      In this case, the values of 'db_id' and 'user_id' are passed to constructor as Collection of Strings.

    2. The second constructor, MyResource(ResourceId rid), is used when the user (owner of the resource) is logged in and ClassLoader loads the resource.

    Also, the resource may overwrite the initDone() method called upon the resource creation. initDone() is designed to save all additional parameters into the database and to execute additional scripts.

    The resource may also overwrite the delete() method called upon the recource deletion. This method is used to delete all additional database records related to this resource.

    If the resource creates system resources (directories, files, etc.) on a certain host, the resource should implement the HostDependentResource interface:

    package psoft.hsphere.resource;
    
    public interface HostDependentResource {
        public boolean canBeMovedTo(long newHostId) throws Exception;
        public void physicalCreate(long targetHostId) throws Exception;
        public void physicalDelete(long targetHostId) throws Exception;
        public void setHostId(long newHostId) throws Exception;
        public long getHostId() throws Exception;
    }
    

    In case of the HostDependentResource implementation, the method physicalCreate(long targetHostId) must be called from the method initDone(), and the method physicalDelete(long targetHostId) from the method delete(). The methods physicalCreate(long targetHostId) and physicalDelete(long targetHostId) call scripts to create and delete system resources, respectfully.

    The method canBeMovedTo(long newHostId) should return true if physical components of the resource (files, directories, etc) can be moved to or created on the host. The methods setHostId(long newHostId) and getHostId() respectfully set and get id of the host where resource physical components are located.

    General order of calling methods during the first resource creation is as follows:

    MyResource(int type, Collection init)
    public void initDone()
    public void physicalCreate(long targetHostId)
    

    The resource parameter values predefined in the <plan_name>.xml file can be retrieved by calling the getPlanValue(String key) method defined in Resource.class.

    For example, in unix.xml, the myresource resource is described with the res_myresource construction with the block of predefined values:

    <res_myresource>
    ...
      <values>
        <value name="some_key">some value</value>
        ...
      </values>
    </res_myresource>
    

    Then, to get the value for some_key, the getPlanValue method is used as follows:

    <assign value=myresource.getPlanValue("some_key")>

    In order to retrieve the resource values, FM_ methods should be implemented to be called from the HTML form. FM_ method, with its name having the FM_ prefix, is a method that returns a value of the TemplateModel class.

    If you call an FM_ method from a template, the Freemarker code will look like:

    <assign multiply=myresource.multiply(a, b)>

    Here, myresource is the resource name in the plan, and multiply refers to the FM_multiply(a, b) method, where a and b are the method's arguments.

    In this case, the TemplateModel FM_multiply(int x, int y) method of MyResource class will be called.

  3. Insert resource information into the H-Sphere database.

    Information must be added to the type_name table:

       Column    |          Type          | Modifiers
    -------------+------------------------+-----------
    id           | integer                | not null
    name         | character varying(40)  | not null
    price        | character varying(5)   |
    description  | character varying(100) |
    rprice       | character varying(5)   |
    required     | smallint               |
    priority     | smallint               |
    ttl          | integer                |
    

    Index: type_name_name
    Primary key: type_name_pkey

    Field description:

    • id - unique resource type id
    • name - unique resource name
    • price - flags:
      - M (initial value must be set)
      - R (recurrent)
      - U (usage)
      - F (initial value is optional)
      - S (setup)
    • description - resource description
    • rprice - reseller flags
      - R (recurrent)
      - U (usage)
      - F (initial value is optional)
      - S (setup)
    • required - flag indicating if this resource is required for all accounts
    • priority - must be 0
    • ttl - resource deletion time (must not be set initially)

    To add a resource, insert the resource data into the type_name table, like this:
    INSERT INTO type_name (id,name,description,required,priority) VALUES (119, 'my_resource', 'My Resource',0,0);

  4. Include the resource to the plan XML configuration file.

    The resource should be included into XML configuration files for each type of plans where this resource is to be enabled (for example, unix.xml for Unix plan). These files are located in the ~cpanel/shiva/psoft/hsphere/plan/wizard/xml/ directory.

    You need to add the resource tags with the new resource wherever necessary according to the guide on creating XML plan wizards.

    For example:

    <categories>
    .......................
    <category description="planeditor.myresource">
        .........................................
        <resource name="my_resource" class="psoft.hsphere.resource.MyResource" adminonly="1"/>
        .........................................
    </category>
    .......................
    </categories>
    

    To make the resource available automatically upon accounts' creation, add the res_RESOURCE_NAME construction to the plan XML file, where RESOURCE_NAME is the value set in the name attribute of the resource tag for the given resource.

    Make sure you also set the interface text label set as the description attribute of the category tag. This is done in the custom hsphere_lang.properties file. For the label in the above example, the label is set as follows:

    planeditor.myresource = My Resource

  5. Implement the resource in CP Web interface.

    1) Create templates for this resource.

    Create templates according to the template procedure. See the example below for the templates you may need to add.

    2) Add a new menu item for this resource in CP menu.

    Customize CP menu and add a new menu item to the custom menu.xml, for example:

    ....................
    <menudef id="unix">
    ....................
        <menuitem name="myresource" label="myresource.label"
                    URL="design/myresource.html" resource=""
                    tip="myresource.tip"/>
    ....................
    </menudef>
    ....................
    

    Then, add labels myresource.label and myresource.tip to the custom menu.properties file and run language bundle compiler:
    []$ java psoft.hsphere.LangBundlesCompiler

    Important: Starting with H-Sphere 3.0 RC 1, menu.properties and messages.properties become deprecated, and all labels are merged into a single hsphere_lang.properties for each language!

  6. Create scripts for the resource's physical implementation.

    You must be logged in as root to create these scripts in the /hsphere/shared/scripts/ directory. See the example below on how you may create these scripts.

IMPORTANT:
Make changes to custom templates, interface text bundles and XML files, not to the default ones! Otherwise, you will lose your settings with the next H-Sphere upgrade. Please refer to Customization Guide for details.

Example

Below is a detailed example of how to create and add a new resource to H-Sphere.

  1. Login as cpanel user to CP server.

  2. Create a resource class:

    package psoft.hsphere.resource;
    
    import java.util.*;
    
    import psoft.hsphere.*;
    
    public class MyResource extends Resource implements HostDependentResource {
    
        public MyResource(int type, Collection init) throws Exception {
            super(type, init);
        }
    
        public MyResource(ResourceId rid) throws Exception {
            super(rid);
        }
    
        /*In this case the resource can be moved to any host*/
        public boolean canBeMovedTo(long newHostId) throws Exception {
            return true;
        }
    
        /* This method is started when the resource is created */
        public void initDone() throws Exception {
               physicalCreate(Long.parseLong(recursiveGet("host_id").toString()));
        }
    
       /*
       * Deletes persistant representation of the resource as well as its system/physical representation
       * @throws Exception
       */
       public void delete() throws Exception {
           physicalDelete(Long.parseLong(recursiveGet("host_id").toString()));
       }
    
       /*This method implements method of HostDependentResource interface.
       * In this case method collects the information about resource
       * and runs the 'myresource-init' script with collected
       * information as arguments.
       */
       public void physicalCreate(long targetHostId) throws Exception {
    
        //Unix-based realization:
        List l = new ArrayList();
           l.add(recursiveGet("login").toString());
           l.add(recursiveGet("dir").toString());
           HostEntry he = HostManager.getHost(targetHostId);
           he.exec("myresource-init", l);
    
        //Win-based realization:
    //    WinHostEntry he = (WinHostEntry) HostManager.getHost(targetHostId);
    //    boolean isSOAP = WinService.isSOAPSupport();
    //    if (isSoap) {
    //            SOAPEnvelope envelope = he.invokeMethod("create", new String[][] {
    //        {"resourcename", "myresource"},
    //        {"username", recursiveGet("login").toString()},
    //        {"directory", recursiveGet("dir").toString()}}
    //            );
    //        if (envelope == null) {
    //            throw new HSUserException("The error invoked during SOAP calling");
    //        }
    //    } else {
    //        throw new HSUserException("SOAP is not supported");
    //    }
    
       }
    
       /*This method implements method of HostDependentResource interface.
       * In this case method collects the information about resource
       * and executes the 'myresource-init' script with collected
       * information as arguments in order to physically delete resource.
       */
       public void physicalDelete(long targetHostId) throws Exception {
    
        //Unix-based realisation:
           List l = new ArrayList();
           l.add(recursiveGet("login").toString());
           l.add(recursiveGet("dir").toString());
           HostEntry he = HostManager.getHost(targetHostId);
           he.exec("myresource-delete", l);
    
        //Win-based realisation:
    //    WinHostEntry he = (WinHostEntry) HostManager.getHost(targetHostId);
    //    boolean isSOAP = WinService.isSOAPSupport();
    //    if (isSoap) {
    //            SOAPEnvelope envelope = he.invokeMethod("delete", new String[][] {
    //        {"resourcename", "myresource"},
    //        {"username", recursiveGet("login").toString()},
    //        {"directory", recursiveGet("dir").toString()}}
    //            );
    //        if (envelope == null) {
    //            throw new HSUserException("The error invoked during SOAP calling");
    //        }
    //    } else {
    //        throw new HSUserException("SOAP is not supported");
    //    }
    
       }
    
       /*This method implements method of HostDependentResource interface.
       * id of this resource host cannot be set
       */
       public void setHostId(long newHostId) throws Exception {
           return;
       }
    
       /*This method implements method of HostDependentResource interface
       * and returns value of "hos_id" key in resource tree.
       */
       public long getHostId() throws Exception {
           return Long.parseLong(recursiveGet("host_id").toString());
       }
    }
    
  3. Insert the resource info into the system database:

    []$ psql hsphere
    hsphere=# INSERT INTO type_name (id, name, description, required, priority)
    hsphere-# VALUES (777, 'my_resource', 'My Resource', 0, 0);
    
  4. Add the new resource to plan XML config files.

    For example, ~cpanel/shiva/psoft/hsphere/plan/wizard/xml/unix.xml for Unix plan type:

    <categories>
    .......................
    <category description="planeditor.myresource">
        .........................................
        <resource name="my_resource" required="0" noprice="1"
                     class="psoft.hsphere.resource.MyResource"/>
        .........................................
    </category>
    .......................
    </categories>
    

    Note: Resource will be created automatically with accounts if the <res_my_resource> </res_my_resource> tag is defined in unix.xml

    Then, set interface text label for the new resource:

    Edit ~cpanel/shiva/custom/bundles/hsphere_lang.properties:

    ......
    planeditor.myresource = My Resource
    ......
    

    Then, run language bundle compiler:

    []$ java psoft.hsphere.LangBundlesCompiler

  5. Implement the resource in CP Web interface:

    1) create resource template files:

    Create ~cpanel/shiva/custom/templates/common/design/myresource.html:

    <assign template="design/myresource.html">
    <include "functions">
    <call draw_menu("myresource")>
    <include "control/unixuser/myresource.html">
    <call bottom()>
    

    Create ~cpanel/shiva/custom/templates/common/unixuser/myresource.html:

    <call draw_tooltip()>
    <call draw_table_header("2", lang.domain.editincluded.ftp)>
    <tr>
        <td><call draw_label("My Resource")></td>
        <td><call onoff(account.getChild("unixuser"), "my_resource")></td>
    </tr>
    <call draw_table_footer()>
    

    2) add a link to this resource in CP menu

    Add a new menu item in ~cpanel/shiva/custom/xml/menu.xml:

    ....................
    <menudef id="unix">
    ....................
        <menuitem name="myresource" label="myresource.label"
                     URL="design/myresource.html" resource=""
                     tip="myresource.tip"/>
    ....................
    </menudef>
    ....................
    

    Then, add labels myresource.label and myresource.tip to ~cpanel/shiva/psoft/hsphere/lang/menu.properties and run language bundle compiler:
    []$ java psoft.hsphere.LangBundlesCompiler

    Important: Starting with H-Sphere 3.0 RC 1, menu.properties and messages.properties become deprecated, and all labels are merged into a single hsphere_lang.properties for each language!

  6. Create scripts for physical implementation of the resource.

    Note: You must be logged in as root.

    Create the file hsphere/shared/scripts/myresource-init:

    #!/bin/sh
    cd $2;
    mkdir myresource;
    exit 0
    

    Create the file hsphere/shared/scripts/myresource-delete:

    #!/bin/sh
    cd $2;
    rm -rf myresource;
    exit 0
    


© Copyright 2017. Parallels Holdings. All rights reserved.