Package com.parallels.jenkins.api

Interface PrlDevopsApiClient

All Known Implementing Classes:
PrlDevopsHttpClient
public interface PrlDevopsApiClient
Thin abstraction over the prl-devops-service REST API.

All three core operations needed by the Jenkins plugin are declared here. Callers should depend on this interface, not on the concrete HTTP implementation, so the client can be mocked in upstream unit tests.

Every method throws PrlApiException for:

  • non-2xx HTTP responses (carries the status code and parsed error body), or
  • low-level network failures.

  • Method Details

    • cloneVm

      CloneResponse cloneVm(String sourceVmId, CloneRequest request) throws PrlApiException
      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).

      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

      CreateVmResponse createVmFromCatalog(CreateVmRequest request) throws PrlApiException
      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 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.

      Parameters:
      request - Catalog VM creation parameters.
      Returns:
      CreateVmResponse containing the new VM's ID.
      Throws:
      PrlApiException - on HTTP error or network failure.

    • getVmStatus

      VmStatusResponse getVmStatus(String vmId) throws PrlApiException
      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).

      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

      void startVm(String vmId) throws PrlApiException
      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 waitForVmReady(java.lang.String, java.lang.String, java.time.Duration, java.time.Duration) to know when the VM is ready.

      Parameters:
      vmId - ID of the VM to start.
      Throws:
      PrlApiException - on HTTP error or network failure.

    • deleteVm

      void deleteVm(String vmId) throws PrlApiException
      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.

      Parameters:
      vmId - ID of the VM to delete.
      Throws:
      PrlApiException - on HTTP error or network failure.

    • waitForVmReady

      VmStatusResponse waitForVmReady(String vmId, String vmUser, Duration timeout, Duration interval) throws PrlApiException, PrlApiTimeoutException
      Parameters:
      vmUser - OS user used for the execute-API readiness probe.
      Throws:
      PrlApiException
      PrlApiTimeoutException

    • executeCommand

      ExecuteResponse executeCommand(String vmId, ExecuteRequest request) throws PrlApiException
      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).

      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.