Package org.gitlab4j.api

Class JobApi

java.lang.Object

org.gitlab4j.api.AbstractApi

org.gitlab4j.api.JobApi

All Implemented Interfaces:

Constants

public class JobApi
extends AbstractApi
implements Constants

This class provides an entry point to all the GitLab API job calls.

Nested Class Summary

Nested classes/interfaces inherited from interface org.gitlab4j.api.Constants

Constants.ActionType, Constants.ApplicationScope, Constants.ArchiveFormat, Constants.AutoDevopsDeployStrategy, Constants.BuildGitStrategy, Constants.CommitBuildState, Constants.ContributorOrderBy, Constants.DeploymentOrderBy, Constants.DeploymentStatus, Constants.DeployTokenScope, Constants.Encoding, Constants.EpicOrderBy, Constants.EventScope, Constants.GroupOrderBy, Constants.GroupSearchScope, Constants.ImpersonationState, Constants.IssueOrderBy, Constants.IssueScope, Constants.IssueState, Constants.JobScope, Constants.LineType, Constants.MergeRequestOrderBy, Constants.MergeRequestScope, Constants.MergeRequestSearchIn, Constants.MergeRequestState, Constants.MilestoneState, Constants.PackageOrderBy, Constants.PackageStatus, Constants.PipelineOrderBy, Constants.PipelineScope, Constants.ProjectOrderBy, Constants.ProjectSearchScope, Constants.SearchScope, Constants.SortOrder, Constants.SquashOption, Constants.StateEvent, Constants.TagOrderBy, Constants.TargetType, Constants.TodoAction, Constants.TodoState, Constants.TodoType, Constants.TokenType

Field Summary

Fields inherited from class org.gitlab4j.api.AbstractApi

gitLabApi

Fields inherited from interface org.gitlab4j.api.Constants

NEXT_PAGE_HEADER, PAGE_HEADER, PAGE_PARAM, PER_PAGE, PER_PAGE_PARAM, PREV_PAGE_HEADER, TOTAL_HEADER, TOTAL_PAGES_HEADER

Constructor Summary

Constructors

Constructor	Description
JobApi(GitLabApi gitLabApi)

Method Summary

Modifier and Type	Method	Description
Job	cancelJob(Object projectIdOrPath, Long jobId)	Cancel specified job in a project.
Job	cancleJob(Object projectIdOrPath, Long jobId)	Deprecated. replaced by cancelJob(Object, Long)
void	deleteArtifacts(Object projectIdOrPath, Long jobId)	Delete artifacts of a job.
InputStream	downloadArtifactsFile(Object projectIdOrPath, Long jobId)	Get an InputStream pointing to the job artifacts file for the specified job ID.
File	downloadArtifactsFile(Object projectIdOrPath, Long jobId, File directory)	Download the job artifacts file for the specified job ID.
InputStream	downloadArtifactsFile(Object projectIdOrPath, Long jobId, ArtifactsFile artifactsFile)	Download a single artifact file from within the job's artifacts archive.
File	downloadArtifactsFile(Object projectIdOrPath, Long jobId, ArtifactsFile artifactsFile, File directory)	Download a single artifact file from within the job's artifacts archive.
InputStream	downloadArtifactsFile(Object projectIdOrPath, String ref, String jobName)	Get an InputStream pointing to the artifacts file from the given reference name and job provided the job finished successfully.
File	downloadArtifactsFile(Object projectIdOrPath, String ref, String jobName, File directory)	Download the artifacts file from the given reference name and job provided the job finished successfully.
InputStream	downloadSingleArtifactsFile(Object projectIdOrPath, Long jobId, Path artifactPath)	Download a single artifact file from within the job's artifacts archive.
File	downloadSingleArtifactsFile(Object projectIdOrPath, Long jobId, Path artifactPath, File directory)	Download a single artifact file from within the job's artifacts archive.
Job	eraseJob(Object projectIdOrPath, Long jobId)	Erase specified job in a project.
Job	getJob(Object projectIdOrPath, Long jobId)	Get single job in a project.
List<Job>	getJobs(Object projectIdOrPath)	Get a list of jobs in a project.
Pager<Job>	getJobs(Object projectIdOrPath, int itemsPerPage)	Get a Pager of jobs in a project.
List<Job>	getJobs(Object projectIdOrPath, int page, int perPage)	Get a list of jobs in a project in the specified page range.
List<Job>	getJobs(Object projectIdOrPath, Constants.JobScope scope)	Get a list of jobs in a project.
Pager<Job>	getJobs(Object projectIdOrPath, Constants.JobScope scope, int itemsPerPage)	Get a list of jobs in a project.
List<Job>	getJobsForPipeline(Object projectIdOrPath, long pipelineId)	Get a list of jobs in a pipeline.
Pager<Job>	getJobsForPipeline(Object projectIdOrPath, long pipelineId, int itemsPerPage)	Get a Pager of jobs in a pipeline.
List<Job>	getJobsForPipeline(Object projectIdOrPath, long pipelineId, Constants.JobScope scope)	Get a list of jobs in a pipeline.
Stream<Job>	getJobsStream(Object projectIdOrPath)	Get a Stream of jobs in a project.
Stream<Job>	getJobsStream(Object projectIdOrPath, long pipelineId)	Get a Stream of jobs in a pipeline.
Stream<Job>	getJobsStream(Object projectIdOrPath, Constants.JobScope scope)	Get a Stream of jobs in a project.
Optional<Job>	getOptionalJob(Object projectIdOrPath, Long jobId)	Get single job in a project as an Optional instance.
String	getTrace(Object projectIdOrPath, Long jobId)	Get a trace of a specific job of a project
Job	keepArtifacts(Object projectIdOrPath, Long jobId)	Prevents artifacts from being deleted when expiration is set.
Job	playJob(Object projectIdOrPath, Long jobId)	Play specified job in a project.
Job	retryJob(Object projectIdOrPath, Long jobId)	Retry specified job in a project.

Methods inherited from class org.gitlab4j.api.AbstractApi

addFormParam, addFormParam, delete, delete, get, get, getApiClient, getApiVersion, getDefaultPerPage, getDefaultPerPageParam, getDefaultPerPageParam, getGroupIdOrPath, getLabelIdOrName, getPageQueryParams, getPageQueryParams, getPerPageQueryParam, getProjectIdOrPath, getUserIdOrUsername, getWithAccepts, handle, head, isApiVersion, post, post, post, post, post, put, put, put, putUpload, putUpload, putWithFormData, upload, upload, upload, upload, urlEncode, validate

Methods inherited from class java.lang.Object

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

Constructor Details

JobApi

public JobApi(GitLabApi gitLabApi)

Method Details

getJobs

public List<Job> getJobs(Object projectIdOrPath)
                  throws GitLabApiException

Get a list of jobs in a project.

GitLab Endpoint: GET /projects/:id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

Returns:

a list containing the jobs for the specified project ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobs

public List<Job> getJobs(Object projectIdOrPath,
int page,
int perPage)
                  throws GitLabApiException

Get a list of jobs in a project in the specified page range.

GitLab Endpoint: GET /projects/:id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the jobs for

page - the page to get

perPage - the number of Job instances per page

Returns:

a list containing the jobs for the specified project ID in the specified page range

Throws:

GitLabApiException - if any exception occurs during execution

getJobs

public Pager<Job> getJobs(Object projectIdOrPath,
int itemsPerPage)
                   throws GitLabApiException

Get a Pager of jobs in a project.

GitLab Endpoint: GET /projects/:id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the jobs for

itemsPerPage - the number of Job instances that will be fetched per page

Returns:

a Pager containing the jobs for the specified project ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobsStream

public Stream<Job> getJobsStream(Object projectIdOrPath)
                          throws GitLabApiException

Get a Stream of jobs in a project.

GitLab Endpoint: GET /projects/:id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

Returns:

a Stream containing the jobs for the specified project ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobs

public List<Job> getJobs(Object projectIdOrPath,
Constants.JobScope scope)
                  throws GitLabApiException

Get a list of jobs in a project.

GitLab Endpoint: GET /projects/:id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the jobs for

scope - the scope of jobs, one of: CREATED, PENDING, RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL

Returns:

a list containing the jobs for the specified project ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobs

public Pager<Job> getJobs(Object projectIdOrPath,
Constants.JobScope scope,
int itemsPerPage)
                   throws GitLabApiException

Get a list of jobs in a project.

GitLab Endpoint: GET /projects/:id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the jobs for

scope - the scope of jobs, one of: CREATED, PENDING, RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL

itemsPerPage - the number of Job instances that will be fetched per page

Returns:

a list containing the jobs for the specified project ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobsStream

public Stream<Job> getJobsStream(Object projectIdOrPath,
Constants.JobScope scope)
                          throws GitLabApiException

Get a Stream of jobs in a project.

GitLab Endpoint: GET /projects/:id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the jobs for

scope - the scope of jobs, one of: CREATED, PENDING, RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL

Returns:

a Stream containing the jobs for the specified project ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobsForPipeline

public List<Job> getJobsForPipeline(Object projectIdOrPath,
long pipelineId)
                             throws GitLabApiException

Get a list of jobs in a pipeline.

GitLab Endpoint: GET /projects/:id/pipelines/:pipeline_id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the pipelines for

pipelineId - the pipeline ID to get the list of jobs for

Returns:

a list containing the jobs for the specified project ID and pipeline ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobsForPipeline

public List<Job> getJobsForPipeline(Object projectIdOrPath,
long pipelineId,
Constants.JobScope scope)
                             throws GitLabApiException

Get a list of jobs in a pipeline.

GitLab Endpoint: GET /projects/:id/pipelines/:pipeline_id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the pipelines for

pipelineId - the pipeline ID to get the list of jobs for

scope - the scope of jobs, one of: CREATED, PENDING, RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL

Returns:

a list containing the jobs for the specified project ID and pipeline ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobsForPipeline

public Pager<Job> getJobsForPipeline(Object projectIdOrPath,
long pipelineId,
int itemsPerPage)
                              throws GitLabApiException

Get a Pager of jobs in a pipeline.

GitLab Endpoint: GET /projects/:id/pipelines/:pipeline_id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the pipelines for

pipelineId - the pipeline ID to get the list of jobs for

itemsPerPage - the number of Job instances that will be fetched per page

Returns:

a list containing the jobs for the specified project ID and pipeline ID

Throws:

GitLabApiException - if any exception occurs during execution

getJobsStream

public Stream<Job> getJobsStream(Object projectIdOrPath,
long pipelineId)
                          throws GitLabApiException

Get a Stream of jobs in a pipeline.

GitLab Endpoint: GET /projects/:id/pipelines/:pipeline_id/jobs

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

pipelineId - the pipeline ID to get the list of jobs for

Returns:

a Stream containing the jobs for the specified project ID

Throws:

GitLabApiException - if any exception occurs during execution

getJob

public Job getJob(Object projectIdOrPath,
Long jobId)
           throws GitLabApiException

Get single job in a project.

GitLab Endpoint: GET /projects/:id/jobs/:job_id

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the job for

jobId - the job ID to get

Returns:

a single job for the specified project ID

Throws:

GitLabApiException - if any exception occurs during execution

getOptionalJob

public Optional<Job> getOptionalJob(Object projectIdOrPath,
Long jobId)

Get single job in a project as an Optional instance.

GitLab Endpoint: GET /projects/:id/jobs/:job_id

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the job for

jobId - the job ID to get

Returns:

a single job for the specified project ID as an Optional intance

downloadArtifactsFile

public File downloadArtifactsFile(Object projectIdOrPath,
String ref,
String jobName,
File directory)
                           throws GitLabApiException

Download the artifacts file from the given reference name and job provided the job finished successfully. The file will be saved to the specified directory. If the file already exists in the directory it will be overwritten.

GitLab Endpoint: GET /projects/:id/jobs/artifacts/:ref_name/download?job=name

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

ref - the ref from a repository

jobName - the name of the job to download the artifacts for

directory - the File instance of the directory to save the file to, if null will use "java.io.tmpdir"

Returns:

a File instance pointing to the download of the specified artifacts file

Throws:

GitLabApiException - if any exception occurs

downloadArtifactsFile

public InputStream downloadArtifactsFile(Object projectIdOrPath,
String ref,
String jobName)
                                  throws GitLabApiException

Get an InputStream pointing to the artifacts file from the given reference name and job provided the job finished successfully. The file will be saved to the specified directory. If the file already exists in the directory it will be overwritten.

GitLab Endpoint: GET /projects/:id/jobs/artifacts/:ref_name/download?job=name

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

ref - the ref from a repository

jobName - the name of the job to download the artifacts for

Returns:

an InputStream to read the specified artifacts file from

Throws:

GitLabApiException - if any exception occurs

downloadArtifactsFile

public File downloadArtifactsFile(Object projectIdOrPath,
Long jobId,
File directory)
                           throws GitLabApiException

Download the job artifacts file for the specified job ID. The artifacts file will be saved in the specified directory with the following name pattern: job-{jobid}-artifacts.zip. If the file already exists in the directory it will be overwritten.

GitLab Endpoint: GET /projects/:id/jobs/:job_id/artifacts

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the job ID to get the artifacts for

directory - the File instance of the directory to save the file to, if null will use "java.io.tmpdir"

Returns:

a File instance pointing to the download of the specified job artifacts file

Throws:

GitLabApiException - if any exception occurs

downloadArtifactsFile

public InputStream downloadArtifactsFile(Object projectIdOrPath,
Long jobId)
                                  throws GitLabApiException

Get an InputStream pointing to the job artifacts file for the specified job ID.

GitLab Endpoint: GET /projects/:id/jobs/:job_id/artifacts

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the job ID to get the artifacts for

Returns:

an InputStream to read the specified job artifacts file

Throws:

GitLabApiException - if any exception occurs

downloadArtifactsFile

public File downloadArtifactsFile(Object projectIdOrPath,
Long jobId,
ArtifactsFile artifactsFile,
File directory)
                           throws GitLabApiException

Download a single artifact file from within the job's artifacts archive. Only a single file is going to be extracted from the archive and streamed to a client.

GitLab Endpoint: GET /projects/:id/jobs/:job_id/artifacts/*artifact_path

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the unique job identifier

artifactsFile - an ArtifactsFile instance for the artifact to download

directory - the File instance of the directory to save the file to, if null will use "java.io.tmpdir"

Returns:

a File instance pointing to the download of the specified artifacts file

Throws:

GitLabApiException - if any exception occurs

downloadArtifactsFile

public InputStream downloadArtifactsFile(Object projectIdOrPath,
Long jobId,
ArtifactsFile artifactsFile)
                                  throws GitLabApiException

Download a single artifact file from within the job's artifacts archive. Only a single file is going to be extracted from the archive and streamed to a client.

GitLab Endpoint: GET /projects/:id/jobs/:job_id/artifacts/*artifact_path

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the unique job identifier

artifactsFile - an ArtifactsFile instance for the artifact to download

Returns:

an InputStream to read the specified artifacts file from

Throws:

GitLabApiException - if any exception occurs

downloadSingleArtifactsFile

public File downloadSingleArtifactsFile(Object projectIdOrPath,
Long jobId,
Path artifactPath,
File directory)
                                 throws GitLabApiException

Download a single artifact file from within the job's artifacts archive. Only a single file is going to be extracted from the archive and streamed to a client.

GitLab Endpoint: GET /projects/:id/jobs/:job_id/artifacts/*artifact_path

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the unique job identifier

artifactPath - the Path to a file inside the artifacts archive

directory - the File instance of the directory to save the file to, if null will use "java.io.tmpdir"

Returns:

a File instance pointing to the download of the specified artifacts file

Throws:

GitLabApiException - if any exception occurs

downloadSingleArtifactsFile

public InputStream downloadSingleArtifactsFile(Object projectIdOrPath,
Long jobId,
Path artifactPath)
                                        throws GitLabApiException

Download a single artifact file from within the job's artifacts archive. Only a single file is going to be extracted from the archive and streamed to a client.

GitLab Endpoint: GET /projects/:id/jobs/:job_id/artifacts/*artifact_path

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the unique job identifier

artifactPath - the Path to a file inside the artifacts archive

Returns:

an InputStream to read the specified artifacts file from

Throws:

GitLabApiException - if any exception occurs

getTrace

public String getTrace(Object projectIdOrPath,
Long jobId)
                throws GitLabApiException

Get a trace of a specific job of a project

GitLab Endpoint: GET /projects/:id/jobs/:id/trace

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path to get the specified job's trace for

jobId - the job ID to get the trace for

Returns:

a String containing the specified job's trace

Throws:

GitLabApiException - if any exception occurs during execution

cancleJob

@Deprecated
public Job cancleJob(Object projectIdOrPath,
Long jobId)
              throws GitLabApiException

Deprecated.

replaced by cancelJob(Object, Long)

Cancel specified job in a project.

GitLab Endpoint: POST /projects/:id/jobs/:job_id/cancel

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the ID to cancel job

Returns:

job instance which just canceled

Throws:

GitLabApiException - if any exception occurs during execution

cancelJob

public Job cancelJob(Object projectIdOrPath,
Long jobId)
              throws GitLabApiException

Cancel specified job in a project.

GitLab Endpoint: POST /projects/:id/jobs/:job_id/cancel

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the ID to cancel job

Returns:

job instance which just canceled

Throws:

GitLabApiException - if any exception occurs during execution

retryJob

public Job retryJob(Object projectIdOrPath,
Long jobId)
             throws GitLabApiException

Retry specified job in a project.

GitLab Endpoint: POST /projects/:id/jobs/:job_id/retry

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the ID to retry job

Returns:

job instance which just retried

Throws:

GitLabApiException - if any exception occurs during execution

eraseJob

public Job eraseJob(Object projectIdOrPath,
Long jobId)
             throws GitLabApiException

Erase specified job in a project.

GitLab Endpoint: POST /projects/:id/jobs/:job_id/erase

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the ID to erase job

Returns:

job instance which just erased

Throws:

GitLabApiException - if any exception occurs during execution

playJob

public Job playJob(Object projectIdOrPath,
Long jobId)
            throws GitLabApiException

Play specified job in a project.

GitLab Endpoint: POST /projects/:id/jobs/:job_id/play

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the ID to play job

Returns:

job instance which just played

Throws:

GitLabApiException - if any exception occurs during execution

keepArtifacts

public Job keepArtifacts(Object projectIdOrPath,
Long jobId)
                  throws GitLabApiException

Prevents artifacts from being deleted when expiration is set.

GitLab Endpoint: POST /projects/:id/jobs/:job_id/keep

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the ID to keep artifacts for

Returns:

the Job instance that was just modified

Throws:

GitLabApiException - if any exception occurs during execution

deleteArtifacts

public void deleteArtifacts(Object projectIdOrPath,
Long jobId)
                     throws GitLabApiException

Delete artifacts of a job.

GitLab Endpoint: DELETE /projects/:id/jobs/:job_id/artifacts

Parameters:

projectIdOrPath - id, path of the project, or a Project instance holding the project ID or path

jobId - the ID to delete artifacts for

Throws:

GitLabApiException - if any exception occurs during execution