com.xpn.xwiki.api
Class Util

java.lang.Object
  extended by com.xpn.xwiki.api.Api
      extended by com.xpn.xwiki.api.Util

public class Util
extends Api

Utility APIs, available to scripting environments under the util variable.

Version:
$Id: ed0a15625c3c5b3a27ba5009d8e72ba9f4e55e61 $

Field Summary
 
Fields inherited from class com.xpn.xwiki.api.Api
context
 
Constructor Summary
Util(com.xpn.xwiki.XWiki xwiki, com.xpn.xwiki.XWikiContext context)
          Simple constructor, initializes a new utility API with the current context and the current global XWiki object.
 
Method Summary
 int add(int a, int b)
          Add two integer numbers.
 long add(long a, long b)
          Add two long numbers.
 String add(String a, String b)
          Add two numbers, specified as strings.
 String clearAccents(String text)
          Replace all accented characters by their ASCII equivalent.
 String clearName(String documentName)
          Cleans up the passed text by removing all accents and special characters to make it a valid page name.
 String convertToAlphaNumeric(String text)
          Removes all non alpha numerical characters from the passed text.
 String decodeURI(String text)
          Decodes a application/x-www-form-urlencoded string, the reverse of encodeURI(String).
 String encodeURI(String text)
          Translates a string into application/x-www-form-urlencoded format, so that it can be safely used in a query string as a parameter value.
 String escapeSQL(String text)
          Escape text so that it can be used in a HQL/SQL query, in a like clause or in a test for equality clause.
 String escapeText(String text)
          Protect Text from Wiki transformation.
 String escapeURL(String url)
          Protect URLs from Wiki transformation.
 String generateRandomString(int size)
          Generate a random string, containing only alpha-numeric characters.
<T> List<T>
getArrayList()
          Creates an ArrayList.
 Date getDate()
          Creates a new Date object corresponding to the current time.
 Date getDate(long time)
          Creates a new Date object corresponding to the specified time.
<T,U> Map<T,U>
getHashMap()
          Creates a HashMap, a generic map implementation optimized for performance.
<T,U> Map<T,U>
getLinkedHashMap()
          Creates a LinkedHashMap, a map implementation which preserves the order of insertion.
 String getNewline()
          Get a New Line character.
 Object getNull()
          Get a Null value.
 int getTimeDelta(long time)
          Compute the elapsed time, in milliseconds, since the specified unix-epoch timestamp.
<T,U> Map<T,U>
getTreeMap()
          Creates a TreeMap, a map implementation which always maintains the natural order of the elements.
 void outputImage(BufferedImage image)
          Output a BufferedImage object into the response outputstream.
 Boolean parseBoolean(String str)
          Convert a String to a Boolean object.
 double parseDouble(String str)
          Convert a String to a primitive double.
 float parseFloat(String str)
          Convert a String to a primitive float.
 int parseInt(String str)
          Convert a String to a primitive int.
 Integer parseInteger(String str)
          Convert a String to an Integer object.
 long parseLong(String str)
          Convert a String to a primitive long.
 String printStrackTrace(Throwable e)
          Get a stack trace as a String.
<T> List<T>
reverseList(List<T> list)
          Reverse the order of the elements within a list, so that the last element is moved to the beginning of the list, the next-to-last element to the second position, and so on.
<T extends Comparable<T>>
List<T>
sort(List<T> list)
          Sort a list using a standard comparator.
 String[] split(String text, String separator)
          Split a text into an array of texts, according to a list of separator characters.
 Number toNumber(Object object)
          Convert an Object to a number and return null if the object is not a Number.
 
Methods inherited from class com.xpn.xwiki.api.Api
convert, convert, getXWikiContext, hasAccessLevel, hasAdminRights, hasProgrammingRights, hasWikiAdminRights
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Util

public Util(com.xpn.xwiki.XWiki xwiki,
            com.xpn.xwiki.XWikiContext context)
Simple constructor, initializes a new utility API with the current context and the current global XWiki object.

Parameters:
xwiki - the current global XWiki object
context - the current context
See Also:
Api.Api(com.xpn.xwiki.XWikiContext)
Method Detail

escapeText

public String escapeText(String text)
Protect Text from Wiki transformation. This method is useful for preventing content generated with Velocity from being interpreted in the xwiki/1.0 rendering engine, and should not be used in xwiki/2.0 code. The result is valid only in HTML or XML documents.

Parameters:
text - the text to escape
Returns:
the escaped text
Since:
1.3 Milestone 2

escapeURL

public String escapeURL(String url)
Protect URLs from Wiki transformation. This method is useful for preventing content generated with Velocity from being interpreted in the xwiki/1.0 rendering engine, and should not be used in xwiki/2.0 code. The result is valid only in HTML or XML documents.

Parameters:
url - the url to escape
Returns:
the encoded URL, which can be used in the HTML output
Since:
1.3 Milestone 2

encodeURI

public String encodeURI(String text)
Translates a string into application/x-www-form-urlencoded format, so that it can be safely used in a query string as a parameter value.

Parameters:
text - the non encoded text
Returns:
encoded text
Since:
1.3 Milestone 2
See Also:
decodeURI(String)

decodeURI

public String decodeURI(String text)
Decodes a application/x-www-form-urlencoded string, the reverse of encodeURI(String).

Parameters:
text - the encoded text
Returns:
decoded text
Since:
1.3 Milestone 2
See Also:
encodeURI(String)

getArrayList

public <T> List<T> getArrayList()
Creates an ArrayList. This is useful from Velocity since new objects cannot be created.

Returns:
an ArrayList object
Since:
1.3 Milestone 2

getHashMap

public <T,U> Map<T,U> getHashMap()
Creates a HashMap, a generic map implementation optimized for performance. This is useful from Velocity since new objects cannot be created.

Returns:
a HashMap object
Since:
1.3 Milestone 2

getTreeMap

public <T,U> Map<T,U> getTreeMap()
Creates a TreeMap, a map implementation which always maintains the natural order of the elements. This is useful from Velocity since new objects cannot be created.

Returns:
a TreeMap object
Since:
1.3 Milestone 2

getLinkedHashMap

public <T,U> Map<T,U> getLinkedHashMap()
Creates a LinkedHashMap, a map implementation which preserves the order of insertion. This is useful from Velocity since new objects cannot be created.

Returns:
a LinkedHashMap object
Since:
2.2 Milestone 1

getDate

public Date getDate()
Creates a new Date object corresponding to the current time. This is useful from Velocity since new objects cannot be created.

Returns:
the current date
Since:
1.3 Milestone 2

getDate

public Date getDate(long time)
Creates a new Date object corresponding to the specified time. This is useful from Velocity since new objects cannot be created.

Parameters:
time - time in milliseconds since 1970, 00:00:00 GMT
Returns:
Date a date from a time in milliseconds since 01/01/1970 as a Java Date Object
Since:
1.3 Milestone 2

getTimeDelta

public int getTimeDelta(long time)
Compute the elapsed time, in milliseconds, since the specified unix-epoch timestamp. This is useful from Velocity since new objects cannot be created.

Parameters:
time - the time in milliseconds
Returns:
the time delta in milliseconds between the current date and the time passed as parameter
Since:
1.3 Milestone 2

split

public String[] split(String text,
                      String separator)
Split a text into an array of texts, according to a list of separator characters.

Parameters:
text - the original text
separator - the separator characters
Returns:
an array containing the resulting text fragments
Since:
1.3 Milestone 2

reverseList

public <T> List<T> reverseList(List<T> list)
Reverse the order of the elements within a list, so that the last element is moved to the beginning of the list, the next-to-last element to the second position, and so on. This is useful from Velocity since classes and their static methods cannot be accessed.

Parameters:
list - the list to reverse
Returns:
the reversed list
Since:
1.4 Milestone 1

printStrackTrace

public String printStrackTrace(Throwable e)
Get a stack trace as a String.

Parameters:
e - the exception to convert to a String
Returns:
the exception stack trace as a String
Since:
1.3 Milestone 2

sort

public <T extends Comparable<T>> List<T> sort(List<T> list)
Sort a list using a standard comparator. Elements need to be mutually comparable and implement the Comparable interface. This is useful from Velocity since classes and their static methods cannot be accessed.

Parameters:
list - the list to sort
Returns:
the sorted list (as the same object reference)
Since:
1.3 Milestone 2
See Also:
java.util.Collections#sort(java.util.List)}

generateRandomString

public String generateRandomString(int size)
Generate a random string, containing only alpha-numeric characters.

Parameters:
size - the desired size of the string
Returns:
the randomly generated string
Since:
1.3 Milestone 2

outputImage

public void outputImage(BufferedImage image)
                 throws IOException
Output a BufferedImage object into the response outputstream. Once this method has been called, no further action is possible. Users should set $context.setFinished(true) to avoid template output. The image is served as image/jpeg.

Parameters:
image - the BufferedImage to output
Throws:
IOException - if the output fails
Since:
1.3 Milestone 2

getNull

public Object getNull()
Get a Null value. This is useful in Velocity where there is no real null object for comparisons.

Returns:
a null Object
Since:
1.3 Milestone 2

getNewline

public String getNewline()
Get a New Line character. This is useful in Velocity where there is no real new line character for inclusion in texts.

Returns:
a new line character
Since:
1.3 Milestone 2

toNumber

public Number toNumber(Object object)
Convert an Object to a number and return null if the object is not a Number.

Parameters:
object - the object to convert
Returns:
the object as a Number, or null
Since:
1.3 Milestone 2

parseBoolean

public Boolean parseBoolean(String str)
Convert a String to a Boolean object.

Parameters:
str - the String containing the boolean representation to be parsed
Returns:
the boolean represented by the string argument, false if the string is not representing a boolean
Since:
1.8 Milestone 2

parseInt

public int parseInt(String str)
Convert a String to a primitive int.

Parameters:
str - the String to convert to an integer
Returns:
the parsed integer or zero if the string is not a valid integer number
Since:
1.3 Milestone 2

parseInteger

public Integer parseInteger(String str)
Convert a String to an Integer object.

Parameters:
str - the String to convert to an Integer Object
Returns:
the parsed integer or zero if the string is not a valid integer number
Since:
1.3 Milestone 2

parseLong

public long parseLong(String str)
Convert a String to a primitive long.

Parameters:
str - the String to convert to a long
Returns:
the parsed long or zero if the string is not a valid long number
Since:
1.3 Milestone 2

parseFloat

public float parseFloat(String str)
Convert a String to a primitive float.

Parameters:
str - the String to convert to a float
Returns:
the parsed float or zero if the string is not a valid float number
Since:
1.3 Milestone 2

parseDouble

public double parseDouble(String str)
Convert a String to a primitive double.

Parameters:
str - the String to convert to a double
Returns:
the parsed double or zero if the string is not a valid double number
Since:
1.3 Milestone 2

escapeSQL

public String escapeSQL(String text)
Escape text so that it can be used in a HQL/SQL query, in a like clause or in a test for equality clause. For example it escapes single quote characters.

Parameters:
text - the text to escape
Returns:
filtered text
Since:
1.3 Milestone 2

clearAccents

public String clearAccents(String text)
Replace all accented characters by their ASCII equivalent.

Parameters:
text - the text to parse
Returns:
a string with accents replaced with their alpha equivalent
Since:
1.3 Milestone 2

add

public int add(int a,
               int b)
Add two integer numbers. Useful in Velocity, since arithmetical operations are not always working.

Parameters:
a - the first number to add
b - the second number to add
Returns:
the sum of the two parameters
Since:
1.3 Milestone 2

add

public long add(long a,
                long b)
Add two long numbers. Useful in Velocity, since arithmetical operations are not always working.

Parameters:
a - the first number to add
b - the second number to add
Returns:
the sum of the two parameters
Since:
1.3 Milestone 2

add

public String add(String a,
                  String b)
Add two numbers, specified as strings. Useful in Velocity, since arithmetical operations are not always working.

Parameters:
a - a string representing a number to add
b - a string representing a number to add
Returns:
the sum of the two parameters, as a String
Since:
1.3 Milestone 2

clearName

public String clearName(String documentName)
Cleans up the passed text by removing all accents and special characters to make it a valid page name.

Parameters:
documentName - the document name to normalize
Returns:
the equivalent valid document name
Since:
1.3 Milestone 2

convertToAlphaNumeric

public String convertToAlphaNumeric(String text)
Removes all non alpha numerical characters from the passed text. First tries to convert accented chars to their ASCII representation. Then it removes all the remaining non-alphanumeric non-ASCII characters.

Parameters:
text - the text to convert
Returns:
the alpha numeric equivalent
Since:
1.3 Milestone 2


Copyright © 2004-2011 XWiki. All Rights Reserved.