Package com.iizix.text

Class KString

java.lang.Object
com.iizix.text.KString
All Implemented Interfaces:
Cloneable, Comparable<KString>
Direct Known Subclasses:
KStringStyled, PlainKString
public class KString extends Object implements Cloneable, Comparable<KString>
The KString outputs a text string of a type. The available types are plain strings and HTML. As an options, the string can contain tags that are replaced with other strings at runtime. These tags can refer to e.g. a VirtualSpace Field, to application or system fields (such as the current date, the server operating system).

To perform fast, a KString can have its contents parsed at creation time for any tags, or this can be set as a parameter. The references can be retrieved as well. When stored into XML, the string is parsed references are written to XML.

HTML strings

The following rules apply to the HTML strings:
(Note: [] are replacements for <>)

  1. White space characters CR/LF/Tab/Space characters are replaced with spaces. As the W3C specification states, note that although &#x2028; and &#x2029; are defined in ISO10646 to unambiguously separate lines and paragraphs, respectively, these do not constitute line breaks in HTML.
  2. More than one white spaces are merged into a single white space when not inside a [PRE] element (preformatted text).
  3. Valid tags: B, I, U, EM, STRONG, BR, P, CODE, PRE, A, IMG, SPAN, DIV, FONT, SUP, SUB, TT, STRIKE, S, HR, CITE, DFN, SAMP, KBD, VAR, ABBR, ACRONYM, ADDRESS, ARTICLE, ASIDE, AUDIO, DATA, DETAILS, SUMMARY, FIGCAPTION, FIGURE, FOOTER, HEADER, MAIN, MARK, METER, NAV, PICTURE, SOURCE, PROGRESS, SECTION, TIME, VIDEO, TRACK, WBR, Q, BLOCKQUOTE, BIG, SMALL, BDI, BDO, INS, DEL, UL, OL, LI, DL, DT, DD, TABLE, CAPTION, COL, COLGROUP, SITE, THEAD, TFOOT, TBODY, TR, TH, TD, H1, H2, H3, H4, H5, H6.
  4. SVG is supported, see below.
  5. Additionally, the IZ tag is defined as described below.
  6. All attributes in tags relating to Javascript, e.g. "onclick", are forbidden for security reasons.
  7. The following tags are not allowed to have a close tag (e.g. </BR>): BR, IZ.

Unsupported tags: LINK, HEAD, SCRIPT, NOSCRIPT, TITLE, META, IFRAME, BODY, HTML, OBJECT, APPLET, BASE, DATALIST, DIALOG, DIR, FRAMESET, FRAME, NOFRAMES, PARAM, STYLE, FORM, INPUT, BUTTON, LABEL, SELECT, OPTION, OPTGROUP, OUTPUT, TEMPLATE, TEXTAREA, ISINDEX, FIELDSET, LEDGEND, CENTER, AREA, MAP, RUBY, RP, RT.
Some new HTML5 tags are not supported either.

The following tags are used by IIZI (where [] indicate optional attribute):

IZ type="tt" name="textID"
Reference to the text table with the full text ID "id".
IZ type="vs" name="fullPath" [format="vsFieldFormatString"]
Text retrieval from a VirtualSpace field with the specified "name", with optional "format" string, specific to the data type of the VirtualSpace field.
IZ type="connector" name="fullPath" [attr1="value1" ...customAttrValuePairs... attrN="valueN"]
Text retrieval from a VirtualSpace field with the specified "name", with optional "format" string, specific to the data type of the VirtualSpace field.
A href="fullPath" type="Resource|VS|Panel|Connector" [format="VSField-specific"] [attr1="value1" ...customAttrValuePairs... attrN="valueN"]
Hyperlink reference to the "fullPath" that can be of "type":
  • Resource
    link opens a new page to e.g. a HTML page, a video.
  • VS
    link performs the associated VirtualSpace action.
  • Connector
    link executes a hyperlink action with optional connector-specific "customAttrValuePairs".
  • Panel
    link changes to another panel.
IMG src="fullPath" [alt="textDescription"] [width="150"] [height="60"]
An image in the application, with an optional tooltip "textDescription" and a size (overrides the image size) of "width" and "height". The "fullPath" specifies the image resource path in the application (e.g. not on the web such as "http://something.com/image.gif". The "src" URL attribute is set to point correctly to the image for the end-user application at runtime.

Normal string

Normal strings are by its nature limited to the single functionality of retrieving a text, as opposed to HTML tags that e.g. also can request an action.

Tags are declared enclosed in curly brackets. The have the format:

    {type=value attr=value ... attrN=valueN}
Rules for the format:

  • To have a curly bracket '{' in the string as a character, double it "{{".
  • Attribute-value pairs are separated by one or more white space characters (space, tab, carriage return or linefeed).
  • Valid characters in an attribute name are valid Unicode characters with a code point above 32 (space), except the equal sign '=' or the curly bracket '{}'.
  • Attribute values must be specified.
  • Attribute values must be enclosed in quotes (single or double). Tip: a value that contains a double-quote can be surrounded by single-quotes, and vice versa.
  • To enter the quote character surrounding the value in the value, enter it twice (e.g. "I don't think it's ""difficult"" to specify", or 'I don''t think it''s "difficult" to specify').
The different "type" strings defined are:
{tt="textID"}
text table reference to textID.
{vs="fullPath" [format="vsFieldFormatString"]}
text retrieval from a VirtualSpace field with the specified "name", with optional "format" string, specific to the data type of the VirtualSpace field.
{connector="fullPath" [attr1=value1 ...customAttrValuePairs... attrN=valueN]}
text retrieval from a Connector with the "fullPath" name.

SVG

The following tags are supported:

  • Animation elements:
    animate, animateColor, animateMotion, animateTransform, discard, mpath, set
  • Basic shapes:
    circle, ellipse, line, polygon, polyline, rect
  • Container elements:
    a, defs, g, marker, mask, missing-glyph, pattern, svg, switch, symbol, unknown
  • Descriptive elements:
    desc, metadata, title
  • Filter primitive elements:
    feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDropShadow, feFlood, feFuncA, feFuncB, feFuncG, feFuncR,feGaussianBlur, feImage, feMerge, feMergeNode, feMorphology, feOffset, feSpecularLighting, feTile, feTurbulence
  • Font elements:
    font, font-face, font-face-format, font-face-name, font-face-src, font-face-uri, hkern, vkern
  • Gradient elements:
    linearGradient, meshgradient, radialGradient, stop
  • Graphics elements:
    circle, ellipse, image, line, mesh, path, polygon, polyline, rect, text, use
  • Graphics referencing elements:
    audio, iframe (ILLEGAL), image, mesh, use, video
  • HTML elements:
    audio, canvas, iframe (ILLEGAL), video
  • Light source elements:
    feDistantLight, fePointLight, feSpotLight
  • Never-rendered elements:
    clipPath, defs, hatch, linearGradient, marker, mask, meshgradient, metadata, pattern, radialGradient, script (ILLEGAL), style, symbol, title
  • Paint server elements:
    hatch, linearGradient, meshgradient, pattern, radialGradient, solidcolor
  • Renderable elements:
    a, audio, canvas, circle, ellipse, foreignObject, g, iframe (ILLEGAL), image, line, mesh, path, polygon, polyline, rect, svg, switch, symbol, text, textPath, tspan, unknown, use, video
  • Shape elements:
    circle, ellipse, line, mesh, path, polygon, polyline, rect
  • Structural elements:
    defs, g, svg, symbol, use
  • Text content elements:
    altGlyph, altGlyphDef, altGlyphItem, glyph, glyphRef, textPath, text, tref, tspan
  • Text content child elements:
    altGlyph, textPath, tref, tspan
  • Uncategorized elements:
    clipPath, color-profile, cursor, filter, foreignObject, hatchpath, meshpatch, meshrow, script (ILLEGAL), style, view
Author:
Christopher Mindus

  • Field Details

    • EMPTY

      public static final KString EMPTY
      The empty string: empty PLAIN.

    • DEFAULT

      public static final KString DEFAULT
      The default string: empty HTML.

  • Constructor Details

    • KString

      public KString(KString.Type type, String inputString) throws KStringException
      Creates the parsed KString where it is assumed the string can contain tags.
      Parameters:
      type - The type of string, PLAIN or HTML.
      inputString - The input string in correct format.
      Throws:
      KStringException - If type or inputString is null, for parsing or reference errors.

    • KString

      public KString(KString.Type type, String inputString, boolean usesTagProcessing) throws KStringException
      Creates the parsed KString.

      The parameter usesTagProcessing is used to control parsing of the string to look-up potential references to e.g. the iiziApp. An HTML string will be parsed for security reasons in all cases.

      Parameters:
      type - The type of string, PLAIN or HTML.
      inputString - The input string in correct format.
      usesTagProcessing - Flag indicating special IIZI tags might be included.
      Throws:
      KStringException - For string errors.
      KStringParseException - For parsing errors.
      IllegalArgumentException - If type or inputString is null.

  • Method Details

    • newPlainKString

      public static PlainKString newPlainKString(String inputString)
      Creates a new PlainKString where it is assumed the string doesn't use tags.
      Parameters:
      inputString - The input string.
      Returns:
      A new instance of the PlainKString.

    • createKString

      public static KString createKString(Element e) throws KStringException
      Constructs a KString from an Element.
      Parameters:
      e - The Element.
      Returns:
      A new KString, null if the "value" attribute is not present.
      Throws:
      KStringException - For string errors.
      KStringParseException - For parsing errors.

    • toElement

      public void toElement(Element e)
      Fills in the serialize information for this KString contents in an Element, so that it can be recreated when the XML is loaded in KStringProp.
      Parameters:
      e - The XML element to initialize attributes in.

    • createKStringForEditor

      public static KString createKStringForEditor(String inputString, boolean usesTagProcessing) throws KStringException
      Special creator for HTML-edited text in the Editor. INPUT tags are used to insert text references, and this tag is converted with this method.
      Parameters:
      inputString - The input string in correct format.
      usesTagProcessing - Flag indicating special IIZI tags might be included.
      Returns:
      The KString edited in the RichTextEditor.
      Throws:
      KStringException - For string errors.
      KStringParseException - For parsing errors.

    • getSource

      public String getSource()
      Gets the source of the KString.
      Returns:
      The source string that constructed the KString, or null if not available (it is only non-null in the Designer).

    • toPlainKString

      public PlainKString toPlainKString() throws KStringException
      Gets a PlainKString from this KString instance. This will succeed if the Type is PLAIN. If this already is a PlainKString instance, the same instance (this) is returned.
      Returns:
      A new PlainKString.
      Throws:
      KStringException - If this is not possible, i.e. if it's an HTML Type.

    • dispose

      public void dispose()
      Disposes of the KString, needed in the Editor when references are used.

    • finalize

      protected void finalize() throws Throwable
      Called when the KString is being garbage collected.

      The KString will be disposed if not previously disposed of.

      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • getType

      public KString.Type getType()
      Gets the type of KString.
      Returns:
      Type.PLAIN or Type.HTML.

    • isHTML

      public boolean isHTML()
      Check if it's an HTML string originally.
      Returns:
      true if this KString is of HTML type.

    • isPLAIN

      public boolean isPLAIN()
      Check if it's an PLAIN string originally.
      Returns:
      true if this KString is of PLAIN type.

    • isEmpty

      public boolean isEmpty()
      Checks if the string is empty, i.e. contains no characters and no tags.
      Returns:
      true if this KString would resolve to an empty string.

    • isEmptyBlankResolved

      public boolean isEmptyBlankResolved(boolean checkBlank, IKStringInfoProvider provider)
      Checks if the resolved KString of the current type would be an empty or blank string. References to text files, etc, is handled.
      Parameters:
      checkBlank - Flag to use String.isBlank() if true, otherwise String.isEmpty() when false. A blank string is either empty or contains only whitespace code points.
      provider - The KString information provider.
      Returns:
      The empty string flag.
      Throws:
      NullPointerException - If the KString information provider is null.

    • usesTagProcessing

      public boolean usesTagProcessing()
      Checks if this string uses the original value (HTML tags are always validated though). For PLAIN text, this means no transformation whatsoever from the original input string.
      Returns:
      Flag indicating if tag-processing is enabled.

    • hasTags

      public boolean hasTags()
      Checks for presence of tags in the text in its original form (HTML or PLAIN). The option not to parse the string only applies for PLAIN text (when usesTagProcessing() returns false, this method always returns false).
      Returns:
      Flag indicating presence of tags.

    • hasReferenceTags

      public boolean hasReferenceTags()
      Checks for the presence of content modifiable tags: A, IMG, IZ for HTML, or the reference tags in PLAIN format.
      Returns:
      true if there are any tags with references.

    • hasImageReferenceTags

      public boolean hasImageReferenceTags()
      Checks for the presence of image content modifiable tags: IMG.
      Returns:
      true if there are any tags with references to a text table.

    • hasTextTableReferenceTags

      public boolean hasTextTableReferenceTags()
      Checks for the presence of content modifiable text table reference tags.

      This method is typically used to check if updates is required to the resolved KString HTML or PLAIN string in case of language change.

      Returns:
      true if there are any tags with references to a text table.

    • willLoseFormatting

      public boolean willLoseFormatting()
      Checks if this string will lose formatting when translated to PLAIN. Note that translating PLAIN to HTML never loses formatting.
      Returns:
      true if the string will lose formatted if converted from HTML to PLAIN, false if KString type is PLAIN or there are no tags that cannot be represented in a PLAIN KString.

    • getRawString

      public String getRawString()
      Gets the "raw" string formatted in the "native" type, i.e. HTML or PLAIN.
      Returns:
      The raw native-formatted string.

    • getRawDebugString

      public String getRawDebugString()
      Gets the "raw" string formatted in the "native" type, i.e. HTML or PLAIN.
      Returns:
      The raw native-formatted string, where HTML character entities (in case of a HTML Ktring type) are surrounded by curly brackets '{}' and tags with brackets '[]'. Tags are surrounded with brackets in either HTML or PLAIN format.

    • getRawPLAINString

      public String getRawPLAINString()
      Gets the "raw" PLAIN formatted string. This method is used by the designer to get the editable contents. It can also be used to convert a KString from HTML to PLAIN, but quite a lot of information is then lost (e.g. all formatting).
      Returns:
      The PLAIN formatted string.

    • getRawPLAINDebugString

      public String getRawPLAINDebugString()
      Gets the "raw" PLAIN formatted string.
      Returns:
      The PLAIN formatted string with tags where located, enclosed in brackets '[]'.

    • getRawHTMLString

      public String getRawHTMLString()
      Gets the "raw" HTML formatted string. This method is used by the designer to get the editable contents. It can also be used to convert a KString from PLAIN to HTML.
      Returns:
      The HTML formatted string.

    • getRawHTMLDebugString

      public String getRawHTMLDebugString()
      Gets the "raw" HTML debug-formatted string.
      Returns:
      The HTML formatted string with tags where located, enclosed in brackets '[]', and HTML character identities with curly brackets '{}', except inside tags.

    • getRawHTMLStringForEditor

      public String getRawHTMLStringForEditor()
      Gets the "raw" HTML formatted string, with special formatting as required by the Rich Text Editor.
      Returns:
      The HTML formatted string for Rich Text Editor.

    • getRawHTMLStringForEditor

      public String getRawHTMLStringForEditor(IKStringInfoProvider provider)
      Gets the "raw" HTML formatted string, with special formatting as required by the Rich Text Editor.
      Parameters:
      provider - The information provider or null for none.
      Returns:
      The HTML formatted string for Rich Text Editor.

    • getPLAINString

      public String getPLAINString(IKStringInfoProvider provider)
      Gets the string formatted in HTML.
      Parameters:
      provider - The information provider or null for none.
      Returns:
      The HTML formatted string.

    • getPLAINString

      public String getPLAINString(TextTable textTableBase, String languageCode)
      Resolves the string that may contain tags to a text table. No other tag is allowed, and the string MUST be of PLAIN type.

      The text entries for a specific language code is first looked up, then it falls back on the derived tables in order.

      Parameters:
      textTableBase - The base text table to use, null will result in a NullPointerException.
      languageCode - The language code supported by the app, null for default.
      Returns:
      The localized-resolved string.
      Throws:
      IllegalArgumentException - If the KString is not PLAIN or contains tags other than Text Table tags.
      NullPointerException - If the KString contains text table tags and the textTable is null

    • getHTMLString

      public String getHTMLString(IKStringInfoProvider provider)
      Gets the string formatted in HTML.
      Parameters:
      provider - The information provider or null for none.
      Returns:
      The HTML formatted string.

    • isRefreshRequired

      public boolean isRefreshRequired(RefreshEvent event)
      Returns whether the KString needs a refresh for the specified refresh type.
      Parameters:
      event - The refresh event.
      Returns:
      true for refresh needed, false otherwise.

    • equals

      public boolean equals(Object obj)
      Checks for equality between two KStrings, including reference refresh counter checking and potential original source string. If the source strings are not available, but only the raw data, those strings are compared for equality.
      Overrides:
      equals in class Object
      Parameters:
      obj - Another KString (perhaps).
      Returns:
      true if equal, false otherwise.

    • hashCode

      public int hashCode()
      The hash code.
      Overrides:
      hashCode in class Object
      Returns:
      A hash code built from the "type", "usesTagProcessing" and the "data".

    • equalsOmitReferenceRefreshCheck

      public boolean equalsOmitReferenceRefreshCheck(KString ks)
      Checks for pure equality between two KStrings, excluding reference refresh counter checking but including potential original source string.

      This method is used when comparing values for e.g. save file.

      Parameters:
      ks - Another KString, perhaps null.
      Returns:
      true if equal, false otherwise.

    • compareTo

      public int compareTo(KString ks)
      Compares two KStrings with the raw format in their respective native format.
      Specified by:
      compareTo in interface Comparable<KString>
      Parameters:
      ks - Another KString.
      Returns:
      The string comparison value, not taking into account the type of KString nor if tag processing is used, i.e. the comparison is done with the 'source' if both has a source representation (e.g. in the Editor or coded for it using the KString constructor that includes 'source'), otherwise the comparison is done using the result of getRawString() for both KString's.

    • clone

      public KString clone()
      Clones this KString.
      Overrides:
      clone in class Object
      Returns:
      A new KString instance.

    • getTags

      public KStringTag<?>[] getTags()
      Gets the array of tags for this string.
      Returns:
      The array of tags for this string, null for none.

    • getTag

      public KStringTag<?> getTag(int position, boolean doIncludeStartPos)
      Gets the tag at specified position in string.
      Parameters:
      position - Position in String.
      doIncludeStartPos - Include starting position or not.
      Returns:
      The tag, or null if not found.

    • toString

      public String toString()
      Formats to a String.
      Overrides:
      toString in class Object
      Returns:
      A string as KString[<i>type</i>,tags=<i>boolean</i>] = "<i>rawString</i>" where type is HTML or plain, tags indicates if tag support is enabled or not and rawString is the raw string representation of the KString data.

    • toDebugString

      public String toDebugString()
      Formats to a Debug String.
      Returns:
      A string as KString[<i>type</i>,tags=<i>boolean</i>] = "<i>rawString</i>" where type is HTML or plain, tags indicates if tag support is enabled or not and rawString is the raw string representation of the KString data.

      The raw native-formatted string, where HTML character entities (in case of a HTML KString type) are surrounded by curly brackets '{}' and tags with brackets '[]'. Tags are surrounded with brackets in either HTML or PLAIN format.

    • format

      public KString format(Object... params) throws KStringException
      Formats the HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to HTML or PLAIN KString's, depending on this KString instance type.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The locale and potential IKStringInfoProvider provider is looked up from the current thread if required.

      Parameters:
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted KString of the same KString.Type as this instance. The return value might be this KString instance if there are no parameters available or if there is no parameter reference.
      Throws:
      KStringException - For exceptions formatting a HTML string.
      See Also:

    • format

      public KString format(IKStringInfoProvider provider, Object... params) throws KStringException
      Formats the HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to HTML or PLAIN KString's, depending on this KString instance type.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The locale is looked up from the current thread if required.

      Parameters:
      provider - The information provider or null to look it up for the current session.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted KString of the same KString.Type as this instance. The return value might be this KString instance if there are no parameters available or if there is no parameter reference.
      Throws:
      KStringException - For exceptions formatting a HTML string.
      See Also:

    • format

      public KString format(Locale locale, Object... params) throws KStringException
      Formats a HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to HTML or PLAIN KString's, depending on this KString instance type.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      Parameters:
      locale - The Locale, or null to look it up for the current thread if needed.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted KString of the same KString.Type as this instance. The return value might be this KString instance if there are no parameters available or if there is no parameter reference.
      Throws:
      KStringException - For exceptions formatting a HTML string.
      See Also:

    • format

      public KString format(IKStringInfoProvider provider, Locale locale, Object... params) throws KStringException
      Formats a HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to HTML or PLAIN KString's, depending on this KString instance type.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      Parameters:
      provider - The information provider or null to look it up for the current session.
      locale - The Locale, or null to look it up for the current thread if needed.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted KString of the same KString.Type as this instance. The return value might be this KString instance if there are no parameters available or if there is no parameter reference.
      Throws:
      KStringException - For exceptions formatting a HTML string.
      See Also:

    • format

      public KString format(ILocaleString localeString, Object... params) throws KStringException
      Formats a HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to HTML or PLAIN KString's, depending on this KString instance type.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The IKStringInfoProvider is looked up from the current session.

      Parameters:
      localeString - The locale string instance, or null for current session.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted KString of the same KString.Type as this instance. The return value might be this KString instance if there are no parameters available or if there is no parameter reference.
      Throws:
      KStringException - For exceptions formatting a HTML string.
      See Also:

    • format

      public KString format(IKStringInfoProvider provider, ILocaleString localeString, Object... params) throws KStringException
      Formats a HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to HTML or PLAIN KString's, depending on this KString instance type.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      Parameters:
      provider - The information provider or null to look it up for the current session.
      localeString - The locale string instance, or null for current session.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted KString of the same KString.Type as this instance. The return value might be this KString instance if there are no parameters available or if there is no parameter reference.
      Throws:
      KStringException - For exceptions formatting a HTML string.
      See Also:

    • format

      public KString format(LocaleInfo localeInfo, Object... params) throws KStringException
      Formats a String using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to HTML or PLAIN KString's, depending on this KString instance type.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The IKStringInfoProvider is looked up from the current session.

      Parameters:
      localeInfo - The Locale information, or null to look it up from the current thread if needed.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted KString of the same KString.Type as this instance. The return value might be this KString instance if there are no parameters available or if there is no parameter reference.
      Throws:
      KStringException - For exceptions formatting a HTML string.
      See Also:

    • format

      public KString format(IKStringInfoProvider provider, LocaleInfo localeInfo, Object... params) throws KStringException
      Formats a String using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to HTML or PLAIN KString's, depending on this KString instance type.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The IKStringInfoProvider is looked up from the current session.

      Parameters:
      provider - The information provider or null for none.
      localeInfo - The Locale information, or null to look it up from the current thread if needed.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted KString of the same KString.Type as this instance. The return value might be this KString instance if there are no parameters available or if there is no parameter reference.
      Throws:
      KStringException - For exceptions formatting a HTML string.
      See Also:

    • formatPLAIN

      public KString formatPLAIN(Object... params)
      Formats the HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to PLAIN KString's.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The locale and potential IKStringInfoProvider provider is looked up from the current thread if required.

      Parameters:
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted PLAIN KString.
      See Also:

    • formatPLAIN

      public KString formatPLAIN(IKStringInfoProvider provider, Object... params)
      Formats the HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link Utilities#toString()} enable e.g. deep-to-String of e.g. Exceptions, Arrays, etc. Parameters references e.g. using %s will not receive this "toString" conversion (unless they target the same param_index.

      Parameters referenced by {[param_index]} that are KString types are KString's in which case they are converted to PLAIN KString's.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The locale is looked up from the current thread if required.

      Parameters:
      provider - The information provider or null to look it up for the current session.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted PLAIN KString.
      See Also:

    • formatPLAIN

      public KString formatPLAIN(Locale locale, Object... params)
      Formats a HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link toString()}, except when the parameters are KString's in which case they are converted to PLAIN KString's.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      Parameters:
      locale - The Locale, or null to look it up for the current thread if needed.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted PLAIN KString.
      See Also:

    • formatPLAIN

      public KString formatPLAIN(IKStringInfoProvider provider, Locale locale, Object... params)
      Formats a HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link toString()}, except when the parameters are KString's in which case they are converted to PLAIN KString's.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      Parameters:
      provider - The information provider or null to look it up for the current session.
      locale - The Locale, or null to look it up for the current thread if needed.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted PLAIN KString.
      See Also:

    • formatPLAIN

      public KString formatPLAIN(ILocaleString localeString, Object... params)
      Formats a HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link toString()}, except when the parameters are KString's in which case they are converted to PLAIN KString's.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The IKStringInfoProvider provider parameter is looked up from the current session.

      Parameters:
      localeString - The locale string instance, or null for current session.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted PLAIN KString.
      See Also:

    • formatPLAIN

      public KString formatPLAIN(IKStringInfoProvider provider, ILocaleString localeString, Object... params)
      Formats a HTML or PLAIN KString using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link toString()}, except when the parameters are KString's in which case they are converted to PLAIN KString's.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      Parameters:
      provider - The information provider or null to look it up for the current session.
      localeString - The locale string instance, or null for current session.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted PLAIN KString.
      See Also:

    • formatPLAIN

      public KString formatPLAIN(LocaleInfo localeInfo, Object... params)
      Formats a String using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link toString()}, except when the parameters are KString's in which case they are converted to PLAIN KString's.

      The formatting string replaces {} with %s and {param_index} with %param_index$s.

      The IKStringInfoProvider is looked up from the current session.

      Parameters:
      localeInfo - The Locale information, or null to look it up from the current thread if needed.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted PLAIN KString.
      See Also:

    • formatPLAIN

      public KString formatPLAIN(IKStringInfoProvider provider, LocaleInfo localeInfo, Object... params)
      Formats a String using curly brackets {} as parameter or {param_index} parameter where param_index is an optional one-based index value, AND/OR the Java String.format(Locale, String, Object...) method using parameters in the form of %[flags][width]conversion or %[argument_index$][flags][width]conversion.

      Parameters referenced by {[param_index]} are converted toString() using {@link toString()}, except when the parameters are KString's in which case they are converted to PLAIN KString's.

      The IKStringInfoProvider provider parameter is looked up from the current session.

      Parameters:
      provider - The information provider or null for none.
      localeInfo - The Locale information, or null to look it up from the current thread if needed.
      params - The parameters. Any params elements of KString type will be converted to a resolved KString.Type.PLAIN String using the method {@link #getPLAINString(IKStringInfoProvider)}.
      Returns:
      The formatted PLAIN KString.
      See Also:

    • getDirectReferencedTargetSet

      public final Set<IGProp<?>> getDirectReferencedTargetSet(IGProp<?> owner)
      Gets the direct references of this property to others.
      Parameters:
      owner - The owner property of the KString, used for e.g. reference look-up's.
      Returns:
      The references list instance references if non-null, or a new filled in instance. Returns null if no references are found and the references parameter also was null.