Package com.parallels.jenkins.api

Class PrlDevopsHttpClient

java.lang.Object

com.parallels.jenkins.api.PrlDevopsHttpClient

All Implemented Interfaces:

PrlDevopsApiClient

public class PrlDevopsHttpClient
extends Object
implements PrlDevopsApiClient

JDK HttpClient-based implementation of PrlDevopsApiClient.

Construct via PrlDevopsHttpClient.Builder:

   PrlDevopsApiClient client = new PrlDevopsHttpClient.Builder()
       .baseUrl("https://my-host:8080")
       .bearerToken("secret-token")
       .mode(ConnectionMode.HOST)
       .build();
 

For orchestrator mode, no hostId is needed — the orchestrator routes requests to the appropriate host internally:

   PrlDevopsApiClient client = new PrlDevopsHttpClient.Builder()
       .baseUrl("https://orchestrator:8080")
       .bearerToken("secret-token")
       .mode(ConnectionMode.ORCHESTRATOR)
       .build();
 

Thread-safe: a single instance may be shared across threads.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	PrlDevopsHttpClient.Builder

Method Summary

Modifier and Type	Method	Description
CloneResponse	cloneVm(String sourceVmId, CloneRequest request)	Clones the VM identified by sourceVmId.
CreateVmResponse	createVmFromCatalog(CreateVmRequest request)	Creates a new VM from a Parallels DevOps catalog entry.
void	deleteVm(String vmId)	Deletes a VM.
ExecuteResponse	executeCommand(String vmId, ExecuteRequest request)	Executes a command on a running VM.
VmStatusResponse	getVmStatus(String vmId)	Returns the lightweight status of a VM.
void	startVm(String vmId)	Starts a VM that is in the stopped state.
VmStatusResponse	waitForVmReady(String vmId, String vmUser, Duration timeout, Duration interval)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

cloneVm

public CloneResponse cloneVm(String sourceVmId,
 CloneRequest request)
                      throws PrlApiException

Description copied from interface: PrlDevopsApiClient

Clones the VM identified by sourceVmId.

Maps to PUT /api/v1/machines/{sourceVmId}/clone (host mode) or PUT /api/v1/orchestrator/machines/{sourceVmId}/clone (orchestrator mode).

Specified by:

cloneVm in interface PrlDevopsApiClient

Parameters:

sourceVmId - ID of the VM to clone.

request - Clone options (clone name, destination path); fields are optional.

Returns:

CloneResponse containing the new VM's ID.

Throws:

PrlApiException - on HTTP error or network failure.

createVmFromCatalog

public CreateVmResponse createVmFromCatalog(CreateVmRequest request)
                                     throws PrlApiException

Description copied from interface: PrlDevopsApiClient

Creates a new VM from a Parallels DevOps catalog entry.

Maps to POST /api/v1/machines (host mode) or POST /api/v1/orchestrator/machines (orchestrator mode).

The request includes startOnCreate: true so the VM boots immediately after creation. Callers must still poll PrlDevopsApiClient.waitForVmReady(java.lang.String, java.lang.String, java.time.Duration, java.time.Duration) because the VM will be in stopped state momentarily before transitioning to running.

Specified by:

createVmFromCatalog in interface PrlDevopsApiClient

Parameters:

request - Catalog VM creation parameters.

Returns:

CreateVmResponse containing the new VM's ID.

Throws:

PrlApiException - on HTTP error or network failure.

getVmStatus

public VmStatusResponse getVmStatus(String vmId)
                             throws PrlApiException

Description copied from interface: PrlDevopsApiClient

Returns the lightweight status of a VM.

Maps to GET /api/v1/machines/{vmId}/status (host mode) or GET /api/v1/orchestrator/machines/{vmId}/status (orchestrator mode).

Specified by:

getVmStatus in interface PrlDevopsApiClient

Parameters:

vmId - ID of the VM to query.

Returns:

VmStatusResponse with id, status, and ip_configured.

Throws:

PrlApiException - on HTTP error or network failure.

startVm

public void startVm(String vmId)
             throws PrlApiException

Description copied from interface: PrlDevopsApiClient

Starts a VM that is in the stopped state.

Maps to GET /api/v1/machines/{vmId}/start (host mode) or GET /api/v1/orchestrator/machines/{vmId}/start (orchestrator mode).

The API accepts the request and begins booting; the VM transitions through stopped → starting → running. Callers must subsequently poll PrlDevopsApiClient.waitForVmReady(java.lang.String, java.lang.String, java.time.Duration, java.time.Duration) to know when the VM is ready.

Specified by:

startVm in interface PrlDevopsApiClient

Parameters:

vmId - ID of the VM to start.

Throws:

PrlApiException - on HTTP error or network failure.

deleteVm

public void deleteVm(String vmId)
              throws PrlApiException

Description copied from interface: PrlDevopsApiClient

Deletes a VM.

Maps to DELETE /api/v1/machines/{vmId}?force=true (host mode) or DELETE /api/v1/orchestrator/machines/{vmId}?force=true (orchestrator mode). The force=true parameter allows deletion of a running VM without stopping it first. The API returns 202 Accepted with no body.

Specified by:

deleteVm in interface PrlDevopsApiClient

Parameters:

vmId - ID of the VM to delete.

Throws:

PrlApiException - on HTTP error or network failure.

executeCommand

public ExecuteResponse executeCommand(String vmId,
 ExecuteRequest request)
                               throws PrlApiException

Description copied from interface: PrlDevopsApiClient

Executes a command on a running VM.

Maps to PUT /api/v1/machines/{vmId}/execute (host mode) or PUT /api/v1/orchestrator/machines/{vmId}/execute (orchestrator mode).

Specified by:

executeCommand in interface PrlDevopsApiClient

Parameters:

vmId - ID of the VM to run the command on.

request - Command, user, and environment variables.

Returns:

ExecuteResponse with stdout and exit code.

Throws:

PrlApiException - on HTTP error or network failure.

waitForVmReady

public VmStatusResponse waitForVmReady(String vmId,
 String vmUser,
 Duration timeout,
 Duration interval)
                                throws PrlApiException,
PrlApiTimeoutException

Specified by:

waitForVmReady in interface PrlDevopsApiClient

Parameters:

vmUser - OS user used for the execute-API readiness probe.

Throws:

PrlApiException

PrlApiTimeoutException