Task/extract interfaces (#1738)

https://issues.jenkins-ci.org/browse/JENKINS-51463

Extract some common java interfaces and create initial TypeScript definitions for them

blueocean-core-js/src/js/Model.ts

@@ -0,0 +1,157 @@
+/**
+ Model interfaces
+
+ TODO: Hand-written for now, needs to be generated from Java sources with docstrings copied over etc
+ */
+
+namespace Model {
+    export interface WithClass {
+        _class: string;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueRun
+    export enum RunState {
+        QUEUED = 'QUEUED',
+        RUNNING = 'RUNNING',
+        PAUSED = 'PAUSED',
+        SKIPPED = 'SKIPPED',
+        NOT_BUILT = 'NOT_BUILT',
+        FINISHED = 'FINISHED',
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueRun
+    export enum RunResult {
+        SUCCESS = 'SUCCESS',
+        UNSTABLE = 'UNSTABLE',
+        FAILURE = 'FAILURE',
+        NOT_BUILT = 'NOT_BUILT',
+        UNKNOWN = 'UNKNOWN',
+        ABORTED = 'ABORTED',
+    }
+
+    // From io.jenkins.blueocean.rest.hal.Link
+    export interface Link {
+        href: string;
+    }
+
+    // From io.jenkins.blueocean.rest.Reachable
+    export interface Reachable {
+        link: Link;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueActionProxy
+    export interface Action extends WithClass {
+        urlName: string;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BluePipelineItem
+    export interface PipelineItem extends Reachable, WithClass {
+        organization: string;
+        name: string;
+        displayName: string;
+        fullName: string;
+        fullDisplayName: string;
+        actions: Array<Action>;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueRunnableItem
+    export interface RunnableItem extends PipelineItem {
+        weatherScore: number;
+        latestRun: Run | null;
+        estimatedDurationInMillis: number;
+        parameters: Array<any>;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueContainerItem
+    export interface ContainerItem extends PipelineItem {
+        numberOfFolders: number;
+        numberOfPipelines: number;
+        icon?: Reachable;
+        pipelineFolderNames: Array<string>;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueMultiBranchItem
+    export interface MultiBranchItem extends ContainerItem {
+        totalNumberOfBranches: number;
+        numberOfFailingBranches: number;
+        numberOfSuccessfulBranches: number;
+        totalNumberOfPullRequests: number;
+        numberOfFailingPullRequests: number;
+        numberOfSuccessfulPullRequests: number;
+        branchNames: Array<string>;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueItemRun
+    export interface Run extends Reachable, WithClass {
+        organization: string;
+        id: string;
+        pipeline: string;
+        name: string;
+        description: string;
+        changeSet: Array<Change>;
+        startTime: string;
+        enQueueTime: string;
+        endTime: string;
+        durationInMillis: number;
+        estimatedDurationInMillis: number;
+        state: RunState;
+        result: RunResult;
+        runSummary: string;
+        type: string;
+        artifactsZipFile: string;
+        actions: Array<Action>;
+        testSummary?: TestSummary;
+        causes: Array<RunCause>;
+        causeOfBlockage: string;
+        replayable: boolean;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueChangeSetEntry
+    export interface Change extends Reachable, WithClass {
+        author: User;
+        commitId: string;
+        timestamp: string;
+        msg: string;
+        affectedPaths: Array<string>;
+        url: string;
+        issues?: Array<Issue>;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueTestSummary
+    export interface TestSummary {
+        total: number;
+        skipped: number;
+        failed: number;
+        passed: number;
+        fixed: number;
+        existingFailed: number;
+        regressions: number;
+    }
+
+    // No nice interface for this, and no impl fields marked @Exported
+    export interface RunCause {
+        shortDescription: string;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueUser
+    export interface User extends Reachable, WithClass {
+        id: string;
+        fullName: string;
+        email?: string;
+        permission: UserPermission;
+        avatar: string;
+    }
+
+    // From io.jenkins.blueocean.rest.model.BlueIssue
+    export interface Issue {
+        id: string;
+        url: string;
+    }
+
+    // From: io.jenkins.blueocean.rest.model.BlueUserPermission
+    export interface UserPermission {
+        administrator: boolean;
+        pipeline: Map<string, boolean>;
+        credential: Map<string, boolean>;
+    }
+}

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BlueContainerItem.java

@@ -0,0 +1,57 @@
+package io.jenkins.blueocean.rest.model;
+
+import io.jenkins.blueocean.rest.annotation.Capability;
+import org.kohsuke.stapler.export.Exported;
+
+import static io.jenkins.blueocean.rest.model.KnownCapabilities.BLUE_PIPELINE_FOLDER;
+
+/**
+ * Common interface for items in the pipeline "namespace" that aggregate or contain other pipeline items, such as team
+ * or organization folders, or the collection of pipelines that forms a BlueMultiBranchItem.
+ * <p>
+ * These may or may not be also runnable, so we want to keep that facet in BlueRunnableItem and not here.
+ */
+@Capability(BLUE_PIPELINE_FOLDER)
+public interface BlueContainerItem /* extends BluePipelineItem */ {
+    /**
+     * @return Gives pipeline container
+     */
+    BluePipelineContainer getPipelines();
+
+    /**
+     * Gets nested BluePipeline inside the BluePipelineFolder
+     * <p>
+     * For example for: /pipelines/folder1/pipelines/folder2/pipelines/p1, call sequence  will be:
+     *
+     * <ul>
+     * <li>getPipelines().get("folder1")</li>
+     * <li>getPipelines().get(folder2)</li>
+     * <li>getDynamics(p1)</li>
+     * </ul>
+     *
+     * @param name name of pipeline
+     * @return a {@link BluePipeline}
+     */
+    BluePipeline getDynamic(String name);
+
+    /**
+     * @return Number of folders in this folder
+     */
+    @Exported(name = "numberOfFolders")
+    Integer getNumberOfFolders();
+
+    /**
+     * @return Number of pipelines in this folder. Pipeline is any buildable type.
+     */
+    @Exported(name = "numberOfPipelines")
+    Integer getNumberOfPipelines();
+
+    @Exported(skipNull = true)
+    BlueIcon getIcon();
+
+    /**
+     * Returns pipeline folder names present in this folder.
+     */
+    @Exported(name = "pipelineFolderNames")
+    Iterable<String> getPipelineFolderNames();
+}

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BlueItemRun.java

@@ -0,0 +1,164 @@
+package io.jenkins.blueocean.rest.model;
+
+import io.jenkins.blueocean.rest.Navigable;
+import io.jenkins.blueocean.rest.annotation.Capability;
+import org.kohsuke.stapler.export.Exported;
+
+import javax.annotation.Nonnull;
+import java.util.Collection;
+
+import static io.jenkins.blueocean.rest.model.KnownCapabilities.BLUE_RUN;
+
+/**
+ * Common interface for job run details
+ */
+@Capability(BLUE_RUN)
+public interface BlueItemRun {
+
+    /**
+     * @return name of the organization
+     */
+    @Exported(name = "organization")
+    String getOrganization();
+
+    /**
+     * @return {@link BlueRun} id - unique within a pipeline
+     */
+    @Exported(name = "id")
+    String getId();
+
+    /**
+     * @return Pipeline name - unique within an organization
+     */
+    @Exported(name = "pipeline")
+    String getPipeline();
+
+    @Exported(name = "name")
+    String getName();
+
+    @Exported(name = "description")
+    String getDescription();
+
+    /**
+     * @return Gives change set of a run
+     */
+    @Exported(inline = true)
+    @Nonnull
+    Container<BlueChangeSetEntry> getChangeSet();
+
+    /**
+     * @return run start time
+     */
+    @Exported(name = "startTime")
+    String getStartTimeString();
+
+    /**
+     * Enque time
+     */
+    @Exported(name = "enQueueTime")
+    String getEnQueueTimeString();
+
+    /**
+     * Run end time
+     */
+    @Exported(name = "endTime")
+    String getEndTimeString();
+
+    /**
+     * @return Build duration in milli seconds
+     */
+    @Exported(name = "durationInMillis")
+    Long getDurationInMillis();
+
+    /**
+     * @return Estimated Build duration in milli seconds
+     */
+    @Exported(name = "estimatedDurationInMillis")
+    Long getEstimatedDurtionInMillis();
+
+    /**
+     * @return The state of the run
+     */
+    @Exported(name = "state")
+    BlueRun.BlueRunState getStateObj();
+
+    /**
+     * @return The result state of the job (e.g unstable)
+     */
+    @Exported(name = "result")
+    BlueRun.BlueRunResult getResult();
+
+    /**
+     * @return Build summary
+     */
+    @Exported(name = "runSummary")
+    String getRunSummary();
+
+    /**
+     * @return Type of Run. Type name to be Jenkins Run.getClass().getSimpleName()
+     */
+    @Exported(name = "type")
+    String getType();
+
+    /**
+     * @return Uri of artifacts zip file.
+     */
+    @Exported
+    String getArtifactsZipFile();
+
+    /**
+     * @return Run artifacts
+     */
+    @Navigable
+    BlueArtifactContainer getArtifacts();
+
+    /**
+     * @return Gives Actions associated with this Run, if requested via tree
+     */
+    @Navigable
+    @Exported(name = "actions", inline = true)
+    Collection<BlueActionProxy> getActions();
+
+    /**
+     * @return Gives tests in this run
+     */
+    @Navigable
+    BlueTestResultContainer getTests();
+
+    /**
+     * @return Gives the test summary for this run
+     */
+    @Exported(name = "testSummary", inline = true, skipNull = true)
+    BlueTestSummary getTestSummary();
+
+    /**
+     * @return Instance of stapler aware instance that can do the following:
+     * <p></p><ul>
+     * <li>Must be able to process start query parameter. 'start' parameter is the byte offset in the actual log file</li>
+     * <li>Must produce following HTTP headers in the response</li>
+     * <li>X-Text-Size  It is the byte offset of the raw log file client should use in the next request as value of start query parameter.</li>
+     * <li>X-More-Data  If  its true, then client should repeat the request after some delay. In the repeated request it should use
+     * X-TEXT-SIZE header value with *start* query parameter.</li>
+     * </ul>
+     */
+    @Navigable
+    Object getLog();
+
+    /**
+     * @return cause of the run being created
+     */
+    @Exported(name = "causes", inline = true)
+    Collection<BlueRun.BlueCause> getCauses();
+
+    /**
+     * @return cause of what is blocking this run
+     */
+    @Exported(name = "causeOfBlockage")
+    String getCauseOfBlockage();
+
+    /**
+     * @return if the run will allow a replay
+     */
+    @Exported(name = "replayable")
+    boolean isReplayable();
+}

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BlueManagedSource.java

@@ -0,0 +1,11 @@
+package io.jenkins.blueocean.rest.model;
+
+import io.jenkins.blueocean.rest.Navigable;
+
+public interface BlueManagedSource /* extends BluePipelineItem */ {
+    /**
+     * @return Gives scm resource attached to this pipeline
+     */
+    @Navigable
+    BluePipelineScm getScm();
+}

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BlueMultiBranchItem.java

@@ -0,0 +1,66 @@
+package io.jenkins.blueocean.rest.model;
+
+import io.jenkins.blueocean.rest.annotation.Capability;
+import org.kohsuke.stapler.export.Exported;
+
+import java.util.Collection;
+
+import static io.jenkins.blueocean.rest.model.KnownCapabilities.BLUE_MULTI_BRANCH_PIPELINE;
+
+/**
+ * Common interface for container items that exist to group multiple branches of the same source project.
+ *
+ * Should not be tied to a specific repository kind / scm vendor etc.
+ */
+@Capability(BLUE_MULTI_BRANCH_PIPELINE)
+public interface BlueMultiBranchItem /* extends BlueContainerItem */ {
+
+    // TODO: Replace all the ints with Integers etc
+
+    /**
+     * @return total number of branches
+     */
+    @Exported(name = "totalNumberOfBranches")
+    int getTotalNumberOfBranches();
+
+    /**
+     * @return total number of failing branches
+     */
+    @Exported(name = "numberOfFailingBranches")
+    int getNumberOfFailingBranches();
+
+    /**
+     * @return total number of successful branches
+     */
+    @Exported(name = "numberOfSuccessfulBranches")
+    int getNumberOfSuccessfulBranches();
+
+    /**
+     * @return total number of pull requests
+     */
+    @Exported(name = "totalNumberOfPullRequests")
+    int getTotalNumberOfPullRequests();
+
+    /**
+     * @return total number of pull requests
+     */
+    @Exported(name = "numberOfFailingPullRequests")
+    int getNumberOfFailingPullRequests();
+
+    /**
+     * @return total number of pull requests
+     */
+    @Exported(name = "numberOfSuccessfulPullRequests")
+    int getNumberOfSuccessfulPullRequests();
+
+    /**
+     * @return Gives {@link BluePipelineContainer}
+     */
+    BluePipelineContainer getBranches();
+
+    /**
+     * @return Gives array of branch names
+     */
+    @Exported(name = "branchNames")
+    Collection<String> getBranchNames();
+}

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BlueMultiBranchPipeline.java

@@ -18,7 +18,7 @@ import static io.jenkins.blueocean.rest.model.KnownCapabilities.BLUE_MULTI_BRANC
  * @author Vivek Pandey
  */
 @Capability(BLUE_MULTI_BRANCH_PIPELINE)
-public abstract class BlueMultiBranchPipeline extends BluePipelineFolder{
+public abstract class BlueMultiBranchPipeline extends BluePipelineFolder implements BlueMultiBranchItem {
     public static final String TOTAL_NUMBER_OF_BRANCHES="totalNumberOfBranches";
     public static final String NUMBER_OF_FAILING_BRANCHES="numberOfFailingBranches";
     public static final String NUMBER_OF_SUCCESSFULT_BRANCHES="numberOfSuccessfulBranches";

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BluePipeline.java

@@ -21,7 +21,7 @@ import static io.jenkins.blueocean.rest.model.KnownCapabilities.BLUE_PIPELINE;
  * @author Vivek Pandey
  */
 @Capability(BLUE_PIPELINE)
-public abstract class BluePipeline extends Resource {
+public abstract class BluePipeline extends Resource implements BluePipelineItem, BlueRunnableItem, BlueManagedSource {
     public static final String ORGANIZATION="organization";
     public static final String NAME="name";
     public static final String DISPLAY_NAME="displayName";

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BluePipelineFolder.java

@@ -19,7 +19,7 @@ import static io.jenkins.blueocean.rest.model.KnownCapabilities.JENKINS_ABSTRACT
  * @see BluePipelineContainer
  */
 @Capability({BLUE_PIPELINE_FOLDER, JENKINS_ABSTRACT_FOLDER})
-public abstract class BluePipelineFolder extends BluePipeline {
+public abstract class BluePipelineFolder extends BluePipeline implements BlueContainerItem {
 
     private static final String NUMBER_OF_PIPELINES = "numberOfPipelines";
     private static final String NUMBER_OF_FOLDERS = "numberOfFolders";

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BluePipelineItem.java

@@ -0,0 +1,64 @@
+package io.jenkins.blueocean.rest.model;
+
+import io.jenkins.blueocean.rest.Navigable;
+import io.jenkins.blueocean.rest.Reachable;
+import io.jenkins.blueocean.rest.annotation.Capability;
+import org.kohsuke.stapler.export.Exported;
+
+import javax.annotation.Nonnull;
+import java.util.Collection;
+
+import static io.jenkins.blueocean.rest.model.KnownCapabilities.BLUE_PIPELINE;
+
+/**
+ * Minimal interface for all Blue Ocean items that live in the "pipeline namespace"
+ * <p>
+ * This includes various kinds of jobs that can be run, but also things that exist only as containers like folders and
+ * multibranch parents, and as such doesn't contain any references to runs, build times, etc.
+ */
+@Capability(BLUE_PIPELINE)
+public interface BluePipelineItem extends Reachable {
+    /**
+     * @return the organization that owns this item
+     */
+    @Nonnull
+    BlueOrganization getOrganization();
+
+    /**
+     * @return name of the organization that owns this item
+     */
+    @Exported(name = "organization")
+    String getOrganizationName();
+
+    /**
+     * @return name of the pipeline
+     */
+    @Exported(name = "name")
+    String getName();
+
+    /**
+     * @return human readable name of this pipeline
+     */
+    @Exported(name = "displayName")
+    String getDisplayName();
+
+    /**
+     * @return Includes parent folders names if any. For example folder1/folder2/p1
+     */
+    @Exported(name = "fullName")
+    String getFullName();
+
+    /**
+     * @return Includes display names of parent folders if any. For example folder1/myFolder2/p1
+     */
+    @Exported(name = "fullDisplayName")
+    String getFullDisplayName();
+
+    /**
+     * @return Gives Actions associated with this Run
+     */
+    @Navigable
+    @Exported(name = "actions", inline = true)
+    Collection<BlueActionProxy> getActions();
+
+}

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BlueRun.java

@@ -25,7 +25,7 @@ import static io.jenkins.blueocean.rest.model.KnownCapabilities.BLUE_RUN;
  * @author Vivek Pandey
  */
 @Capability(BLUE_RUN)
-public abstract class BlueRun extends Resource {
+public abstract class BlueRun extends Resource implements BlueItemRun {
     public static final String ORGANIZATION="organization";
     public static final String ID="id";
     public static final String PIPELINE="pipeline";

blueocean-rest/src/main/java/io/jenkins/blueocean/rest/model/BlueRunnableItem.java

@@ -0,0 +1,54 @@
+package io.jenkins.blueocean.rest.model;
+
+import io.jenkins.blueocean.rest.Navigable;
+import org.kohsuke.stapler.export.Exported;
+
+import java.util.List;
+
+/**
+ * Common interface to be implemented by pipeline items that are runnable and hence have expected run-times, a
+ * run history, etc.
+ */
+public interface BlueRunnableItem /* extends BluePipelineItem */ {
+    /**
+     * @return weather health score percentile
+     */
+    @Exported(name = "weatherScore")
+    Integer getWeatherScore();
+
+    /**
+     * @return The Latest Run for the branch
+     */
+    @Exported(name = "latestRun", inline = true)
+    BlueRun getLatestRun();
+
+    /**
+     * @return Estimated duration based on last pipeline runs. -1 is returned if there is no estimate available.
+     */
+    @Exported(name = "estimatedDurationInMillis")
+    Long getEstimatedDurationInMillis();
+
+    /**
+     * @return Gives Runs in this pipeline
+     */
+    @Navigable
+    BlueRunContainer getRuns();
+
+    /**
+     * @return Gives {@link BlueQueueContainer}
+     */
+    @Navigable
+    BlueQueueContainer getQueue();
+
+    /**
+     * List of build parameters
+     */
+    @Exported(name = "parameters", inline = true)
+    List<Object> getParameters();
+
+    /**
+     * @return trend data related to this pipeline
+     */
+    @Navigable
+    BlueTrendContainer getTrends();
+}