Package org.gitlab4j.api

Class 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.

    • Constructor Detail

      • JobApi

        public JobApi​(GitLabApi gitLabApi)

    • Method Detail

      • getJobs

        public java.util.List<Job> getJobs​(java.lang.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 java.util.List<Job> getJobs​(java.lang.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​(java.lang.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 java.util.stream.Stream<Job> getJobsStream​(java.lang.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 java.util.List<Job> getJobs​(java.lang.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​(java.lang.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 java.util.stream.Stream<Job> getJobsStream​(java.lang.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 java.util.List<Job> getJobsForPipeline​(java.lang.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 java.util.List<Job> getJobsForPipeline​(java.lang.Object projectIdOrPath,
                                              long pipelineId,
                                              java.lang.Boolean includeRetried)
                                       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
        includeRetried - Include retried jobs in the response
        Returns:
        a list containing the jobs for the specified project ID and pipeline ID
        Throws:
        GitLabApiException - if any exception occurs during execution

      • getJobsForPipeline

        public java.util.List<Job> getJobsForPipeline​(java.lang.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 java.util.List<Job> getJobsForPipeline​(java.lang.Object projectIdOrPath,
                                              long pipelineId,
                                              Constants.JobScope scope,
                                              java.lang.Boolean includeRetried)
                                       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
        includeRetried - Include retried jobs in the response
        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​(java.lang.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

      • getJobsForPipeline

        public Pager<Job> getJobsForPipeline​(java.lang.Object projectIdOrPath,
                                     long pipelineId,
                                     int itemsPerPage,
                                     java.lang.Boolean includeRetried)
                              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
        includeRetried - Include retried jobs in the response
        Returns:
        a list containing the jobs for the specified project ID and pipeline ID
        Throws:
        GitLabApiException - if any exception occurs during execution

      • getJobsStream

        public java.util.stream.Stream<Job> getJobsStream​(java.lang.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

      • getJobsStream

        public java.util.stream.Stream<Job> getJobsStream​(java.lang.Object projectIdOrPath,
                                                  long pipelineId,
                                                  java.lang.Boolean includeRetried)
                                           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
        includeRetried - Include retried jobs in the response
        Returns:
        a Stream containing the jobs for the specified project ID
        Throws:
        GitLabApiException - if any exception occurs during execution

      • getJob

        public Job getJob​(java.lang.Object projectIdOrPath,
                  java.lang.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 java.util.Optional<Job> getOptionalJob​(java.lang.Object projectIdOrPath,
                                              java.lang.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 java.io.File downloadArtifactsFile​(java.lang.Object projectIdOrPath,
                                          java.lang.String ref,
                                          java.lang.String jobName,
                                          java.io.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 java.io.InputStream downloadArtifactsFile​(java.lang.Object projectIdOrPath,
                                                 java.lang.String ref,
                                                 java.lang.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 java.io.File downloadArtifactsFile​(java.lang.Object projectIdOrPath,
                                          java.lang.Long jobId,
                                          java.io.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 java.io.InputStream downloadArtifactsFile​(java.lang.Object projectIdOrPath,
                                                 java.lang.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 java.io.File downloadArtifactsFile​(java.lang.Object projectIdOrPath,
                                          java.lang.Long jobId,
                                          ArtifactsFile artifactsFile,
                                          java.io.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 java.io.InputStream downloadArtifactsFile​(java.lang.Object projectIdOrPath,
                                                 java.lang.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 java.io.File downloadSingleArtifactsFile​(java.lang.Object projectIdOrPath,
                                                java.lang.Long jobId,
                                                java.lang.String artifactPath,
                                                java.io.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 java.io.InputStream downloadSingleArtifactsFile​(java.lang.Object projectIdOrPath,
                                                       java.lang.Long jobId,
                                                       java.lang.String 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 java.lang.String getTrace​(java.lang.Object projectIdOrPath,
                                 java.lang.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​(java.lang.Object projectIdOrPath,
                     java.lang.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​(java.lang.Object projectIdOrPath,
                     java.lang.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​(java.lang.Object projectIdOrPath,
                    java.lang.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​(java.lang.Object projectIdOrPath,
                    java.lang.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​(java.lang.Object projectIdOrPath,
                   java.lang.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

      • playJob

        public Job playJob​(java.lang.Object projectIdOrPath,
                   java.lang.Long jobId,
                   JobAttributes jobAttributes)
            throws GitLabApiException
        Play specified job with parameters 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
        jobAttributes - attributes for the played job
        Returns:
        job instance which just played
        Throws:
        GitLabApiException - if any exception occurs during execution

      • keepArtifacts

        public Job keepArtifacts​(java.lang.Object projectIdOrPath,
                         java.lang.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​(java.lang.Object projectIdOrPath,
                            java.lang.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