/*******************************************************************************
*
* Copyright (c) 2011 Oracle Corporation.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
*
* Nikita Levyankov
*
*******************************************************************************/
package org.eclipse.hudson.api.model;
import hudson.PermalinkList;
import hudson.model.BallColor;
import hudson.model.BuildTimelineWidget;
import hudson.model.Fingerprint;
import hudson.model.HealthReport;
import hudson.model.Item;
import hudson.model.Job;
import hudson.model.JobProperty;
import hudson.model.JobPropertyDescriptor;
import hudson.model.Queue;
import hudson.model.Result;
import hudson.model.Run;
import hudson.tasks.LogRotator;
import org.eclipse.hudson.graph.Graph;
import hudson.util.RunList;
import hudson.widgets.Widget;
import java.io.IOException;
import java.util.List;
import java.util.Map;
import java.util.SortedMap;
/**
* Interface that represents Job.
* <p/>
* Date: 9/15/11
*
* @author Nikita Levyankov
*/
public interface IJob<JobT extends Job> extends Item {
/**
* @return whether the name of this job can be changed by user.
*/
boolean isNameEditable();
/**
* Returns the log rotator for this job, or null if none.
*
* @return {@link LogRotator} instance.
*/
LogRotator getLogRotator();
/**
* Sets log rotator.
*
* @param logRotator log rotator.
*/
void setLogRotator(LogRotator logRotator);
/**
* @return true if this instance supports log rotation configuration.
*/
boolean supportsLogRotator();
/**
* Gets all the job properties configured for this job.
*
* @return Map of properties.
*/
Map<JobPropertyDescriptor, JobProperty<? super JobT>> getProperties();
/**
* @return List of all {@link JobProperty}.
*/
List<JobProperty<? super JobT>> getAllProperties();
/**
* @return true if the build is in the queue.
*/
boolean isInQueue();
/**
* @return queue item If this job is in the build queue.
*/
Queue.Item getQueueItem();
/**
* @return true if a build of this project is in progress.
*/
boolean isBuilding();
/**
* @return flag, which shows whether all the build logs of dependency
* components will be kept.
*/
boolean isKeepDependencies();
/**
* Allocates a new buildCommand number.
*
* @return new build number.
* @throws IOException if any.
*/
int assignBuildNumber() throws IOException;
/**
* @return the next build number.
*/
int getNextBuildNumber();
/**
* Programatically updates the next build number.
* <p/>
* <
* p/> Much of Hudson assumes that the build number is unique and monotonic,
* so this method can only accept a new value that's bigger than
* {@link #getLastBuild()} returns. Otherwise it'll be no-op.
*
* @param next build number to set.
* @throws IOException if any.
* @since 1.199 (before that, this method was package private.)
*/
void updateNextBuildNumber(int next) throws IOException;
/**
* Perform log rotation.
*
* @throws IOException if any.
* @throws InterruptedException if any.
*/
void logRotate() throws IOException, InterruptedException;
/**
* @return {@link hudson.widgets.HistoryWidget}
*/
List<Widget> getWidgets();
/**
* @return true if we should display "build now" icon
*/
boolean isBuildable();
/**
* Gets all the {@link hudson.model.PermalinkProjectAction.Permalink}s
* defined for this job.
*
* @return never null
*/
PermalinkList getPermalinks();
/**
* Gets the read-only view of all the builds.
*
* @return never null. The first entry is the latest build.
*/
<RunT extends Run> RunList<RunT> getBuilds();
/**
* @param rs target rangeSet.
* @return all the {@link Run}s whose build numbers matches the given
* {@link Fingerprint.RangeSet}.
*/
<RunT extends Run> List<RunT> getBuilds(Fingerprint.RangeSet rs);
/**
* @return all the builds in a map.
*/
<RunT extends Run> SortedMap<Integer, RunT> getBuildsAsMap();
/**
* @param n The build number.
* @return null if no such build exists.
* @see Run#getNumber()
*/
<RunT extends Run> RunT getBuildByNumber(int n);
/**
* Gets the youngest build #m that satisfies <tt>n<=m</tt>.
* <p/>
* This is useful when you'd like to fetch a build but the exact build might
* be already gone (deleted, rotated, etc.)
*
* @param n build to compare with.
* @return youngest build.
*/
<RunT extends Run> RunT getNearestBuild(int n);
/**
* Gets the latest build #m that satisfies <tt>m<=n</tt>.
* <p/>
* This is useful when you'd like to fetch a build but the exact build might
* be already gone (deleted, rotated, etc.)
*
* @param n build to compare with.
* @return the oldest build.
*/
<RunT extends Run> RunT getNearestOldBuild(int n);
/**
* @return the last build
*/
<RunT extends Run> RunT getLastBuild();
/**
* @return the oldest build in the record.
*/
<RunT extends Run> RunT getFirstBuild();
/**
* @return the last successful build, if any. Otherwise null. A successful
* build would include either {@link Result#SUCCESS} or
* {@link Result#UNSTABLE}.
* @see #getLastStableBuild()
*/
<RunT extends Run> RunT getLastSuccessfulBuild();
/**
* @return the last build that was anything but stable, if any. Otherwise
* null.
* @see #getLastSuccessfulBuild
*/
<RunT extends Run> RunT getLastUnsuccessfulBuild();
/**
* @return the last unstable build, if any. Otherwise null.
* @see #getLastSuccessfulBuild
*/
<RunT extends Run> RunT getLastUnstableBuild();
/**
* @return the last stable build, if any. Otherwise null.
* @see #getLastSuccessfulBuild
*/
<RunT extends Run> RunT getLastStableBuild();
/**
* @return the last failed build, if any. Otherwise null.
*/
<RunT extends Run> RunT getLastFailedBuild();
/**
* @return the last completed build, if any. Otherwise null.
*/
<RunT extends Run> RunT getLastCompletedBuild();
/**
* Returns the last 'numberOfBuilds' builds with a build result >=
* 'threshold'
*
* @param numberOfBuilds build count to return.
* @param threshold required {@link Result} of the build.
* @return a list with the builds. May be smaller than 'numberOfBuilds' or
* even empty if not enough builds satisfying the threshold have been found.
* Never null.
*/
<RunT extends Run> List<RunT> getLastBuildsOverThreshold(int numberOfBuilds, Result threshold);
/**
* @return build status image link. Info is taken from
* {@link BallColor#getImage()}.
* @see #getIconColor()
* @see BallColor#getImage()
*/
String getBuildStatusUrl();
/**
* @return the color of the status ball for the project.
*/
BallColor getIconColor();
/**
* Get the current health report for a job.
*
* @return the health report. Never returns null
*/
HealthReport getBuildHealth();
/**
* @return list of {@link HealthReport}
*/
List<HealthReport> getBuildHealthReports();
/**
* @return {@link Graph} of builds
*/
Graph getBuildTimeGraph();
/**
* @return {@link BuildTimelineWidget} based on build history
*/
BuildTimelineWidget getTimeline();
/**
* Returns the author of the job.
*
* @return the author of the job.
* @since 2.0.1
*/
String getCreatedBy();
/**
* Returns time when the project was created.
*
* @return time when the project was created.
* @since 2.0.1
*/
long getCreationTime();
}