Class PNMessageProp

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.push.PNMessageProp
All Implemented Interfaces:
EventListener, IGProp<GProp<?>[]>, IPropCnr, Cloneable
public class PNMessageProp extends PropCnr
A push notification payload as a property tree, i.e. the notification the way the IIZI property framework carries it.

What this is, and what it is not. The canonical in-flight form of a notification is the lightweight IPushNotification object: that is what the engine holds, what the admission-gated dispatch loop carries, and what the VAPID/FCM device path encrypts and ships. A PNMessageProp is the heavyweight form, materialised on demand only at the two boundaries that actually need the framework:

  1. in-session streaming to a JavaScript client, over the normal IIZI transports; and
  2. persistence - the spool, the app-session retention, and crash recovery - as XML.
Both boundaries are already off the latency-critical path: an in-session delivery is a local socket write, and persistence is the exception path, because only what could not be delivered now is ever spooled. Do not keep a notification in this form for its whole life; convert at the boundary and nowhere else.

The children map onto showNotification(title,options). The browser leg needs no translation, so the tree is deliberately flat and value-property-based:

  • TITLE and BODY - KStringProp. One property type carries both plain and HTML text, the KString's own Type distinguishing them, so text - the bulk of any notification - is fully covered by existing machinery.
  • TAG and ICON - StringProp, through the inherited getString/setString accessors.
  • DATA - StringMapProp, the ordered options.data string map.
  • OPTIONS - StringMapProp, every other showNotification option (badge, image, requireInteraction, ...), each value as its JSON text. Absent from a notification that carries none.
  • BINARY - ByteArrayProp, an optional opaque binary payload. Absent from a notification that carries none.
  • ACTIONS - PNActions, the ordered action buttons. Predefined, so a message is self-describing; not written to XML while empty.

JS-facing: the leaf types are a closed set. Everything that reaches the JavaScript client must be one of the property classes that has a hand-written JavaScript reconstructor - KStringProp, StringProp, IntProp, NumberProp, StringMapProp, StringArrayProp, ByteArrayProp and PropCnr. A custom GProp<VALUE> is Java-only: it serialises perfectly to XML and then does not reconstruct on the client. No leaf of this tree may be one, which is why every child above is drawn from the closed set. The containers themselves need no new JavaScript class - they are reconstructed by the generic PropCnr JavaScript, which is what the jsclient="PropCnr" registration in base-properties.xml selects.

Timestamps do not live here. A notification is pure payload; when it was created, when it should next be retried and when it expires are spool bookkeeping and live on PNSpoolEntry.

Author:
Christopher Mindus

  • Field Details

    • TITLE

      public static final String TITLE
      The notification title property: "title". A KStringProp, plain or HTML.
      See Also:

    • BODY

      public static final String BODY
      The notification body text property: "body". A KStringProp, plain or HTML.
      See Also:

    • TAG

      public static final String TAG
      The notification tag property: "tag", i.e. options.tag, the identifier that lets a later notification replace an earlier one on the device.
      See Also:

    • ICON

      public static final String ICON
      The notification icon URL property: "icon", i.e. options.icon.
      See Also:

    • DATA

      public static final String DATA
      The notification data map property: "data", i.e. options.data. A StringMapProp, which preserves insertion order.
      See Also:

    • OPTIONS

      public static final String OPTIONS
      The remaining options property: "options", i.e. every member of the browser showNotification options object that has no dedicated leaf of its own - badge, image, lang, dir, requireInteraction, silent, renotify, vibrate, timestamp and any application-defined member. A StringMapProp whose every value is the JSON text of the option - a string quoted, a number, boolean, array or object as written - so that a spooled notification replays with every option it was sent with, and a string option that happens to read as a number or boolean comes back a string. Absent from a notification that carries none.
      See Also:

    • BINARY

      public static final String BINARY
      The optional opaque binary payload property: "binary". A ByteArrayProp.
      See Also:

    • ACTIONS

      public static final String ACTIONS
      The action buttons property: "actions", i.e. options.actions. A PNActions container, predefined by this container and always present.
      See Also:

  • Constructor Details

    • PNMessageProp

      public PNMessageProp()
      Creates a push notification message container without name and with a null value.

    • PNMessageProp

      public PNMessageProp(Atom propertyAtom)
      Creates a push notification message container with the specified name with a null value.
      Parameters:
      propertyAtom - The property atom.

  • Method Details

    • clone

      public PNMessageProp clone()
      Creates a clone out of this property.
      Overrides:
      clone in class PropCnr
      Returns:
      The clone of the push notification message.

    • addPredefinedProps

      protected void addPredefinedProps() throws PropException
      Adds the predefined properties, i.e. the empty PNActions container, so that a message is self-describing rather than assembled ad hoc by its callers and getActions() never returns null.

      No reference is cached, so no getPredefinedProps() override is needed after a clone: getActions() looks the child up each time.

      Overrides:
      addPredefinedProps in class PropCnr
      Throws:
      PropException - If the container cannot be added.

    • getTitle

      public KString getTitle()
      Gets the title as a KString, which carries its own plain-or-HTML type.
      Returns:
      The title, or null when not set.

    • setTitle

      public boolean setTitle(KString title) throws PropException
      Sets the title from a KString, of either plain or HTML type.
      Parameters:
      title - The title.
      Returns:
      true when this property container has been changed, false otherwise.
      Throws:
      PropException - If the property cannot be added or the value is rejected.

    • setTitlePlain

      public boolean setTitlePlain(String title) throws PropException
      Sets the title from plain text.
      Parameters:
      title - The plain title text.
      Returns:
      true when this property container has been changed, false otherwise.
      Throws:
      PropException - If the property cannot be added or the value is rejected.

    • setTitleHTML

      public boolean setTitleHTML(String title) throws PropException, KStringException
      Sets the title from HTML.
      Parameters:
      title - The HTML title text.
      Returns:
      true when this property container has been changed, false otherwise.
      Throws:
      PropException - If the property cannot be added or the value is rejected.
      KStringException - If the HTML string cannot be parsed.

    • getBody

      public KString getBody()
      Gets the body text as a KString, which carries its own plain-or-HTML type.
      Returns:
      The body, or null when not set.

    • setBody

      public boolean setBody(KString body) throws PropException
      Sets the body text from a KString, of either plain or HTML type.
      Parameters:
      body - The body text.
      Returns:
      true when this property container has been changed, false otherwise.
      Throws:
      PropException - If the property cannot be added or the value is rejected.

    • setBodyPlain

      public boolean setBodyPlain(String body) throws PropException
      Sets the body text from plain text.
      Parameters:
      body - The plain body text.
      Returns:
      true when this property container has been changed, false otherwise.
      Throws:
      PropException - If the property cannot be added or the value is rejected.

    • setBodyHTML

      public boolean setBodyHTML(String body) throws PropException, KStringException
      Sets the body text from HTML.
      Parameters:
      body - The HTML body text.
      Returns:
      true when this property container has been changed, false otherwise.
      Throws:
      PropException - If the property cannot be added or the value is rejected.
      KStringException - If the HTML string cannot be parsed.

    • getTag

      public String getTag()
      Gets the notification tag, i.e. options.tag.
      Returns:
      The tag, or null when not set.

    • setTag

      public boolean setTag(String tag)
      Sets the notification tag, i.e. options.tag.
      Parameters:
      tag - The tag.
      Returns:
      true when this property container has been changed, false otherwise.

    • getIcon

      public String getIcon()
      Gets the notification icon URL, i.e. options.icon.
      Returns:
      The icon URL, or null when not set.

    • setIcon

      public boolean setIcon(String icon)
      Sets the notification icon URL, i.e. options.icon.
      Parameters:
      icon - The icon URL.
      Returns:
      true when this property container has been changed, false otherwise.

    • getDataProp

      public StringMapProp getDataProp()
      Gets the data map property, i.e. options.data.
      Returns:
      The data map property, or null when the notification carries no data.

    • putData

      public String putData(String key, String value) throws PropException
      Puts one entry in the data map, creating the map property if the notification does not yet carry one.
      Parameters:
      key - The key.
      value - The value.
      Returns:
      The previous value for the key, or null when there was none.
      Throws:
      PropException - If the map property cannot be added or is read-only.

    • getOptionsProp

      public StringMapProp getOptionsProp()
      Gets the remaining-options map property, i.e. the showNotification options that have no dedicated leaf.
      Returns:
      The options map property, or null when the notification carries none.

    • putOption

      public String putOption(String key, String value) throws PropException
      Puts one entry in the remaining-options map, creating the map property if the notification does not yet carry one.
      Parameters:
      key - The option name.
      value - The option value as JSON text: a string quoted, any other value as written.
      Returns:
      The previous value for the key, or null when there was none.
      Throws:
      PropException - If the map property cannot be added or is read-only.

    • getBinary

      public byte[] getBinary()
      Gets the opaque binary payload.
      Returns:
      The binary payload, or null when the notification carries none.

    • setBinary

      public boolean setBinary(byte[] data) throws PropException
      Sets the opaque binary payload.
      Parameters:
      data - The binary payload.
      Returns:
      true when this property container has been changed, false otherwise.
      Throws:
      PropException - If the property cannot be added.

    • getActions

      public PNActions getActions()
      Gets the action buttons container, i.e. options.actions.
      Returns:
      The actions container; never null, because it is a predefined property.