Package com.iizix.text

Class KString

  • All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Comparable<KString>
    Direct Known Subclasses:
    KStringStyled, PlainKString
    public class KString
extends java.lang.Object
implements java.lang.Cloneable, java.lang.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, Q, BLOCKQUOTE, BIG, SMALL, BDO, INS, DEL, UL, OL, LI, DL, DT, DD, TABLE, CAPTION, COL, COLGROUP, 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, FRAMESET, FRAME, NOFRAMES, PARAM, STYLE, FORM, INPUT, BUTTON, LABEL, SELECT, OPTION, OPTGROUP, TEXTAREA ISINDEX, FIELDSET, LEDGEND, CENTER, AREA, MAP. The 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

    • Nested Class Summary

      Nested Classes 
      Modifier and TypeClassDescription
      static class KString.Type
      The type of string.

    • Field Summary

      Fields 
      Modifier and TypeFieldDescription
      static KStringDEFAULT
      The default string: empty HTML.
      static KStringEMPTY
      The empty string: empty PLAIN.

    • Constructor Summary

      Constructors 
      ConstructorDescription
      KString​(KString.Type type, java.lang.String inputString)
      Creates the parsed KString where it is assumed the string can contain tags.
      KString​(KString.Type type, java.lang.String inputString, boolean usesTagProcessing)
      Creates the parsed KString.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and TypeMethodDescription
      KStringclone()
      Clones this KString.
      intcompareTo​(KString ks)
      Compares two KStrings with the raw format in their respective native format.
      static KStringcreateKString​(org.w3c.dom.Element e)
      Constructs a KString from an Element.
      static KStringcreateKStringForEditor​(java.lang.String inputString, boolean usesTagProcessing)
      Special creator for HTML-edited text in the Editor.
      voiddispose()
      Disposes of the KString, needed in the Editor when references are used.
      booleanequals​(java.lang.Object obj)
      Checks for equality between two KStrings, including reference refresh counter checking and potential original source string.
      booleanequalsOmitReferenceRefreshCheck​(KString ks)
      Checks for pure equality between two KStrings, excluding reference refresh counter checking but including potential original source string.
      protected voidfinalize()
      Called when the KString is being garbage collected.
      java.lang.StringgetHTMLString​(IKStringInfoProvider provider)
      Gets the string formatted in HTML.
      java.lang.StringgetPLAINString​(TextTable textTableBase, java.lang.String languageCode)
      Resolves the string that may contain tags to a text table.
      java.lang.StringgetPLAINString​(IKStringInfoProvider provider)
      Gets the string formatted in HTML.
      java.lang.StringgetRawHTMLString()
      Gets the "raw" HTML formatted string.
      java.lang.StringgetRawHTMLStringForEditor()
      Gets the "raw" HTML formatted string, with special formatting as required by the Rich Text Editor.
      java.lang.StringgetRawHTMLStringForEditor​(IKStringInfoProvider provider)
      Gets the "raw" HTML formatted string, with special formatting as required by the Rich Text Editor.
      java.lang.StringgetRawPLAINString()
      Gets the "raw" PLAIN formatted string.
      java.lang.StringgetRawString()
      Gets the "raw" string formatted in the "native" type, i.e.
      intgetReferences​(KStringProp owner, java.util.List<Reference> references)
      Gets the references of this property top others.
      java.lang.StringgetSource()
      Gets the source of the KString.
      KStringTag<?>getTag​(int position, boolean doIncludeStartPos)
      Gets the tag at specified position in string.
      KStringTag<?>[]getTags()
      Gets the array of tags for this string.
      KString.TypegetType()
      Gets the type of KString.
      inthashCode()
      The hash code.
      booleanhasImageReferenceTags()
      Checks for the presence of image content modifiable tags: IMG.
      booleanhasReferenceTags()
      Checks for the presence of content modifiable tags: A, IMG, IZ for HTML, or the reference tags in PLAIN format.
      booleanhasTags()
      Checks for presence of tags in the text in its original form (HTML or PLAIN).
      booleanhasTextTableReferenceTags()
      Checks for the presence of content modifiable text table reference tags.
      booleanisEmpty()
      Checks if the string is empty, i.e.
      booleanisEmptyBlankResolved​(boolean checkBlank, IKStringInfoProvider provider)
      Checks if the resolved KString of the current type would be an empty or blank string.
      booleanisHTML()
      Check if it's an HTML string originally.
      booleanisPLAIN()
      Check if it's an PLAIN string originally.
      booleanisRefreshRequired​(RefreshEvent event)
      Returns whether the KString needs a refresh for the specified refresh type.
      static PlainKStringnewPlainKString​(java.lang.String inputString)
      Creates a new PlainKString where it is assumed the string doesn't use tags.
      voidtoElement​(org.w3c.dom.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.
      PlainKStringtoPlainKString()
      Gets a PlainKString from this KString instance.
      java.lang.StringtoString()
      Formats to a String.
      booleanusesTagProcessing()
      Checks if this string uses the original value (HTML tags are always validated though).
      booleanwillLoseFormatting()
      Checks if this string will lose formatting when translated to PLAIN.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • EMPTY

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

      • DEFAULT

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

    • Constructor Detail

      • KString

        public KString​(KString.Type type,
               java.lang.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,
               java.lang.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.
        java.lang.IllegalArgumentException - If type or inputString is null.

    • Method Detail

      • newPlainKString

        public static PlainKString newPlainKString​(java.lang.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​(org.w3c.dom.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​(org.w3c.dom.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​(java.lang.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 java.lang.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 java.lang.Throwable
        Called when the KString is being garbage collected.

        The KString will be disposed if not previously disposed of.

        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.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:
        java.lang.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.

      • hasImageReferenceTags

        public boolean hasImageReferenceTags()
        Checks for the presence of image content modifiable tags: IMG.

      • 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 java.lang.String getRawString()
        Gets the "raw" string formatted in the "native" type, i.e. HTML or PLAIN.
        Returns:
        The raw native-formatted string.

      • getRawPLAINString

        public java.lang.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.

      • getRawHTMLString

        public java.lang.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.

      • getRawHTMLStringForEditor

        public java.lang.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 java.lang.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 java.lang.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 java.lang.String getPLAINString​(TextTable textTableBase,
                                       java.lang.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:
        java.lang.IllegalArgumentException - If the KString is not PLAIN or contains tags other than Text Table tags.
        java.lang.NullPointerException - If the KString contains text table tags and the textTable is null

      • getHTMLString

        public java.lang.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​(java.lang.Object obj)
        Checks for equality between two KStrings, including reference refresh counter checking and potential original source string.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - Another KString (perhaps).
        Returns:
        true if equal, false otherwise.

      • hashCode

        public int hashCode()
        The hash code.
        Overrides:
        hashCode in class java.lang.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 java.lang.Comparable<KString>
        Parameters:
        ks - Another KString.
        Returns:
        The string comparison value.

      • clone

        public KString clone()
        Clones this KString.
        Overrides:
        clone in class java.lang.Object

      • 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 java.lang.String toString()
        Formats to a String.
        Overrides:
        toString in class java.lang.Object

      • getReferences

        public int getReferences​(KStringProp owner,
                         java.util.List<Reference> references)
        Gets the references of this property top others. This method is typically used in the Designer to search for circular references during verification.
        Parameters:
        owner - The owner property of the KString.
        references - The references array is filled in by this method.
        Returns:
        The count of references added.