Parallels H-Sphere Documentation Developer Guide H-Sphere XML API Reference

 

Enabling H-Sphere XML API

 
 

Related Docs:   H-Sphere XML API Reference H-Sphere XML API Security Settings

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.

H-Sphere XML API is designed to manage H-Sphere services via SOAP protocol. It is based on Apache Axis implementation of SOAP and runs under Apache Tomcat engine.

You can download Axis libraries and the latest version of XML API libraries from PSoft site.

WARNING:
H-Sphere XML API is an experimental feature. Please be careful in using it for critical tasks!

 

Enabling XML API

To enable XML API in H-Sphere:

  1. Log into the CP server as the cpanel user.

  2. H-Sphere 2.4.3 Patch 11 and up: Edit the ~cpanel/shiva/psoft_config/allow_access.properties file to grant access to CP server via SOAP port from external IPs.

    [-] SOAP access in earlier H-Sphere versions

    Important: In H-Sphere before 2.4.3 Patch 11 SOAP access to CP server via standard 8080 port was provided by default.
    The following procedure explains how to configure SOAP access via port 8180 and should not be performed in H-Sphere 2.4.3 Patch 11 and up!

    1. Copy the wsdd config file:
      cp ~cpanel/shiva/psoft/hsphere/axis/server-config.wsdd ~cpanel/hsphere/WEB-INF/
      Skip this step if the file is already in the target location.
    2. Edit the Tomcat XML configuration file:
      vi ~cpanel/jakarta/conf/server.xml
    3. Find the following commented fragment:
      <!--Connector port="8080"
                  maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                  enableLookups="false" redirectPort="8443" acceptCount="100"
                  debug="0" connectionTimeout="20000"
                  disableUploadTimeout="true" /-->
      
      and replace it with the following code:
      <Connector port="8180"
              maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
              enableLookups="false" acceptCount="100"
              debug="0" connectionTimeout="20000"
              disableUploadTimeout="true" />
      
      Optionally, leave the port at 8080.
  3. Restart H-Sphere.

After that, XML API will be available. You may wish to test if it works correctly by means of our test Java classes that use H-Sphere XML API.

 

Testing HS XML API

  1. Make sure you are logged into the CP server as the cpanel user.
  2. Download the latest version of test Java classes from PSoft site to the ~cpanel/shiva/psoft/hsphere/axis/test directory (create it first if it does not exist):
    cd ~cpanel/shiva/psoft/hsphere/axis/test/
    wget http://www.psoft.net/shiv/HS/xml-api/AxisExamples.tgz

    Note: AxisExamples.tgz is for the latest H-Sphere 3.0 version. For H-Sphere 2.5, download AxisExamples_25.tgz.

  3. Extract the archive with the command:
    tar zxf AxisExamples.tgz
    Java source .java files will be added into the current ~cpanel/shiva/psoft/hsphere/axis/test/ directory.

  4. Edit the necessary test classes (at least AdminServicesTest.java) replacing URL in the folowing line:
    String endpoint = "http://localhost:8080/psoft/servlet/AdminServices.jws";
    with your URL:
    String endpoint = "http://your_cp_host:8180/your_cp_url_path/AdminServices.jws";
    where your_cp_url_path is by default psoft/servlet but you may change it in your Tomcat configuration.
    If you have enabled XML API with port 8180, make sure it is specified in the URL.
  5. Note: don't forget to include XML API libraries into your java classpass


  6. Compile Java classes:
    cd ~cpanel/shiva/psoft/hsphere/axis/test/
    javac *.java
  7. Upon the successful compilation, run the following command:
    java psoft.hsphere.axis.test.AdminServicesTest admin <hs_admin_password>
  8. You will see the > prompt. Here, enter the line:
    searchbydomainname domain-name
    where domain-name is a customer's domain name.
  9. On the next > invitation, press Enter to force the service to run.
  10. Repeat the previous two steps testing other services, for instance getAccounts, getDomains, searchbydomainname, etc:
    [cpanel@exampleuser test]$ java psoft.hsphere.axis.test.AdminServicesTest admin admin
    >getAccounts example.com
    >Params:1:example.com
    1

    >getDomains example.com
    >Params:1:example.com
    no domains
    See in H-Sphere XML API Reference to learn how to invoke other Web services via XML interface.
  11. Press CTRL-D to stop.

 

Getting the List of Available Services

You may get the list of available XML services by typing in your browser:

http://your_cp_host:8180/your_cp_url_path/AxisServlet
where:
your_cp_host   is your CP host domain (CP_HOST in hsphere.properties), and
your_cp_url_path   is usually psoft/servlet if not configured otherwise in your Tomcat configuration.

If this doesn't work, check servlet mapping in your Tomcat configuration:

  1. As the cpanel user, open the ~cpanel/hsphere/WEB-INF/web.xml file for edition:
    vi ~cpanel/shiva/psoft/hsphere/WEB-INF/web.xml
  2. Make sure the following lines are present in the file:
    <servlet>
    <servlet-name>AxisServlet</servlet-name>
    <display-name>Apache-Axis Servlet</display-name>
    <servlet-class>
    org.apache.axis.transport.http.AxisServlet
    </servlet-class>
    </servlet>
  3. Find the following mapping block:
    <servlet-mapping>
    <servlet-name>AxisServlet</servlet-name>
    <url-pattern>*.jws</url-pattern>
    </servlet-mapping>
    and add the following lines right underneath:
    <servlet-mapping>
    <servlet-name>AxisServlet</servlet-name>
    <url-pattern>/AxisServlet</url-pattern>
    </servlet-mapping>
  4. Restart H-Sphere

  5. Try again this URL in your browser:
    http://your_cp_host:8180/your_cp_url_path/AxisServlet

You may also wish to test AxisTestServlet from the package of test Java classes:

http://your_cp_host:8180/your_cp_url_path/AxisTestServlet

 

Generating WSDL

You can generate WSDL files for H-Sphere XML API services by means of the Axis' org.apache.axis.wsdl.Java2WSDL utility.

For example, to generate a WSDL file for SupportServices, log into CP server as cpanel and run:

java org.apache.axis.wsdl.Java2WSDL -o SupportService.wsdl -l"http://localhost:8080/psoft/servlet/AxisServlet" psoft.hsphere.axis.SupportServices

Example: H-Sphere XML API signup form implementation in PHP 5 (SOAP client embedded) via WSDL.


Related Docs:   H-Sphere XML API Reference H-Sphere XML API Security Settings



© Copyright 2014. Parallels Holdings. All rights reserved.