Skip to main content
Pentaho Documentation

Server

Documentation Library
Table of Contents

Overview

Provides web service calls related to servers, such as allocating sockets and ports, getting the list of slaves and registering them, and displaying the initial Carte page.

Provides web service calls related to servers, such as allocating sockets and ports, getting the list of slaves and registering them, and displaying the initial Carte page.

You will need to modify the example URLs if you are working with the PDI server instead of a standalone Carte server.

The following resources are applicable:

  • /
  • /kettle/allocateSocket
  • /kettle/listSocket
  • /kettle/nextSequence
  • /kettle/registerSlave​
  • /kettle/getSlaves
  • /kettle/status
  • /kettle/stopCarte

Overview

Displays initial Carte page.

GET

Displays initial Carte page.

Example Request:

    GET /    

Response Body

element: (custom)
media types: text/html

HTML response containing content of initial page is returned.

Example Response:

<html>
<head><title>Kettle slave server</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>
<h2>Slave server menu</h2>
<p><a href="/kettle/status">Show status</a><br><p>
</body>
</html>

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.

/kettle/allocateSocket​

The following operations are supported on this resource:

Overview

Allows any client to ask for a port number to use. This is necessary because several slaves can be run on the same host. The method ensures the port number is unique for the host name provided and makes sure the slaves are using valid port numbers. Data communication across a cluster of Carte servers happens through TCP/IP sockets. Slave transformations sometimes open (or listen to) tens to hundreds of sockets. When you want to allocate the port numbers for data communication between slave transformation in a kettle clustering run, you need unique combinations of all the parameters below. port number will be returned in the Response object. If an error occurred you'll receive html output describing the problem. HTTP status code of such response is 500.

GET

Example Request:

    GET /kettle/allocateSocket/?xml=Y&rangeStart=100&host=locahost&id=clust&trans=my_trans&sourceSlave=slave_1
  &sourceStep=200&sourceCopy=1&targetSlave=slave_2&targetStep=50&targetCopy=1    

POST

Content-Type: application/x-www-form-urlencoded should be set to use POST.

Example Request:

POST /kettle/allocateSocket/

POST body

xml=Y&rangeStart=100&host=locahost&id=clust&trans=my_trans&sourceSlave=slave_1&sourceStep=200&sourceCopy=1&targetSlave=slave_2&targetStep=50&targetCopy=1    

Parameters

name description type
xml Boolean flag set to either Y or N describing if xml or html reply should be produced. boolean, optional
rangeStart Port number to start looking from. integer
host Port's host. query
id Carte container id. query
trans Running transformation id. query
sourceSlave Name of the source slave server. query
sourceStep Port number step used on source slave server. integer
sourceCopy Number of copies of the step on source server. integer
targetSlave Name of the target slave server. query
targetStep Port number step used on target slave server. integer
targetCopy Number of copies of the step on target server. integer

Response Body

element: (custom)
media types: text/xml, text/html

Response wraps port number that was allocated or error stack trace if an error occurred. Response HTTP code is 200 if there were no errors. Otherwise it is 500.

Example Response:

    <port>100</port>    

Status Codes

code description
200 Request was processed and XML response is returned.
500 Internal server error occurs during request processing. This might also be caused by missing request parameter.

/kettle/listSocket

The following operations are supported on this resource:

Overview

Gets list of ports for specified host. Method is used for listing all or just open ports for specified host. Response contains port number, which transformation it is (was) used for, current status of the port and last date time used.

GET

Example Request:

    GET /kettle/listSocket/?host=127.0.0.1    

POST

Content-Type: application/x-www-form-urlencoded should be set to use POST.

Example Request:

POST /kettle/listSocket/

POST body

host=127.0.0.1

Parameters

name description type
host Host to get ports for. query
onlyOpen Boolean flag that indicates whether all or only open ports should be returned. Set it to Y to get the list of only currently open ports. boolean, optional

Response Body

text: HTML
media types: text/html

Response is HTML document listing the ports requested.

Example Response:

  <html>
  <head><title>List of server sockets on server '127.0.0.1'</title></head>
  <body>
  
  </Found 5 ports for host '127.0.0.1'>

<p>8088 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0 --> sll/Dummy (do nothing).0 id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false time=Mon Nov 17 09:31:15 BRT 2014
8089 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0 --> sll/Dummy (do nothing).1 id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false time=Mon Nov 17 09:31:15 BRT 2014
8090 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0 --> sll/Dummy (do nothing).2 id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false time=Mon Nov 17 09:31:15 BRT 2014
8091 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0 --> sll/Dummy (do nothing).3 id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false time=Mon Nov 17 09:31:15 BRT 2014
8092 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0 --> sll/Dummy (do nothing).4 id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false time=Mon Nov 17 09:31:15 BRT 2014</p>

</body>>

</html>>

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.

/kettle/nextSequence

The following operations are supported on this resource:

Overview

Increments specified pre-configured sequence.

GET

Increments specified pre-configured sequence. Method is used for reserving a number of IDs and incrementing a sequence pre-configured in Carte server configuration by specified amount. If no increment value provided 10000 is used by default.

Example Request:

    GET /kettle/nextSequence?name=test_seq    

POST

Content-Type: application/x-www-form-urlencoded should be set to use POST.

Example Request:

POST /kettle/nextSequence/

POST body

name=test_seq

Parameters

name description type
name Name of the sequence specified in Carte configuration file. Post body
increment Parameter used for incrementing sequence. If no parameter specified 10000 is used by default. Post body

Response Body

text: HTML
media types: text/xml

Response XML containing sequence value and the increment value used.

Example Response:

  <seq><value>570000</value><increment>10000</increment></seq>  

Status Codes

code description
200 Request was processed.
404 If the sequence was not found or error occurred during allocation
500 Internal server error occurs during request processing.

/kettle/registerSlave

Overview

Registers slave server in the master. The method is used to add or update information of slave server.

POST

Example Request:

  POST /kettle/registerSlave/  

Request body should contain xml containing slave server description.

Response Body

element: (custom)
media types: text/xml

Response contains slave server name or error stack trace if an error occurred. Response has result OK if there were no errors. Otherwise it returns ERROR.

Example Response:

<SlaveServerDetection>
<slaveserver>
<name>Dynamic slave</name>
<hostname>localhost</hostname>
<port>901</port>
<webAppName/>
<username>cluster</username>
<password>Encrypted 2be98afc86aa7f2e4cb1aa265cd86aac8</password>
<proxy_hostname/>
<proxy_port/>
<non_proxy_hosts/>
<master>N</master>
</slaveserver>
<active>Y</active>
<last_active_date/>
<last_inactive_date/>
</SlaveServerDetection>

Status Codes

code description
200 Request was processed and XML response is returned.
500 Internal server error occurs during request processing.

/kettle/getSlaves

Overview

Gets list of slave servers. Retrieves list of slave servers which are known to specific server.

GET

Example Request:

    GET /kettle/getSlaves    

Response Body

element: (custom)
media types: text/xml

Response contains list of slave servers.

Example Response:

    <slaveserverdetections>
    <slaveserverdetection>
      <slaveserver>
        <name>Dynamic slave [localhost:909]</name><hostname>localhost</hostname><port>909</port>
        <webappname/><username>cluster</username><password>Encrypted 2be98afc86aa7f2e4cb1aa265cd86aac8</password>
        <proxy_hostname/><proxy_port/><non_proxy_hosts/><master>N</master>
      </slaveserver>
      <active>Y</active>
      <last_active_date>2014/11/17 06:42:28.043</last_active_date>
      <last_inactive_date>2014/11/17 06:42:27.372</last_inactive_date>
    </slaveserverdetection>
  </slaveserverdetections>    

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.

/kettle/status

The following operations are supported on this resource:

Overview

Retrieves server status. The status contains information about the server itself (OS, memory, etc) and information about jobs and transformations present on the server.

GET

Example Request:

      GET /kettle/status/?xml=Y      

POST

Content-Type: application/x-www-form-urlencoded should be set to use POST.

Example Request:

POST /kettle/status/

POST body

xml=Y      

Parameters

name description type
xml Boolean flag which defines output format Y forces XML output to be generated. HTML is returned otherwise. boolean, optional

Response Body

element: (custom)
media types: text/xml, text/html

Response XML or HTML response containing details about the transformation specified. If an error occurs during method invocation result field of the response will contain ERROR status.

Example Response:

      <serverstatus>
        <statusdesc>Online</statusdesc>
        <memory_free>229093440</memory_free>
        <memory_total>285736960</memory_total>
        <cpu_cores>4</cpu_cores>
        <cpu_process_time>7534848300</cpu_process_time>
        <uptime>68818403</uptime>
        <thread_count>45</thread_count>
        <load_avg>-1.0</load_avg>
        <os_name>Windows 7</os_name>
        <os_version>6.1</os_version>
        <os_arch>amd64</os_arch>
        <transstatuslist>
          <transstatus>
            <transname>Row generator test</transname>
            <id>56c93d4e-96c1-4fae-92d9-d864b0779845</id>
            <status_desc>Waiting</status_desc>
            <error_desc/>
            <paused>N</paused>
            <stepstatuslist>
            </stepstatuslist>
            <first_log_line_nr>0</first_log_line_nr>
            <last_log_line_nr>0</last_log_line_nr>
            <logging_string><![CDATA[]]></logging_string>
          </transstatus>
          <transstatus>
            <transname>dummy-trans</transname>
            <id>c56961b2-c848-49b8-abde-76c8015e29b0</id>
            <status_desc>Stopped</status_desc>
            <error_desc/>
            <paused>N</paused>
            <stepstatuslist>
            </stepstatuslist>
            <first_log_line_nr>0</first_log_line_nr>
            <last_log_line_nr>0</last_log_line_nr>
            <logging_string><![CDATA[]]></logging_string>
          </transstatus>
        </transstatuslist>
        <jobstatuslist>
          <jobstatus>
            <jobname>dummy_job</jobname>
            <id>abd61143-8174-4f27-9037-6b22fbd3e229</id>
            <status_desc>Stopped</status_desc>
            <error_desc/>
            <logging_string><![CDATA[]]></logging_string>
            <first_log_line_nr>0</first_log_line_nr>
            <last_log_line_nr>0</last_log_line_nr>
          </jobstatus>
        </jobstatuslist>
      </serverstatus>      

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.

/kettle/stopCarte

Overview

Stops the Carte server. This method must be set up initially through the CLI and is used for stopping the Carte server.

GET

Example Request:

   GET http://localhost:8080/pentaho/kettle/stopCarte

Parameters

name description type
host Host name where Carte is located. query
port Port number for host. query

HTML response containing status of Carte server returned.

Example Response:

<html>
<head><title>Shutdown of Carte requested</title></head>
<body>
<h1>Status</h1>
<p>
Shutting Down
</p>
</body>
</html>

Status Codes

code description
200 Request was processed.
500 Internal server error occurs during request processing.