senselogic.sitevision.api.text

Interface EndecUtil

@Requireable(value="EndecUtil")
public interface EndecUtil

Utility interface for encoding/decoding ("encode/decode" / "escape/unescape").

An instance of the Sitevision class implementing this interface can be obtained via Utils.getEndecUtil(). See Utils for how to obtain an instance of the Utils interface.

Author:

Magnus Lövgren

Method Summary

Modifier and Type	Method and Description
String	base64decode(String aBase64EncodedString) Decodes a base64 encoded string (using UTF-8 encoding).
byte[]	base64decodeToBytes(String aBase64EncodedString) Decodes a base64 encoded string to a byte array (using UTF-8 encoding).
String	base64encode(String aString) Encodes a string using base64 encoding (using UTF-8 encoding).
String	base64encodeToString(byte[] aBytes) Encodes a byte array to a base64 encoded string (using UTF-8 encoding).
String	br(String aString) Converts line breaks to xhtml <br /> elements.
String	decodeURL(String aURL) Decodes a URL safe String into its original form using the default charset.
String	encodeURL(String aURL) Encodes a String into its URL safe form using the default charset.
String	escapeIdentifier(String aPrefix, String anIdentifier) Escapes/encodes an identifier.
String	escapeJcrName(String aJcrName) Escapes/encodes a jcr name (property name or node name) that might contain illegal characters.
String	escapeXML(String aString) Escapes/encodes the characters in a String using XML entities.
String	getBaseSubstitute(String aString) Replaces characters to their base subtitute.
String	unEscapeHTML4(String aString) Unescapes/decodes a string containing HTML 4 entities to a string containing the actual Unicode characters corresponding to the entities.
String	unEscapeIdentifier(String aPrefix, String anIdentifier) Unescapes/decodes an escaped/encoded identifier.
String	unEscapeJcrName(String aJcrName) Unescapes/decodes a jcr name (property name or node name) that might be escape/encoded.
String	unEscapeXML(String aString) Unescapes/decodes a string containing basic XML entities to a string containing the actual Unicode characters corresponding to the entities.

Method Detail

escapeXML

String escapeXML(String aString)

Escapes/encodes the characters in a String using XML entities.

   Example: "One <br /> & two" -> "One &lt;br /&gt; &amp; two"
 

Parameters:

aString - a String that needs to be escaped

Returns:

aString escaped

unEscapeXML

String unEscapeXML(String aString)

Unescapes/decodes a string containing basic XML entities to a string containing the actual Unicode characters corresponding to the entities.

Supports the 5 basic XML entities (gt, lt, quot, amp, apos) and numerical unicodes (decimal and hex).

Examples:

[ One <br /> & two ] will become:
[ One <br /> & two ]

[ "Hej å hå" är kopieringsskyddat© sägs det ] will become:
[ "Hej å hå" är kopieringsskyddat© sägs det ]

Parameters:

aString - a String that contains escaped xml entities

Returns:

aString unescaped

See Also:

unEscapeHTML4(String)

unEscapeHTML4

String unEscapeHTML4(String aString)

Unescapes/decodes a string containing HTML 4 entities to a string containing the actual Unicode characters corresponding to the entities.

Supports HTML 4.0 entities, including numerical unicodes (decimal and hex).

Examples:

[ One <br /> & two ] will become:
[ One <br /> & two ]

[ "Hej å hå" är kopieringsskyddat© sägs det ] will become:
[ "Hej å hå" är kopieringsskyddat© sägs det ]

Parameters:

aString - a String that contains escaped html 4 entities

Returns:

aString unescaped

Since:

Sitevision 2.6.2

See Also:

unEscapeXML(String)

encodeURL

String encodeURL(String aURL)

Encodes a String into its URL safe form using the default charset.

Handles the www-form-urlencoded encoding scheme, also misleadingly known as URL encoding

Parameters:

aURL - the string to convert to a URL safe form

Returns:

an URL safe String. Returns null if aURL is null or can't be encoded.

Since:

Sitevision 2.6.1_04

decodeURL

String decodeURL(String aURL)

Decodes a URL safe String into its original form using the default charset.

Handles the www-form-urlencoded encoding scheme, also misleadingly known as URL encoding

Parameters:

aURL - URL safe String to convert to its original form

Returns:

a decoded String. Returns null if aURL is null or can't be decoded.

Since:

Sitevision 2.6.1_04

br

String br(String aString)

Converts line breaks to xhtml <br /> elements.

   Example: "Line 1\nLine 2" -> "Line 1<br />Line2"
 

Parameters:

aString - a String to convert

Returns:

aString the converted string

getBaseSubstitute

String getBaseSubstitute(String aString)

Replaces characters to their base subtitute. A name that is base substituted ensures that the name is CSS valid. Can for instance be used to get valid names for anchors (anchor links).

   Example: "xml ëBå_$-1205" -> "xmleBa1205"
 

Parameters:

aString - a String that should be base substituted

Returns:

the base substitute for aString

escapeJcrName

String escapeJcrName(String aJcrName)

Escapes/encodes a jcr name (property name or node name) that might contain illegal characters.

Any operation that includes a JCR name that contains illegal characters must be escaped. For example:

    javax.jcr.Node node = ...

    javax.jcr.NodeIterator nodeIterator = node.getNodes("aNodeNameThatShouldBeEscaped");
    javax.jcr.NodeIterator anotherNodeIterator = node.getNodes("aNodeNameThatShouldBeEscaped/aNodeNameThatShouldBeEscaped");
    javax.jcr.Property property = node.getProperty("aPropertyNameThatShouldBeEscaped");
 

Characters in JCR Names - section 3.2.5.4 of the JSR 283 specification (Java Content Repository 2.0)

Illegal character	Substitution character
* (U+002A) "asterix"	U+F02A
/ (U+002F) "slash"	U+F02F
: (U+003A) "colon"	U+F03A
[ (U+005B) "left bracket"	U+F05B
] (U+005D) "right bracket"	U+F05D
| (U+007C) "pipe"	U+F07C

Some specific names are conflicting with the JCR naming semantics and must also be escaped:
(though, these two "dot-only" expressions would typically be extremely uncommon as names)

Illegal Name	Substitution Name
"." (the JCR Self Notation)	U+F02E
".." (the JCR Parent Notation)	U+F02E and U+F02E

Parameters:

aJcrName - a name that should be escaped/encoded

Returns:

aJcrName escaped/encoded

See Also:

unEscapeJcrName(String)

unEscapeJcrName

String unEscapeJcrName(String aJcrName)

Unescapes/decodes a jcr name (property name or node name) that might be escape/encoded.

Any operation that includes getting a JCR name must be unescaped if it contains illegal characters. For example:

    javax.jcr.Node node = ...
    javax.jcr.Property property = ...

    java.lang.String aNameThatNeedsToBeUnEscaped = node.getName();
    java.lang.String anotherNameThatNeedsToBeUnEscaped = property.getName();
 

See escapeJcrName(String) for escape/unescape characters and names

Parameters:

aJcrName - a name that might be escaped/encoded

Returns:

aJcrName unescaped/decoded

See Also:

escapeJcrName(String)

base64encode

String base64encode(String aString)

Encodes a string using base64 encoding (using UTF-8 encoding).

Parameters:

aString - a String that should be base64 encoded

Returns:

aString base64 encoded. Returns null if aString is null

Since:

Sitevision 2.6

See Also:

base64decode(String)

base64encodeToString

String base64encodeToString(byte[] aBytes)

Encodes a byte array to a base64 encoded string (using UTF-8 encoding).

Parameters:

aBytes - a byte array that should be base64 encoded as string

Returns:

aBytes as base64 encoded string, using UTF-8 encoding. Returns null if aBytes is null

Since:

Sitevision 4.5.5.2

See Also:

base64encode(String)

base64decode

String base64decode(String aBase64EncodedString)

Decodes a base64 encoded string (using UTF-8 encoding).

Parameters:

aBase64EncodedString - a base64 encoded String

Returns:

aBase64EncodedString base64 decoded. Returns null if aBase64EncodedString is null or can't be decoded.

Since:

Sitevision 2.6

See Also:

base64encode(String)

base64decodeToBytes

byte[] base64decodeToBytes(String aBase64EncodedString)

Decodes a base64 encoded string to a byte array (using UTF-8 encoding).

Parameters:

aBase64EncodedString - a base64 encoded String

Returns:

aBase64EncodedString base64 decoded as byte array, using UTF-8 encoding. Returns null if aBase64EncodedString is null or can't be decoded.

Since:

Sitevision 4.5.5.2

See Also:

base64decode(String)

escapeIdentifier

String escapeIdentifier(String aPrefix,
                        String anIdentifier)

Escapes/encodes an identifier.

Some examples

aPrefix	anIdentifier	Returned
null	null	""
""	null	""
null	""	""
""	""	""
"pcx"	null	"pcx"
null	"pcx"	"pcx"
"pcx"	""	"pcx"
"pcx"	"123"	"pcx123"
"pcx"	"1.23"	"pcx1_23"
"pcx"	"1.23.45"	"pcx1_23_45"

Parameters:

aPrefix - a prefix added to the result

anIdentifier - a string id

Returns:

a non-null prefixed and escaped string identifier

Since:

Sitevision 3.0.2

See Also:

unEscapeIdentifier(String, String)

unEscapeIdentifier

String unEscapeIdentifier(String aPrefix,
                          String anIdentifier)

Unescapes/decodes an escaped/encoded identifier.

Some examples

aPrefix	anIdentifier	Returned
null	null	""
""	null	""
null	""	""
""	""	""
"pcx"	null	""
null	"pcx"	"pcx"
"pcx"	""	""
"pcx"	"pcx123"	"123"
"pcx"	"pcx1_23"	"1.23"
"pcx"	"pcx1_23_45"	"1.23.45"
null	"pcx1_23"	"pcx1.23"
""	"pcx1_23"	"pcx1.23"
"badprefix"	"pcx1_23"	"pcx1.23"

Parameters:

aPrefix - a prefix that will be removed from the result

anIdentifier - a string id

Returns:

an unescaped non-null identifier

Since:

Sitevision 3.0.2

See Also:

escapeIdentifier(String, String)