Package org.apache.juneau.console.views

Class RegionDef

java.lang.Object
org.apache.juneau.console.views.RegionDef
public class RegionDef extends Object
A page "region": a named container whose contents a client-side populator fills in, chosen by name via populate rather than declared inline.

Beyond the identity/populator core, this bean also carries the declarative descriptor: a data source (dataUrl / params), an inline renderer (renderer), lazy activation (lazy), a refresh interval (refreshMs), and a field/title projection (fields / titleFields). A descriptor that omits populate resolves to the Juneau-shipped declarative default (JuneauViews.regions.defaultPopulate), which reads exactly this descriptor (via ctx.declared) and nothing else.

Mutability

Deliberately mutable, like Column and ViewDef (the same rule, stated here since this class predates it): a RegionDef is a server-side authoring bean built up once via its public fields and fluent setters while constructing a page, not an immutable value object. Callers must not mutate one concurrently from more than one thread, and must not reuse one across requests unless every request treats it as read-only after construction.

Example:

// A lazily-activated row-detail region backed by a data URL, refreshing every 30 seconds. RegionDef region = RegionDef.create("release-notes") .type(RegionDef.TYPE_ROW_DETAIL) .dataUrl("/api/releases/{id}/notes") .lazy(true) .refreshMs(30_000L);

Since:
10.0.0

  • Field Details

    • CONTRACT_VERSION

      public static final String CONTRACT_VERSION
      The frozen contract version for the region envelope.

      Deliberately independent of ViewsMixin.CONTRACT_VERSION: a region-contract revision must never force a view-sidecar bump, or vice-versa.

      See Also:

    • TYPE_ROW_DETAIL

      public static final String TYPE_ROW_DETAIL
      Wire token for a row-detail region.
      See Also:

    • TYPE_CARD_BODY

      public static final String TYPE_CARD_BODY
      Wire token for a card-body region.
      See Also:

    • TYPE_TAB_BODY

      public static final String TYPE_TAB_BODY
      Wire token for a tab-body region.
      See Also:

    • MIN_REFRESH_MS

      public static final long MIN_REFRESH_MS
      The minimum honored refreshMs, in milliseconds.

      A declared interval below this floor is clamped up to it rather than honored as configured — the same reasoning and the same shared floor as SafePathTemplate.MIN_POLL_INTERVAL_MS.

      See Also:

    • id

      public String id
      This region's own id, unique within its host.

    • populate

      public String populate
      The name of the client populator to resolve via JuneauViews.regions.resolve(name), or null for the reserved declarative default ("default", see PopulatorAllowlist.BUILTIN_IDS).

      This is a name looked up in the client registry rather than an inline function for two reasons: an inline function cannot survive the JSON sidecar this envelope travels in, and a name — unlike an arbitrary function body — is the one shape a server-side allowlist (PopulatorAllowlist) can meaningfully constrain at all.

    • type

      public String type
      This region's type: TYPE_ROW_DETAIL, TYPE_CARD_BODY, or TYPE_TAB_BODY.

      Set by the enclosing host (a detail panel, a card, or a tab body) rather than by the region's own author in the common case; exposed here (rather than only in the sidecar) because validate() needs it to enforce the type-scoped field-catalog rules — a TYPE_ROW_DETAIL region must carry no fields, and a TYPE_CARD_BODY/TYPE_TAB_BODY region using the "field-grid" renderer under the reserved default must carry at least one.

    • dataUrl

      public String dataUrl
      A same-origin path from which the declarative default (and ctx.fetchDeclared()) fetches this region's payload. null means "no declared fetch" — legal, and the normal state for a custom populator that fetches its own way or paints with no fetch at all.

      Validated with isSafeDetailEndpoint(String) (same-origin, no scheme, no leading //, no .. segment).

    • params

      public Map<String,Object> params
      Author-declared request parameters, opaque to the framework as a payload (nothing routes or branches on their contents) but not opaque to the query-string serializer that appends them to dataUrl. Use a LinkedHashMap (or an equivalent ordered map) when key order matters to the endpoint: the serialization walks Map.entrySet() in the map's own iteration order.

    • renderer

      public String renderer
      The name of the JuneauViews.helpers function the declarative default paints with, e.g. "field-grid". null when a custom populate does its own painting.

    • lazy

      public Boolean lazy
      Whether this region's first populate is deferred until it becomes visible.

      null means "use the per-region-type default": false for TYPE_ROW_DETAIL and TYPE_CARD_BODY, true for TYPE_TAB_BODY — see effectiveLazy().

    • refreshMs

      public Long refreshMs
      The declared auto-refresh interval, in milliseconds, or null for no polling.

      A value below MIN_REFRESH_MS is silently clamped up to the floor rather than rejected.

    • fields

      public List<RegionDef.Field> fields
      The field catalog: labels, renderers, hrefs, spans and per-field action-bar ids, declared once per region rather than repeated per row/refresh. Projects onto ctx.declared.fields.

      Card and tab regions only. A TYPE_ROW_DETAIL region's catalog is an author-declared JS literal handed straight to fieldGrid client-side; declaring fields on a TYPE_ROW_DETAIL region fails validate().

    • titleFields

      public List<String> titleFields
      Chrome's declared title-key allowlist — the one descriptor field whose only reader is the framework's own title painter, never the populate (see the three-way partition; the declarative default's source must not reference this field).

    • allowedPopulators

      public Set<String> allowedPopulators
      App-approved populator names allowed on populate in addition to PopulatorAllowlist.BUILTIN_IDS. Blank entries fail validate().

      Opting a name in here is authoring discipline, not a security boundary — see PopulatorAllowlist's class Javadoc.

    • visibleWhen

      public List<VisibilityRule> visibleWhen
      The rules that must all match for the whole region to render. null or empty means always visible. See RowAction.visibleWhen for the shared semantics and evaluation-map convention.

    • config

      public Map<String,Object> config
      Populator-owned structured configuration. null or empty means none.

      Unlike params, nested maps and lists are allowed, and the value is never appended to dataUrl nor sent back to the server: it reaches the client only as ctx.declared.config. Its shape belongs to the populator that reads it (for example JobLogRegion); validate() only checks that it is JSON-serializable (string keys, no cycles).

  • Constructor Details

  • Method Details

    • create

      public static RegionDef create(String id)
      Creates a region with the given id.

      The identity plus populator name. Page slots do not go through this factory — author HTML plus JuneauViews.regions.mount({ id: populatorName }). Not @Deprecated.

      Parameters:
      id - This region's own id, unique within its host. Must not be null or blank.
      Returns:
      A new RegionDef.

    • populate

      public RegionDef populate(String value)
      Sets the name of the client populator to resolve.
      Parameters:
      value - A populator name, or null to use the reserved declarative default.
      Returns:
      This object.

    • type

      public RegionDef type(String value)
      Sets this region's type.
      Parameters:
      value - One of TYPE_ROW_DETAIL, TYPE_CARD_BODY, TYPE_TAB_BODY.
      Returns:
      This object.

    • dataUrl

      public RegionDef dataUrl(String value)
      Sets the same-origin data-fetch endpoint.
      Parameters:
      value - The path. Must be a same-origin path template (no ://, no leading //, no scheme colon-before-slash, no .. segment) — enforced at validate().
      Returns:
      This object.

    • params

      public RegionDef params(Map<String,Object> value)
      Sets the author-declared request parameters.
      Parameters:
      value - The parameters. A LinkedHashMap (or equivalent ordered map) when key order matters.
      Returns:
      This object.

    • params

      public RegionDef params(Object... keyValuePairs)
      Sets the author-declared request parameters from key/value pairs, preserving call order.
      Parameters:
      keyValuePairs - An even-length key, value, key, value, ... sequence.
      Returns:
      This object.

    • renderer

      public RegionDef renderer(String value)
      Sets the helper name the declarative default paints with.
      Parameters:
      value - A JuneauViews.helpers function name, e.g. "field-grid".
      Returns:
      This object.

    • lazy

      public RegionDef lazy(boolean value)
      Sets whether this region's first populate is deferred until it becomes visible.
      Parameters:
      value - true/false, or leave unset (null) for the per-region-type default.
      Returns:
      This object.

    • refreshMs

      public RegionDef refreshMs(long intervalMs)
      Declares that this region should be polled (re-fetched and re-populated) on the given interval.

      A value below MIN_REFRESH_MS is silently clamped up to the floor rather than rejected.

      Parameters:
      intervalMs - The desired polling interval, in milliseconds. Must be positive.
      Returns:
      This object.

    • visibleWhen

      public RegionDef visibleWhen(VisibilityRule... rules)
      Hides this region unless every rule matches.
      Parameters:
      rules - The rules; all must match. Replaces any rules set by an earlier call.
      Returns:
      This object.

    • config

      public RegionDef config(Map<String,Object> value)
      Sets the populator-owned structured configuration.
      Parameters:
      value - The configuration; see config.
      Returns:
      This object.

    • fields

      public RegionDef fields(RegionDef.Field... value)
      Sets the field catalog.
      Parameters:
      value - The catalog, in declaration order. Card/tab regions only — see fields.
      Returns:
      This object.

    • titleFields

      public RegionDef titleFields(String... value)
      Sets chrome's declared title-key allowlist.
      Parameters:
      value - The allowlisted keys.
      Returns:
      This object.

    • allowPopulators

      public RegionDef allowPopulators(String... value)
      Opts in app-approved populator names for populate, in addition to PopulatorAllowlist.BUILTIN_IDS.
      Parameters:
      value - Populator names. Must not contain blank entries.
      Returns:
      This object.

    • effectiveLazy

      public boolean effectiveLazy()
      The effective lazy value once the per-region-type default is applied.

      false for TYPE_ROW_DETAIL (the one region populates on expand, not lazily) and TYPE_CARD_BODY (a card is visible when its grid is); true for TYPE_TAB_BODY (preserving today's init-on-activate). An explicit lazy value always wins over the per-type default, for any type including null.

      Returns:
      The effective lazy flag.

    • validate

      public void validate()
      Fail-closed bean validation.

      Beyond the original id/populator checks, this now also enforces: a same-origin dataUrl; a recognized type (when set); no nested-map params value and no params key colliding with a key already present in dataUrl's own query string; the card/tab-only field catalog and its two startup rejections; and no blank titleFields entry.

      Throws:
      IllegalArgumentException - If this definition is not well-formed.

    • isSafeDetailEndpoint

      public static boolean isSafeDetailEndpoint(String endpoint)
      Whether endpoint is a same-origin path template: no :// , no // prefix, no scheme colon-before-slash, and no .. path segments.
      Parameters:
      endpoint - The candidate template. May be null.
      Returns:
      true if the string is a same-origin path template.

    • toContractMap

      public Map<String,Object> toContractMap()
      Serializes this descriptor to the compact JSON envelope the data-juneau-region-contract sidecar attribute carries, hand-built (rather than reflected) so the key set, order, and each nested RegionDef.Field's wire shape are exactly the ones the contract specifies.
      Returns:
      An ordered Map ready for Json.of(...).