senselogic.sitevision.api.script

Interface ScriptUtil

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

Scripting utility interface that might be needed when using a limited scripting or template language (such as Velocity).

An instance of the Sitevision class implementing this interface can be obtained via Utils.getScriptUtil(). 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	flatten(String aString) Flattens a multi-lined string to a trimmed single-line string.
String	getCalendarAsString(String aFormatPattern, Calendar aCalendar) Deprecated. use DateUtil.getCalendarAsString(String, java.util.Calendar) instead
String	getDateAsString(String aFormatPattern, Date aDate) Deprecated. use DateUtil.getDateAsString(String, java.util.Date) instead
boolean	getFalse() Gets the boolean false primitive.
String	getFormatPattern(Locale aLocale) Deprecated. use DateUtil.getEditorFormatPattern(java.util.Locale) instead
String	getHumanPresentableSize(long aSize) Methods that returns a human presentable size with an appropriate byte-suffix (bytes/kB/MB/GB/TB).
Object	getInstance(String aQualifiedClassName) Deprecated. Use InstanceCreatorUtil.getDefaultInstance(String) instead
List	getList(Object[] anArray) Methods that wraps an array in a List.
Object	getNonBlank(String aString) Gets an object that is ensured not to be null or a whitespace only string.
Object	getNonBlank(String aString, Object aDefaultValue) Gets a default value if a string is null or whitespace only.
Object	getNonNull(Object anObject) Gets an object that is ensured not to be null.
Object	getNonNull(Object anObject, Object aDefaultValue) Gets a default value if an object is null.
Object	getNull() Gets the null reference.
String	getSystemProperty(String aName) Deprecated. Exposes server information and will therefore be removed in future releases of Sitevision
boolean	getTrue() Gets the boolean true primitive.
boolean	isBlank(String aString) Checks if a string is null, empty or whitespace only.
boolean	isEmpty(String aString) Checks if a string is null or empty.
boolean	isFalse(Object anObject) Method that returns true for values that can be interpreted as the false value.
boolean	isNotBlank(String aString) Checks if a string is not null, not empty and not whitespace only.
boolean	isNotEmpty(String aString) Checks if a string is not null and not empty.
boolean	isTrue(Object anObject) Method that returns true for values that can be interpreted as the true value.
String	joinArray(Object[] anArray, String aSeparator) Joins the elements of an array to a single String.
String	joinCollection(Collection aCollection, String aSeparator) Joins the items of a Collection to a single String.
String	messageFormat(String aMessageFormatPattern, List anArguments) A utility method to get a formatted string based on a pattern and some pattern arguments.
double	stringToDouble(String aString) Method that converts a string to a double.
float	stringToFloat(String aString) Method that converts a string to a float.
int	stringToInt(String aString) Method that converts a string to an int.
long	stringToLong(String aString) Method that converts a string to a long.
void	swallow(Object anObject) A utility method that can be used to prevent method invocation return values to be added to the Velocity output.
String	trimToEmpty(String aString) Removes leading and ending control characters (char <= 32) from a String and returns the result (empty String ("") if the string is empty or null).
String	trimToNull(String aString) Removes leading and ending control characters (char <= 32) from a String and returns the result (null if the string is empty or null).

Method Detail

getTrue

boolean getTrue()

Gets the boolean true primitive.

Returns:

true

getFalse

boolean getFalse()

Gets the boolean false primitive.

Returns:

false

getNull

Object getNull()

Gets the null reference.

Returns:

null

getNonNull

Object getNonNull(Object anObject)

Gets an object that is ensured not to be null.

This is a convenience method that can be used to avoid unnecessary subsequent method invocations in Velocity.

Velocity ignores null assignments and trying to assign a null reference will be logged as a WARNING message. A common strategy to work around this is to use the the Velocity #if clause. It allows for easy non-null checks - a null object is considered to be false. The downside with this strategy is that it requires two subsequent method invocations. That can of course be a really bad thing if the method does costly things. This method can be used to avoid such problems.

An example
This Velocity code:

    #if ($anObject.getPersonOrNull())
       #set ($person = $anObject.getPersonOrNull())
       $person.getName()
       ...
    #end

Can be better utilized as:

    #set ($scriptUtil = ...)

    #set ($person = $scriptUtil.getNonNull(${anObject.getPersonOrNull()}))
    #if ($person)
       $person.getName()
       ...
    #end
 

Parameters:

anObject - the object that might be null

Returns:

anObject if non-null, Boolean.FALSE otherwise

Since:

Sitevision 2.6.2

See Also:

getNonNull(Object, Object), getNonBlank(String)

getNonBlank

Object getNonBlank(String aString)

Gets an object that is ensured not to be null or a whitespace only string.

This is a convenience method that can be used to avoid unnecessary subsequent method invocations in Velocity.

Velocity ignores null assignments and trying to assign a null reference will be logged as a WARNING message. A common strategy to work around this is to use the the Velocity #if clause. It allows for easy non-null checks - a null object is considered to be false. The downside with this strategy is that it requires two subsequent method invocations. That can of course be a really bad thing if the method does costly things. This method can be used to avoid such problems.

An example
This Velocity code:

    #if ($anObject.getPersonNameThatCanBeNullOrEmptyOrWhitespaceOnly())
       #set ($name = $anObject.getPersonNameThatCanBeNullOrEmptyOrWhitespaceOnly())
       #if ($name.trim().length() > 0)
          <p>
             $name
          </p>
       #end
    #end

Can be better utilized as:

    #set ($scriptUtil = ...)

    #set ($name = $scriptUtil.getNonBlank(${anObject.getPersonNameThatCanBeNullOrEmptyOrWhitespaceOnly()}))
    #if ($name)
       <p>
          $name
       </p>
    #end
 

A typical example when using PropertyUtil and whitespace is an issue
This Velocity code:

    #if ($propertyUtil.getString($theNode, 'thePropertyName'))
       #set ($propertyValue = $propertyUtil.getString($theNode, 'thePropertyName'))
       #if ($propertyValue.trim().length() > 0)
          <p>
             $propertyValue
          </p>
       #end
    #end

Can be better utilized as:

    #set ($scriptUtil = ...)

    #set ($propertyValue = $scriptUtil.getNonBlank(${propertyUtil.getString($theNode, 'thePropertyName')}))
    #if ($propertyValue)
       <p>
          $propertyValue
       </p>
    #end
 

Parameters:

aString - the string that might be null or whitespace only

Returns:

aString if aString is non-null and not whitespace only, Boolean.FALSE otherwise

Since:

Sitevision 3.6

See Also:

getNonBlank(String, Object)

getNonNull

Object getNonNull(Object anObject,
                  Object aDefaultValue)

Gets a default value if an object is null.

Parameters:

anObject - the object that might be null

aDefaultValue - the default value to return if anObject is null

Returns:

anObject if non-null, aDefaultValue otherwise

Since:

Sitevision 2.6.2

See Also:

getNonNull(Object)

getNonBlank

Object getNonBlank(String aString,
                   Object aDefaultValue)

Gets a default value if a string is null or whitespace only.

Parameters:

aString - the string that might be null or whitespace only

aDefaultValue - the default value to return if aString is null or whitespace only

Returns:

aString if aString is non-null and not whitespace only, aDefaultValue otherwise

Since:

Sitevision 3.6

See Also:

getNonBlank(String)

isNotEmpty

boolean isNotEmpty(String aString)

Checks if a string is not null and not empty.

Parameters:

aString - the string to check

Returns:

true if aString is not null and not empty, false otherwise

Since:

Sitevision 2.6

See Also:

isNotBlank(String)

isEmpty

boolean isEmpty(String aString)

Checks if a string is null or empty.

Parameters:

aString - the string to check

Returns:

true if aString is null or empty, false otherwise

Since:

Sitevision 3.6.2

See Also:

isBlank(String)

isNotBlank

boolean isNotBlank(String aString)

Checks if a string is not null, not empty and not whitespace only.

Parameters:

aString - the string to check

Returns:

true if aString is not null, not empty and not whitespace only - false otherwise

Since:

Sitevision 2.6

See Also:

isNotEmpty(String)

isBlank

boolean isBlank(String aString)

Checks if a string is null, empty or whitespace only.

Parameters:

aString - the string to check

Returns:

true if aString is null, empty or whitespace only - false otherwise

Since:

Sitevision 3.6.2

See Also:

isEmpty(String)

getSystemProperty

@Deprecated
String getSystemProperty(String aName)

Deprecated. Exposes server information and will therefore be removed in future releases of Sitevision

Gets a system property. This method invokes the getProperty method of the java.lang.System class, i.e System.getProperty(String).

Important note!
This method can be used to reveal potential sensitive information about the server.

Allowed properties:

• "sitevision.version" (5.1)
• "sitevision.build" (5.1)
• "sitevision.environment.type" (5.2.1)

A legacy mode that enables the API to return all properties can be enabled using the following system property:
sitevision.api.scriptutil.legacy_system_properties=true

A tip if you need to do backward compatibility workarounds: The Sitevision version is accessible as a system property named sitevision.version.

Parameters:

aName - the name of the system property

Returns:

the value of the system property, or null if indeterminable (e.g. no accessible property named aName exist)

Since:

Sitevision 2.6_02

getInstance

@Deprecated
Object getInstance(String aQualifiedClassName)

Deprecated. Use InstanceCreatorUtil.getDefaultInstance(String) instead

Creates and returns an instance of a Java class.

Parameters:

aQualifiedClassName - a fully qualified name of the class (i.e. including packages)

Returns:

an instance of the class, or null if an instance can not be created

getList

List getList(Object[] anArray)

Methods that wraps an array in a List. Arrays are sub optimal in Velocity and JavaScript.

Parameters:

anArray - an array that needs to be wrapped

Returns:

a list containing the array elements. If the array is null, null is returned

Since:

Sitevision 2.6_06

getFormatPattern

@Deprecated
String getFormatPattern(Locale aLocale)

Deprecated. use DateUtil.getEditorFormatPattern(java.util.Locale) instead

Gets the date format pattern used in the Sitevision editor for a specific Locale.

Parameters:

aLocale - the Locale that specifies the date format pattern

Returns:

the date format pattern used in the Sitevision editor that corresponds to aLocale. If aLocale is null then the current locale (as of PortletContextUtil.getCurrentLocale()) is used to locate the format pattern. If no pattern exist for aLocale then the pattern that corresponds to Locale.ENGLISH will be returned.

Since:

Sitevision 2.6.1_02

getDateAsString

@Deprecated
String getDateAsString(String aFormatPattern,
                                   Date aDate)

Deprecated. use DateUtil.getDateAsString(String, java.util.Date) instead

Methods that formats a date according to a SimpleDateFormat pattern

Parameters:

aFormatPattern - date to string pattern according to SimpleDateFormat. If null is specified the default format is used

aDate - the Date

Returns:

returns a String representation of aDate according to aFormatPattern. Returns null if aDate is null.

Since:

Sitevision 2.6_06

getCalendarAsString

@Deprecated
String getCalendarAsString(String aFormatPattern,
                                       Calendar aCalendar)

Deprecated. use DateUtil.getCalendarAsString(String, java.util.Calendar) instead

Methods that formats the date of a calendar according to a SimpleDateFormat pattern

Parameters:

aFormatPattern - date to string pattern according to SimpleDateFormat. If null is specified the default format is used

aCalendar - the Calendar

Returns:

returns a String representation of the date of aCalendar according to aFormatPattern. Returns null if aDate is null.

Since:

Sitevision 2.6.1_02

getHumanPresentableSize

String getHumanPresentableSize(long aSize)

Methods that returns a human presentable size with an appropriate byte-suffix (bytes/kB/MB/GB/TB).

Note! This method uses two significant digits and 1024 as base. Some examples:
126 -> "130 bytes"
126975 -> "120 kB"
456456456 -> "440 MB"

Parameters:

aSize - a size that should be presented for humans

Returns:

a human presentable byte-suffixed size with two significant digits. If aSize is less than 0 or larger than 1125899906842624 (1024 TB), an empty String will be returned.

Since:

Sitevision 2.6.1_04

stringToInt

int stringToInt(String aString)

Method that converts a string to an int.

Parameters:

aString - the string to be converted

Returns:

aString as int. If aString is null or can't be converted, -1 is returned

Since:

Sitevision 2.6.1_04

stringToLong

long stringToLong(String aString)

Method that converts a string to a long.

Parameters:

aString - the string to be converted

Returns:

aString as long. If aString is null or can't be converted, -1 is returned

Since:

Sitevision 2.6.1_04

stringToDouble

double stringToDouble(String aString)

Method that converts a string to a double.

Parameters:

aString - the string to be converted

Returns:

aString as double. If aString is null or can't be converted, -1.0 is returned

Since:

Sitevision 2.6.1_04

stringToFloat

float stringToFloat(String aString)

Method that converts a string to a float.

Parameters:

aString - the string to be converted

Returns:

aString as float. If aString is null or can't be converted, -1.0 is returned

Since:

Sitevision 2.6.1_04

isTrue

boolean isTrue(Object anObject)

Method that returns true for values that can be interpreted as the true value.

Parameters:

anObject - an Object that might be interpreted as a true value

Returns:

returns true if anObject is a Boolean with a true value or a String with a "true" value, false otherwise.

Since:

Sitevision 2.6.1_04

isFalse

boolean isFalse(Object anObject)

Method that returns true for values that can be interpreted as the false value.

Parameters:

anObject - an Object that might be interpreted as a false value

Returns:

returns true if anObject is a Boolean with a false value or a String with a "false" value, false otherwise.

Since:

Sitevision 2.6.1_04

joinArray

String joinArray(Object[] anArray,
                 String aSeparator)

Joins the elements of an array to a single String.

Some examples:

    joinArray(["one", "two", "three"], ";")   -> "one;two;three"
    joinArray(["a", myTwoInteger], "-")       -> "a-2"
    joinArray(["", null, "three"], "-")       -> "--three"
    joinArray([], "-")                        -> ""
    joinArray(null, "-")                      -> null
 

Parameters:

anArray - the array that should be joined to a single string. null elements will be treated as empty ("") and for non-String elements toString() will be invoked on the element to get a string representation.

aSeparator - the separator that should delimit the elements of anArray in the resulting joined string. null will be treated as empty ("")

Returns:

the joined String. If anArray is null, null will be returned

Since:

Sitevision 2.6.1_04

See Also:

joinCollection(java.util.Collection, String)

joinCollection

String joinCollection(Collection aCollection,
                      String aSeparator)

Joins the items of a Collection to a single String.

For examples, see joinArray(Object[], String)

Parameters:

aCollection - the collection that should be joined to a single string. null items will be treated as empty ("") and for non-String items toString() will be invoked on the item to get a string representation.

aSeparator - the separator that should delimit the items of aCollection in the resulting joined string. null will be treated as empty ("")

Returns:

the joined String. If aCollection is null, null will be returned

Since:

Sitevision 2.6.1_04

See Also:

joinArray(Object[], String)

messageFormat

String messageFormat(String aMessageFormatPattern,
                     List anArguments)

A utility method to get a formatted string based on a pattern and some pattern arguments.

A Velocity example:

    #set ($instanceCreatorUtil = ...)
    #set ($scriptUtil = ...)
    #set ($searchPhrase = ...)

    ## Determine pattern
    #if ($language == 'sv')
       #set ($pattern = 'Din sökning {0} gav inga träffar')
    #else
       #set ($pattern = 'No hits for your search {0}')
    #end

    ## Set up pattern argument(s)
    #set ($argsList = $instanceCreatorUtil.list)
    $scriptUtil.swallow(${argsList.add($searchPhrase)})

    ## Format and print result
    <p>$scriptUtil.messageFormat($pattern, $argsList)</p>
 

Parameters:

aMessageFormatPattern - a pattern accepted by the Java MessageFormat class

anArguments - arguments needed by the pattern

Returns:

the result of the pattern evaluation or null if evaluation fails. Returns null if aMessageFormatPattern is null or if anArguments doesn't contain any arguments.

Since:

Sitevision 3.0

swallow

void swallow(Object anObject)

A utility method that can be used to prevent method invocation return values to be added to the Velocity output.

An example:
This Velocity code:

    #set ($myList = $instanceCreatorUtil.list)
    $myList.add("Magnus Lövgren")
    $myList.add("Mikael Wikblom")
 

will result in the following Velocity output (the add method of ArrayList returns a boolean):

true true

If a non-void method is invoked and the return value isn't handled, it will be part of the Velocity output. The swallow method can be used to prevent that (i.e. use it to "swallow" the result):

    #set ($myList = $instanceCreatorUtil.list)
    $scriptUtil.swallow(${myList.add("Magnus Lövgren")})
    $scriptUtil.swallow(${myList.add("Mikael Wikblom")})

Note! The code above is just an example that illustrates a common problem. When creating and working with a List from Velocity, you should probably use a ListWrapper instead

Parameters:

anObject - the object that should be "swallowed"

Since:

Sitevision 3.0

trimToNull

String trimToNull(String aString)

Removes leading and ending control characters (char <= 32) from a String and returns the result (null if the string is empty or null).

The String is trimmed using String.trim()

Parameters:

aString - the string that should be trimmed

Returns:

the trimmed String. Returns null if aString is null or the trimmed String is empty.

Since:

Sitevision 2.6.1_04

trimToEmpty

String trimToEmpty(String aString)

Removes leading and ending control characters (char <= 32) from a String and returns the result (empty String ("") if the string is empty or null).

The String is trimmed using String.trim()

Parameters:

aString - the string that should be trimmed

Returns:

the trimmed String. Returns empty ("") if aString is null or the trimmed String is empty.

Since:

Sitevision 2.6.1_04

flatten

String flatten(String aString)

Flattens a multi-lined string to a trimmed single-line string.

This method replaces all whitespace (space, line break and such) with a space, but will never add multiple spaces.

Parameters:

aString - the multi-lined string

Returns:

a single-line trimmed string with sequential whitespace removed, or null if aString is null.

Since:

Sitevision 3.6