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. The tag table is one flat set, so every SVG tag is accepted in HTML context as well.
  5. Additionally, the IZ tag is defined as described below.
  6. A KString comes in three kinds, and the kind decides what the parser admits (see KString.Kind):
    • The classical kind, created by every constructor of this class, is SAFE by default: SCRIPT, IFRAME, STYLE and FOREIGNOBJECT are refused; every attribute whose name starts with "on" is refused except "onclick" and "ondblclick", whose value must be a VirtualSpace component reference of the hyperlink machinery (or the client's generated handler for one); URL attributes such as "href" and "src" refuse the "javascript:", "vbscript:" and non-image "data:" schemes; an SVG animation may not retarget a URL or an event attribute. Text that did not come from the application's author belongs in this kind.
    • The trusted kind, created by newTrustedHTMLKString(String,boolean), is for HTML the application vouches for: the four tags above are accepted and no attribute value is inspected; the two event attribute names remain the only "on" names accepted. It parses, resolves references, formats and verifies exactly as the classical kind does.
    • The trusted unparsed kind, created by newTrustedUnparsedHTMLKString(String), is never parsed: a whole page of generated markup passed to the client as it is, with no tags, no references and no formatting.
    The kind survives cloning, formatting, the file (attribute "trusted") and the wire between Java peers, and the kinds compare unequal. "style" attributes are carried through uninspected in every kind. A KString of the classical kind does not need escaping of its text for safety, but text that is meant as TEXT must still be escaped (see HTMLUtilities.escapeString(String,boolean)) or it is parsed as markup.
  7. The following tags are not allowed to have a close tag (e.g. </BR>): BR, IZ.

Unsupported tags: LINK, HEAD, NOSCRIPT, TITLE, META, BODY, HTML, OBJECT, APPLET, BASE, DATALIST, DIALOG, DIR, FRAMESET, FRAME, NOFRAMES, PARAM, 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). Every reference is carried by the "ref" attribute; the type strings are the lower-case ones below, as the tag factory matches them:

IZ type="tt" ref="textID"
Reference to the text table with the full text ID "id".
IZ type="vs" ref="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.
A ref="fullPath" type="resource|vs|panel" [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.
  • panel
    link changes to another panel.
A type="external" href="url"
An ordinary hyperlink to a URL outside the application; the only A form that uses "href".
There is no "connector" type: it is refused in HTML ("Unknown IZ HTML tag type") and in PLAIN ("Unknown tag: connector"), see the register entry IIZI-KSTRING-CONNECTOR-TAG-ABSENT.
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. NOT IMPLEMENTED: refused by the parser ("Unknown tag: connector") until a connector tag exists (register entry IIZI-KSTRING-CONNECTOR-TAG-ABSENT).

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.

    • MAX_WIRE_LENGTH

      public static final int MAX_WIRE_LENGTH
      The longest KString a transaction may carry, in characters (4 Mi). The parser itself has no limit - it is iterative and linear - so the bound sits where untrusted input arrives: a longer string is refused by readFromTransaction(PropMgr,ReadTransaction,Type,boolean).
      See Also:

  • 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.

    • newTrustedHTMLKString

      public static KString newTrustedHTMLKString(String html, boolean usesTagProcessing) throws KStringException
      Creates a new parsed HTML KString of the trusted kind (KString.Kind.TRUSTED): HTML the application vouches for. The parser accepts SCRIPT, IFRAME, STYLE and FOREIGNOBJECT and inspects no attribute value; the attribute NAME rule is the classical one (only "onclick" and "ondblclick" of the event attributes). References inside it are resolved, refactoring follows renames, format(Object...) works and verification reports broken references, as for the classical kind.

      Never put text that did not come from the application's author into a trusted KString: escape it first (see HTMLUtilities.escapeString(String,boolean)) or parse it as a classical KString and insert its getRawHTMLString().

      Parameters:
      html - The HTML string.
      usesTagProcessing - Flag indicating special IIZI tags might be included.
      Returns:
      The trusted KString of HTML type.
      Throws:
      KStringException - For string errors.
      KStringParseException - For parsing errors.
      IllegalArgumentException - If html is null.

    • newTrustedUnparsedHTMLKString

      public static KString newTrustedUnparsedHTMLKString(String rawUnparsedString)
      Creates a new HTML KString of the trusted unparsed kind (KString.Kind.TRUSTED_UNPARSED): a whole page of generated markup the application vouches for, passed to the client exactly as it is.

      Its limits: it is never parsed, so it has no tags, no references are resolved (IZ, A type="vs"/"panel", IMG with an application source stay as written), refactoring does not follow renames, format(Object...) is not available, verification cannot report anything, and equals(Object) compares the source text. It is born disposed. It is the performance path for large generated HTML (a parse costs about 0.4 ms for a 25 KB page and 16 ms for a 180 KB one; this factory costs a reference assignment).

      Parameters:
      rawUnparsedString - The raw unparsed HTML string.
      Returns:
      The trusted unparsed KString of HTML type.
      Throws:
      NullPointerException - If the rawUnparsedString is null.

    • newRawUnparsedHTMLKString

      @Deprecated public static KString newRawUnparsedHTMLKString(String rawUnparsedString)
      Deprecated.
      The raw unparsed KString is the trusted unparsed kind: use newTrustedUnparsedHTMLKString(String), which says what it is.
      Creates a new HTML unparsed raw HTML string.
      Parameters:
      rawUnparsedString - The raw unparsed HTML string.
      Returns:
      The KString of HTML type, of the trusted unparsed kind.

    • createKString

      public static KString createKString(Element e) throws KStringException
      Constructs a KString from an Element. The kind is read from the "trusted" attribute: absent or "false" is the classical kind, "true" the trusted kind, "unparsed" the trusted unparsed kind (whose "value" is the source).
      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. The classical kind writes "value", "type" and "tags"; the trusted kinds add the "trusted" attribute, so a file written by a classical value is what it always was.
      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.

    • createKStringForEditor

      public static KString createKStringForEditor(String inputString, boolean usesTagProcessing, boolean trusted) throws KStringException
      Special creator for HTML-edited text in the Editor, of the classical or the trusted kind. 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.
      trusted - true for the trusted kind (the property being edited holds one), false for classical.
      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.

    • getRawUnparsedHTMLString

      public String getRawUnparsedHTMLString()
      Returns the raw unparsed HTML string if this is the trusted unparsed kind (see newTrustedUnparsedHTMLKString(String)).
      Returns:
      The raw unparsed HTML string, or null if this is a parsed KString of any kind.

    • getType

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

    • getKind

      public KString.Kind getKind()
      Gets the kind of KString: what its parser admitted. The kind is the class, not a field; the trusted kinds override this method.
      Returns:
      KString.Kind.CLASSICAL for every KString created by a constructor of this class.

    • isTrusted

      public final boolean isTrusted()
      Checks if this KString is of a trusted kind, parsed or unparsed.
      Returns:
      true for KString.Kind.TRUSTED and KString.Kind.TRUSTED_UNPARSED, false for the classical kind.

    • appendToTransaction

      public static void appendToTransaction(PropMgr propertyManager, SendTransaction trans, KString ks, String wireString)
      Appends a KString to a transaction: the one wire form of every property that carries a KString (KStringProp, the tooltip and the badge). To a JavaScript client the string alone is sent, as always. To a Java peer (PropMgr.hasJavaScriptClient() false) one flags byte precedes the string and carries the kind (bit 0 trusted, bit 1 unparsed), so that a trusted KString stays trusted across a Java-to-Java link.
      Parameters:
      propertyManager - The property manager of the link.
      trans - The transaction to append to.
      ks - The KString whose kind is carried, or null for none (the classical flags).
      wireString - The string to send: the resolved HTML or PLAIN text, or the unparsed source.

    • readFromTransaction

      public static KString readFromTransaction(PropMgr propertyManager, ReadTransaction trans, KString.Type type, boolean usesTagProcessing) throws KStringException
      Reads a KString from a transaction: the counterpart of appendToTransaction(PropMgr,SendTransaction,KString,String). From a JavaScript client the string alone is read and the result is always of the classical kind: a client can craft any byte, so no flag is honoured from it. From a Java peer the flags byte is read first and decides the kind.
      Parameters:
      propertyManager - The property manager of the link.
      trans - The transaction to read from.
      type - The type to create, PLAIN or HTML.
      usesTagProcessing - Flag indicating special IIZI tags might be included.
      Returns:
      The KString of the kind the peer sent (classical from a JavaScript client).
      Throws:
      KStringException - For a string longer than MAX_WIRE_LENGTH, for invalid flags (a bit outside the two, "unparsed" without "trusted", a trusted flag with the PLAIN type), and for string or parsing errors.
      KStringParseException - For parsing errors.

    • 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", the kind 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. Equal strings of different kinds order classical, trusted, trusted unparsed.

    • 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. The ARRAY is a copy; the tag objects in it are the KString's own, so a write through one of them (setAttribute, setReference) changes this KString - that is the route the refactoring machinery uses. For an independent copy use getTagsCopy().
      Returns:
      The array of tags for this string, null for none.

    • getTagsCopy

      public KStringTag<?>[] getTagsCopy()
      Gets an independent copy of the tags of this string: a new array of cloned tag objects, so that writing through them leaves this KString untouched.
      Returns:
      The copied tags, 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.

      In a PLAIN KString created WITH tag processing the tag parser claims a single opening brace, so the placeholder is written with that brace doubled: {{} and {{n} (the parser keeps one brace and this method then sees {} / {n}); a bare {} is refused ("Missing tag name"). HTML strings and PLAIN strings without tag processing take {} as written.

      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.

      In a PLAIN KString created WITH tag processing the tag parser claims a single opening brace, so the placeholder is written with that brace doubled: {{} and {{n} (the parser keeps one brace and this method then sees {} / {n}); a bare {} is refused ("Missing tag name"). HTML strings and PLAIN strings without tag processing take {} as written.

      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.