Package org.apache.juneau.console.views

Class BadgeDef

java.lang.Object

org.apache.juneau.console.views.BadgeDef

public final class BadgeDef
extends Object

A count badge in the page contract, fed by a JSON endpoint and polled by juneau-badges.js.

The endpoint returns {total, mine?, items?[]}. The badge is presentation only: the endpoint must still authorize the caller, and a page should not declare a badge for users who cannot read it.

Example:

var badge = BadgeDef .create("pending") .src("/rest/changes/pending") .scope("beanType", BadgeDef.ScopeBy.NAV, Map.of("suspensions", List.of("Suspension"))) .href("/ui/changes") .stateFilter("beanType") .refreshes("rules-table") .refreshMs(60_000); badge.validate(); // throws IllegalArgumentException with an E-6x message

Since:

10.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	BadgeDef.Placement	placement wire tokens.
static enum	BadgeDef.ScopeBy	scope.by wire tokens.
static enum	BadgeDef.Tone	tone wire tokens.

Field Summary

Fields

Modifier and Type	Field	Description
static final long	DEFAULT_REFRESH_MS	Default poll interval, in milliseconds, applied by juneau-badges.js when refreshMs is unset.
static final int	DEFAULT_TOOLTIP_MAX	Default tooltip item cap, applied by juneau-badges.js when tooltipMax is unset.
static final long	MIN_REFRESH_MS	The minimum poll interval, in milliseconds (refreshMs.minimum).

Method Summary

Modifier and Type	Method	Description
static BadgeDef	create(String id)	Creates a badge with the given id.
BadgeDef	href(String value)	Sets the click-target URL.
BadgeDef	label(Map<String,String> value)	Sets this badge's label templates.
BadgeDef	params(Map<String,Object> value)	Sets extra request parameters merged into every poll (ahead of the scope params).
BadgeDef	placement(BadgeDef.Placement value)	Sets where this badge renders.
BadgeDef	refreshes(String... value)	Sets the card ids to JuneauViews.tables.reload(el, {resetPaging: false}) when a previously-seen item id drains from the badge's response.
BadgeDef	refreshesAllowMissing(String... value)	Sets card ids, added to refreshes, that are allowed to be absent from the page being rendered.
BadgeDef	refreshMs(long intervalMs)	Sets the poll interval.
BadgeDef	scope(String param, BadgeDef.ScopeBy by, Map<String,List<String>> values)	Sets this badge's scope: the request param to key the poll on, how to resolve its value, and (optionally) the authoritative value map.
BadgeDef	src(String value)	Sets the same-origin endpoint this badge polls.
BadgeDef	stateFilter(String column)	Sets the column href's destination page filters on, via JuneauViews.urlState.encode(...).
BadgeDef	table(String value)	Sets the card id this badge is anchored to.
Map<String,Object>	toContractMap()	Serializes this definition to the compact JSON the header.badges[] contract carries, hand-built (rather than reflected) so the key set and order match the schema exactly.
BadgeDef	tone(BadgeDef.Tone value)	Sets this badge's tone.
BadgeDef	tooltipMax(int value)	Sets the tooltip popover's item cap.
void	validate()	Validates this definition.
BadgeDef	visibleWhen(VisibilityRule... value)	Sets the dynamic-visibility rules gating this badge; all must match (AND).

Methods inherited from class java.lang.Object

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

Field Details

MIN_REFRESH_MS

public static final long MIN_REFRESH_MS

The minimum poll interval, in milliseconds (refreshMs.minimum).

See Also:

• Constant Field Values

DEFAULT_REFRESH_MS

public static final long DEFAULT_REFRESH_MS

Default poll interval, in milliseconds, applied by juneau-badges.js when refreshMs is unset.

See Also:

• Constant Field Values

DEFAULT_TOOLTIP_MAX

public static final int DEFAULT_TOOLTIP_MAX

Default tooltip item cap, applied by juneau-badges.js when tooltipMax is unset.

See Also:

• Constant Field Values

Method Details

create

public static BadgeDef create(String id)

Creates a badge with the given id.

Parameters:

id - This badge's own id, unique across every Java- and FTL-declared badge on the page (C3 E-B15). Must not be null or blank.

Returns:

A new BadgeDef.

Throws:

IllegalArgumentException - If id is null or blank.

src

public BadgeDef src(String value)

Sets the same-origin endpoint this badge polls.

Parameters:

value - The endpoint path. Checked by validate(): present (E-61) and a same-origin path per SafePathTemplate.isSameOriginPath(String).

Returns:

This object.

params

public BadgeDef params(Map<String,Object> value)

Sets extra request parameters merged into every poll (ahead of the scope params).

Parameters:

value - The parameters.

Returns:

This object.

refreshMs

public BadgeDef refreshMs(long intervalMs)

Sets the poll interval.

Parameters:

intervalMs - The desired interval, in milliseconds. Checked against MIN_REFRESH_MS by validate() (E-62) — unlike RegionDef.refreshMs(long), this is rejected, not clamped.

Returns:

This object.

scope

public BadgeDef scope(String param,
 BadgeDef.ScopeBy by,
 Map<String,List<String>> values)

Sets this badge's scope: the request param to key the poll on, how to resolve its value, and (optionally) the authoritative value map.

Parameters:

param - The query parameter name sent with the poll. Must not be null or blank.

by - BadgeDef.ScopeBy.NAV or BadgeDef.ScopeBy.VIEW.

values - The authoritative value map, keyed by nav-leaf or view-tab id, or null for an unscoped badge that still carries a by.

Returns:

This object.

label

public BadgeDef label(Map<String,String> value)

Sets this badge's label templates.

Parameters:

value - A map with any of the keys one, other, mine, each a {total}/ {mine} template. Unset keys fall back to the stock defaults in juneau-badges.js.

Returns:

This object.

tooltipMax

public BadgeDef tooltipMax(int value)

Sets the tooltip popover's item cap.

Parameters:

value - The cap, 0-50. Not range-checked here; schema `$defs/badge.tooltipMax` enforces it for FTL-declared badges, and an out-of-range Java value is simply clamped by juneau-badges.js at render time.

Returns:

This object.

href

public BadgeDef href(String value)

Sets the click-target URL.

Parameters:

value - The destination. Must be a same-origin path per SafePathTemplate.isSameOriginPath(String); validate() rejects anything else, and juneau-badges.js refuses an unsafe href again at run time (E-JS-82).

Returns:

This object.

stateFilter

public BadgeDef stateFilter(String column)

Sets the column href's destination page filters on, via JuneauViews.urlState.encode(...). Requires a non-empty scope(java.lang.String, org.apache.juneau.console.views.BadgeDef.ScopeBy, java.util.Map<java.lang.String, java.util.List<java.lang.String>>) to have any effect.

Parameters:

column - The destination table's filter column name.

Returns:

This object.

refreshes

public BadgeDef refreshes(String... value)

Sets the card ids to JuneauViews.tables.reload(el, {resetPaging: false}) when a previously-seen item id drains from the badge's response.

Every id here must name a card on the page being rendered, unless it is also listed in refreshesAllowMissing(String...).

Parameters:

value - The card ids, in reload order.

Returns:

This object.

refreshesAllowMissing

public BadgeDef refreshesAllowMissing(String... value)

Sets card ids, added to refreshes, that are allowed to be absent from the page being rendered.

A page normally rejects a refreshes id that names no card on it, which catches typos at build time. Use this for a header badge that refreshes a card living on another page: the client skips a card that is not mounted. The ids named here are exempt from that check; every id passed to refreshes stays strict. The name follows the refreshes / stateFilter noun style of this builder: the opt-in is per id, not a page-wide switch.

Parameters:

value - The card ids that may live on another page.

Returns:

This object.

placement

public BadgeDef placement(BadgeDef.Placement value)

Sets where this badge renders.

Parameters:

value - BadgeDef.Placement.HEADER (default) or BadgeDef.Placement.TOOLBAR.

Returns:

This object.

table

public BadgeDef table(String value)

Sets the card id this badge is anchored to. Required when placement is BadgeDef.Placement.TOOLBAR (E-66) and when scope(java.lang.String, org.apache.juneau.console.views.BadgeDef.ScopeBy, java.util.Map<java.lang.String, java.util.List<java.lang.String>>)'s by is BadgeDef.ScopeBy.VIEW (uncoded).

Parameters:

value - The card id.

Returns:

This object.

tone

public BadgeDef tone(BadgeDef.Tone value)

Sets this badge's tone.

Parameters:

value - BadgeDef.Tone.INFO, BadgeDef.Tone.WARNING (default) or BadgeDef.Tone.DANGER.

Returns:

This object.

visibleWhen

public BadgeDef visibleWhen(VisibilityRule... value)

Sets the dynamic-visibility rules gating this badge; all must match (AND).

Parameters:

value - The rules, or none for an always-visible badge.

Returns:

This object.

validate

public void validate()

Validates this definition.

Enforces E-61 (no src), a same-origin src and href, E-62 (refreshMs below MIN_REFRESH_MS), E-66 (BadgeDef.Placement.TOOLBAR without table), and the view-scope rule (uncoded: BadgeDef.ScopeBy.VIEW without table). The "table/refreshes name a real card id" rule and the "scope.values key is a real nav node id" need the rest of the page and run in PageCapture at </@console> instead.

Throws:

IllegalArgumentException - If this definition is not well-formed.

toContractMap

public Map<String,Object> toContractMap()

Serializes this definition to the compact JSON the header.badges[] contract carries, hand-built (rather than reflected) so the key set and order match the schema exactly.

Returns:

An ordered Map ready for Json.of(...).