Package io.jenkins.plugins.batchcontrol.action

Class HistorySection

java.lang.Object
io.jenkins.plugins.batchcontrol.action.HistorySection
All Implemented Interfaces:
ModelObject, org.kohsuke.stapler.StaplerProxy
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public class HistorySection extends Object implements ModelObject, org.kohsuke.stapler.StaplerProxy
The history browser at /batch-control/history/ (SPEC item 12): filtered listings of run records, incidents, change records and run requests, a monthly aggregate JSON endpoint, and CSV exports.

Blocked approval-marker re-use attempts (D-30) are an exception to the one-table-per-kind layout: they are shown on every tab as an alert above the selected table, because they produce no run record and so would otherwise be invisible on the default runs tab. See getMarkerReuseItems().

URL space (fixed contract, asserted by tests):

  • /batch-control/history/ — filter form + one selectable table (?kind=runs|incidents|changes|requests, filters from, to, job, user, result, status, paging ?page=N)
  • GET /batch-control/history/summary?month=YYYY-MM — monthly aggregate JSON with exactly the keys runs, success, failure, unstable, incidentsOpen, incidentsResolved, requestsApproved, requestsRejected
  • GET /batch-control/history/runs.csv|incidents.csv|changes.csv|requests.csv — CSV exports honoring the same filter parameters (D-18 formula-injection sanitization via CsvWriter)

Everything under this section requires ViewHistory; getTarget() rejects the whole subtree with 403 otherwise (T-12-01, T-12-05). All URLs are read-only: PUT/DELETE/PATCH get 405 everywhere, and the JSON and CSV exports refuse every verb except GET/HEAD. Query parsing and validation live in FilterParser.

  • Field Details

    • PAGE_SIZE

      public static final int PAGE_SIZE
      Page size for every table.
      See Also:

    • REUSE_ALERT_LIMIT

      public static final int REUSE_ALERT_LIMIT
      How many blocked marker re-use attempts the always-visible alert lists at most.
      See Also:

    • MAX_CONCURRENT_EXPORTS

      public static final int MAX_CONCURRENT_EXPORTS
      Most CSV exports that may run at the same time, instance-wide (S-05).
      See Also:

  • Constructor Details

    • HistorySection

      public HistorySection()

  • Method Details

    • getTarget

      public Object getTarget()
      Specified by:
      getTarget in interface org.kohsuke.stapler.StaplerProxy

    • getDisplayName

      public String getDisplayName()
      Specified by:
      getDisplayName in interface ModelObject

    • getViewPermissions

      public Permission[] getViewPermissions()
      Permissions for this screen's l:layout (the same set its section gate checks).

    • getLinks

      public SectionAccess getLinks()
      Link predicates: a link to another screen is rendered only if the user may open it.

    • doSummary

      public void doSummary(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp, @QueryParameter String month) throws IOException
      GET summary?month=YYYY-MM — the monthly aggregate as JSON (T-12-04). Absent month defaults to the current month; a malformed month is a 400.
      Throws:
      IOException

    • doDynamic

      public void doDynamic(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException
      Serves the four CSV export URLs (runs.csv, incidents.csv, changes.csv, requests.csv); anything else under this section is a 404. Stapler cannot route dotted tokens to do* methods, hence the dynamic dispatch.
      Throws:
      IOException
      jakarta.servlet.ServletException

    • getFilter

      public FilterParser.Filter getFilter()
      The validated filter for the current request (parsed once).

    • getKind

      public String getKind()
      The selected table, from ?kind=; runs on absence or garbage.

    • getBaseQuery

      public String getBaseQuery()
      The filter as a query fragment (no kind, no page) for CSV links.

    • query

      public String query(String kind)
      Full query fragment for a tab link of the given kind (filter preserved, page reset).

    • getCsvUrl

      public String getCsvUrl()
      The complete CSV export of what this screen lists (S-03), relative to this section. Pointed to by the truncation notice: the export is not bound by the per-screen record cap. Only ISO dates and constant names go into it, so no encoding is needed.

    • getMarkerReuseItems

      public List<ChangeRecord> getMarkerReuseItems()
      The blocked approval-marker re-use records matching the filter, newest first, at most REUSE_ALERT_LIMIT of them (D-30).

      A blocked re-use produces no RunRecord, so on the default runs tab the attempt would otherwise be invisible; the index view renders these rows as an alert above the selected table on every tab. The period, job and user filters are the Changes tab's, so the alert describes the same window as that tab (which is what makes ?user=u2 a query for "what did this account attempt"). The read is bounded like every page.

    • getMarkerReuseCount

      public int getMarkerReuseCount()
      How many blocked re-use attempts match the filter (a lower bound when truncated).

    • getMarkerReuseAlertItems

      public List<ChangeRecord> getMarkerReuseAlertItems()
      The re-use rows the alert actually lists: the newest REUSE_ALERT_LIMIT. The alert must stay a signal rather than become a second unbounded table when an automation retries in a loop; getMarkerReuseOverflow() says how many rows were left out and the Changes tab (and changes.csv) has all of them.

    • getMarkerReuseOverflow

      public int getMarkerReuseOverflow()
      How many matching re-use records the alert does not list; 0 when it lists them all.

    • getPage

      public int getPage()
      Current 1-based page, from the page query parameter (Paging).

    • getPageItems

      public List<?> getPageItems()
      The rows of the selected kind shown on the current page, newest first.

    • getTotal

      public int getTotal()
      Matching records read (a lower bound when isTruncated()).

    • isTruncated

      public boolean isTruncated()
      Whether the per-request record cap stopped the read: ask to narrow the filter.

    • getOversized

      public int getOversized()
      Over-long lines (over 1 MiB) skipped while reading this table (security-11 N-02); the CSV export skips the same lines, so the screen says so rather than look complete.

    • isHasPrevious

      public boolean isHasPrevious()

    • isHasNext

      public boolean isHasNext()

    • getSummaryMonth

      public String getSummaryMonth()
      The month shown in the on-page summary block and the JSON link: month of the filter end.

    • getSummary

      public Map<String,Long> getSummary()
      The on-page monthly aggregate rows for getSummaryMonth().

    • getMonthlyMonth

      public String getMonthlyMonth()
      The month of the monthly summary screen (e2e-03 DEF-22, T-12-12), from ?month=YYYY-MM; anything else (absent, malformed) falls back to getSummaryMonth(), so the query string never reaches the page unparsed.

    • getMonthlySummary

      public Map<String,Long> getMonthlySummary()
      The rows of the monthly summary screen for getMonthlyMonth().

    • summaryLabel

      public String summaryLabel(String key)
      The label of a monthly summary row; an unknown key is shown as it is.

    • join

      public String join(@CheckForNull List<String> approvers)
      An approver set for display (a1, a2).

    • format

      public String format(Instant instant)
      Human-readable timestamp.

    • duration

      public String duration(long durationMs)
      Human-readable duration.

    • runUrl

      @CheckForNull public String runUrl(RunRecord record)
      Root-relative build URL for a run record, or null for plain text (D-44).

    • incidentRunUrl

      @CheckForNull public String incidentRunUrl(Incident incident)
      Root-relative build URL for an incident's originating run, or null for plain text (D-44).

    • incidentCreatedAt

      @CheckForNull public Instant incidentCreatedAt(Incident incident)
      Creation timestamp of an incident.

    • parameters

      public String parameters(Map<String,String> parameters)
      One-line parameter rendering; values come from the record already masked.