InstanceCreatorUtil (Sitevision API)

```
@Requireable(value="InstanceCreatorUtil")
public interface InstanceCreatorUtil
```
Instance creation utility that can be used in limited scripting languages (such as Velocity).
This interface contains 5 categories of methods:
1. Methods for creating an object instance via a constructor (or an Enum instance via an enum name), e.g. see:
  getDefaultInstance(String)
  getArgumentInstance(String, TypedArgument)
  getArgumentsInstance(String, java.util.List)
  getEnumInstance(String, String)
2. Methods needed to properly describe constructor arguments for the first category above, e.g see:
  getObjectArgument(Object)
  getNullArgument(String)
  getCustomArgument(String, Object)
  getIntArgument(int)
  ...
3. Methods that creates wrappers for certain non-instantiable classes (enables instance-level invocation on their static methods), e.g. see:
  getArraysInstance()
  getCollectionsInstance()
  getMathInstance()
4. Convenience methods for creating common object instances or helpers, e.g. see:
  getList()
  getMap()
  getLinkedMap()
  getSet()
  getListWrapper()
5. Methods to create Java arrays, e.g see:
  getBooleanArray(int)
  getByteArray(int)
  getCharArray(int)
  getDoubleArray(int)
  getFloatArray(int)
  getIntArray(int)
  getLongArray(int)
  getObjectArray(int)
  getShortArray(int)
  getStringArray(int)
An instance of the Sitevision class implementing this interface can be obtained via Utils.getInstanceCreatorUtil(). See Utils for how to obtain an instance of the Utils interface.
Since:

Sitevision 3.1

Author:

Magnus Lövgren

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Object`	`getArgumentInstance(String aQualifiedClassName, TypedArgument aConstructorArgument)` Creates and returns an instance of a specified Java class using a single argument constructor.
`Object`	`getArgumentsInstance(String aQualifiedClassName, List<TypedArgument> aConstructorArguments)` Creates and returns an instance of a specified Java class using a multiple argument constructor.
`ArraysInstance`	`getArraysInstance()` Gets a `java.util.Arrays` wrapper instance.
`TypedArgument`	`getBooleanArgument(boolean aBoolean)` Gets a typed argument for a `boolean` primitive.
`boolean[]`	`getBooleanArray(int aSize)` Creates a boolean array with a given size.
`TypedArgument`	`getByteArgument(byte aByte)` Gets a typed argument for a `byte` primitive.
`byte[]`	`getByteArray(int aSize)` Creates a byte array with a given size.
`TypedArgument`	`getCharArgument(char aChar)` Gets a typed argument for a `char` primitive.
`char[]`	`getCharArray(int aSize)` Creates a char array with a given size.
`CollectionsInstance`	`getCollectionsInstance()` Gets a `java.util.Collections` wrapper instance.
`TypedArgument`	`getCustomArgument(String aQualifiedClassName, Object aValue)` Gets a typed argument that specifies a certain class/interface for an object.
`Object`	`getDefaultInstance(String aQualifiedClassName)` Creates and returns an instance of a specified Java class using the default constructor.
`TypedArgument`	`getDoubleArgument(double aDouble)` Gets a typed argument for a `double` primitive.
`double[]`	`getDoubleArray(int aSize)` Creates a double array with a given size.
`TypedArgument`	`getEnumArgument(String aQualifiedEnumClassName, Object anEnum)` Gets a typed argument for an `Enum` value for a specified enum class.
`Enum`	`getEnumInstance(String aQualifiedEnumClassName, String anEnumName)` Gets an enum instance for a specified enum class.
`TypedArgument`	`getFloatArgument(float aFloat)` Gets a typed argument for a `float` primitive.
`float[]`	`getFloatArray(int aSize)` Creates a float array with a given size.
`TypedArgument`	`getIntArgument(int anInt)` Gets a typed argument for a `int` primitive.
`int[]`	`getIntArray(int aSize)` Creates a int array with a given size.
`Map`	`getLinkedMap()` Convenience method to get a `LinkedHashMap` instance.
`List`	`getList()` Convenience method to get an `ArrayList` instance.
`ListWrapper`	`getListWrapper()` Gets a `ListWrapper` instance.
`TypedArgument`	`getLongArgument(long aLong)` Gets a typed argument for a `long` primitive.
`long[]`	`getLongArray(int aSize)` Creates a long array with a given size.
`Map`	`getMap()` Convenience method to get a `HashMap` instance.
`MathInstance`	`getMathInstance()` Gets a `java.lang.Math` wrapper instance.
`TypedArgument`	`getNullArgument(String aQualifiedClassName)` Gets a typed argument for a `null` value for a specified class/interface.
`TypedArgument`	`getObjectArgument(Object aValue)` Gets a typed argument for an `Object`.
`Object[]`	`getObjectArray(int aSize)` Creates a Object array with a given size.
`Set`	`getSet()` Convenience method to get a `HashSet` instance.
`TypedArgument`	`getShortArgument(short aShort)` Gets a typed argument for a `short` primitive.
`short[]`	`getShortArray(int aSize)` Creates a short array with a given size.
`String[]`	`getStringArray(int aSize)` Creates a String array with a given size.

- Method Detail
  - getDefaultInstance
```
Object getDefaultInstance(String aQualifiedClassName)
```
    Creates and returns an instance of a specified Java class using the default constructor.
    Example of how to create a Date instance in Velocity:
```
   #set ($instanceCreatorUtil = $sitevisionUtils.instanceCreatorUtil)
   #set ($now = $instanceCreatorUtil.getDefaultInstance('java.util.Date'))
 
```
    Note! This method will not create any objects of any classes that has a fully qualified class name that starts with senselogic.sitevision and resides outside the api package.
    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
    
    See Also:
    
    getArgumentInstance(String, TypedArgument), getArgumentsInstance(String, java.util.List)
  - getArgumentInstance
```
Object getArgumentInstance(String aQualifiedClassName,
                           TypedArgument aConstructorArgument)
```
    Creates and returns an instance of a specified Java class using a single argument constructor.
    Example of how to create an StringBuilder instance with the initial capacity 500 in Velocity (i.e. invoke the StringBuilder(int) constructor):
```
   #set ($instanceCreatorUtil = $sitevisionUtils.instanceCreatorUtil)
   #set ($capacityIntArgument = $instanceCreatorUtil.getIntArgument(500))
   #set ($buffer = $instanceCreatorUtil.getArgumentInstance('java.lang.StringBuilder', $capacityIntArgument))
 
```
    Note! This method will not create any objects of any classes that has a fully qualified class name that starts with senselogic.sitevision and resides outside the api package.
    Parameters:
    
    aQualifiedClassName - a fully qualified name of the class (i.e. including packages)
    
    aConstructorArgument - a typed argument that describes the value and the type of the constructor argument
    
    Returns:
    
    an instance of the class, or null if an instance can not be created
    
    See Also:
    
    getDefaultInstance(String), getArgumentsInstance(String, java.util.List)
  - getArgumentsInstance
```
Object getArgumentsInstance(String aQualifiedClassName,
                            List<TypedArgument> aConstructorArguments)
```
    Creates and returns an instance of a specified Java class using a multiple argument constructor.
    Example of how to create an Locale instance with language "en" and country "US" in Velocity (i.e. invoke the Locale(String,String) constructor):
```
   #set ($instanceCreatorUtil = $sitevisionUtils.instanceCreatorUtil)

   ## Set up arguments
   #set ($args = $instanceCreatorUtil.listWrapper) ## Use ListWrapper to prohibit output when invoking the "add" method...
   $args.add($instanceCreatorUtil.getObjectArgument('en')) ## Add first argument (language)
   $args.add($instanceCreatorUtil.getObjectArgument('US')) ## Add second argument (country)

   ## Create instance with arguments
   #set ($americanLocale = $instanceCreatorUtil.getArgumentsInstance('java.util.Locale', $args.unwrap())) ## unwrap() to get actual List
 
```
    Note! This method will not create any objects of any classes that has a fully qualified class name that starts with senselogic.sitevision and resides outside the api package.
    Parameters:
    
    aQualifiedClassName - a fully qualified name of the class (i.e. including packages)
    
    aConstructorArguments - a list of typed arguments that describes the values and types of the constructor arguments
    
    Returns:
    
    an instance of the class, or null if an instance can not be created
    
    See Also:
    
    getDefaultInstance(String), getArgumentInstance(String, TypedArgument)
  - getByteArgument
```
TypedArgument getByteArgument(byte aByte)
```
    Gets a typed argument for a byte primitive.
    
    Parameters:
    
    aByte - a byte value
    
    Returns:
    
    a typed argument for the byte primitive.
  - getShortArgument
```
TypedArgument getShortArgument(short aShort)
```
    Gets a typed argument for a short primitive.
    
    Parameters:
    
    aShort - a short value
    
    Returns:
    
    a typed argument for the short primitive.
  - getIntArgument
```
TypedArgument getIntArgument(int anInt)
```
    Gets a typed argument for a int primitive.
    
    Parameters:
    
    anInt - an int value
    
    Returns:
    
    a typed argument for the int primitive.
  - getLongArgument
```
TypedArgument getLongArgument(long aLong)
```
    Gets a typed argument for a long primitive.
    
    Parameters:
    
    aLong - a long value
    
    Returns:
    
    a typed argument for the long primitive.
  - getFloatArgument
```
TypedArgument getFloatArgument(float aFloat)
```
    Gets a typed argument for a float primitive.
    
    Parameters:
    
    aFloat - a float value
    
    Returns:
    
    a typed argument for the float primitive.
  - getDoubleArgument
```
TypedArgument getDoubleArgument(double aDouble)
```
    Gets a typed argument for a double primitive.
    
    Parameters:
    
    aDouble - a double value
    
    Returns:
    
    a typed argument for the double primitive.
  - getCharArgument
```
TypedArgument getCharArgument(char aChar)
```
    Gets a typed argument for a char primitive.
    
    Parameters:
    
    aChar - a char value
    
    Returns:
    
    a typed argument for the char primitive.
  - getBooleanArgument
```
TypedArgument getBooleanArgument(boolean aBoolean)
```
    Gets a typed argument for a boolean primitive.
    
    Parameters:
    
    aBoolean - a boolean value
    
    Returns:
    
    a typed argument for the boolean primitive.
  - getObjectArgument
```
TypedArgument getObjectArgument(Object aValue)
```
    Gets a typed argument for an Object.
    Note! This method can only be used if the class of your actual instance exactly match the type required by the constructor you are trying to invoke! If types mismatch, you must use getCustomArgument(String, Object) instead.
    
    Parameters:
    
    aValue - an object, not null
    
    Returns:
    
    a typed argument for aValue object, null if aValue is null. The class value of TypedArgument will be set via aValue.getClass().
    
    See Also:
    
    getNullArgument(String), getCustomArgument(String, Object)
  - getNullArgument
```
TypedArgument getNullArgument(String aQualifiedClassName)
```
    Gets a typed argument for a null value for a specified class/interface.
    Note! This method must be used if you should pass a null value to a constructor!
    
    Parameters:
    
    aQualifiedClassName - a fully qualified name of the class (i.e. including packages)
    
    Returns:
    
    a null argument that uses a specified class/interface as type, or null if an aQualifiedClassName is invalid)
  - getCustomArgument
```
TypedArgument getCustomArgument(String aQualifiedClassName,
                                Object aValue)
```
    Gets a typed argument that specifies a certain class/interface for an object.
    Note! This method must be used if the class of your actual instance doesn't exactly match the type required by the constructor you are trying to invoke! Typical cases for when to use this method are:
    - The class of your instance extends the type required (class) by the constructor
    - The class of your instance implements the type required (interface) by the constructor
    Example of how to create a ArrayList instance in Velocity via the ArrayList(Collection) constructor:
```
   #set ($myList = ...) ## $myList.class is NOT Collection, it's ArrayList, Vector or another Collection implementation...

   #set ($instanceCreatorUtil = $sitevisionUtils.instanceCreatorUtil)
   #set ($aCollectionsTypeArgument = $instanceCreatorUtil.getCustomArgument('java.util.Collection', $myList))
   #set ($anArrayList = $instanceCreatorUtil.getArgumentInstance('java.util.ArrayList', $aCollectionsTypeArgument))
 
```
    Parameters:
    
    aQualifiedClassName - a fully qualified name of the class (i.e. including packages)
    
    aValue - an object
    
    Returns:
    
    a typed argument that uses a specified class/interface as type, or null if an aQualifiedClassName is invalid
    
    See Also:
    
    getObjectArgument(Object), getNullArgument(String)
  - getEnumArgument
```
TypedArgument getEnumArgument(String aQualifiedEnumClassName,
                              Object anEnum)
```
    Gets a typed argument for an Enum value for a specified enum class.
    
    Parameters:
    
    aQualifiedEnumClassName - a fully qualified name of the enum class (i.e. including packages)
    
    anEnum - an Enum instance or a String with the name of the Enum
    
    Returns:
    
    a typed argument that uses a specified enum as type, or null if an aQualifiedEnumClassName or anEnum is invalid
    
    See Also:
    
    getEnumInstance(String, String)
  - getEnumInstance
```
Enum getEnumInstance(String aQualifiedEnumClassName,
                     String anEnumName)
```
    Gets an enum instance for a specified enum class.
    Example of how to create the DocType.HTML5 instance of DocType in Velocity:
```
   #set ($instanceCreatorUtil = $sitevisionUtils.instanceCreatorUtil)
   #set ($html5Enum = $instanceCreatorUtil.getEnumInstance('senselogic.sitevision.api.webresource.doctype.DocType', 'HTML5'))
 
```
    Example of how to create the SECONDS instance of java.util.concurrent.TimeUnit in Velocity:
```
   #set ($instanceCreatorUtil = $sitevisionUtils.instanceCreatorUtil)
   #set ($secondsEnum = $instanceCreatorUtil.getEnumInstance('java.util.concurrent.TimeUnit', 'SECONDS'))
 
```
    Example of how to create the IndexUtil.IndexType.USER_IDENTITY instance of IndexUtil.IndexType (note that IndexType is an "inner" enum of IndexUtil) in Velocity:
```
   #set ($instanceCreatorUtil = $sitevisionUtils.instanceCreatorUtil)

   ## Note that '$' is used to separate outer class from inner enum
   #set ($enumClassName = 'senselogic.sitevision.api.search.index.IndexUtil$IndexType')
   #set ($userIdentityType = $instanceCreatorUtil.getEnumInstance($enumClassName, 'USER_IDENTITY'))
 
```
    Parameters:
    
    aQualifiedEnumClassName - a fully qualified name of the enum class (i.e. including packages)
    
    anEnumName - the name of the enum value
    
    Returns:
    
    an Enum instance, or null if an aQualifiedEnumClassName or anEnumName is invalid
  - getList
```
List getList()
```
    Convenience method to get an ArrayList instance.
    
    Returns:
    
    a java.util.ArrayList instance
    
    See Also:
    
    getListWrapper()
  - getSet
```
Set getSet()
```
    Convenience method to get a HashSet instance.
    
    Returns:
    
    a java.util.HashSet instance
  - getMap
```
Map getMap()
```
    Convenience method to get a HashMap instance.
    
    Returns:
    
    a java.util.HashMap instance
  - getLinkedMap
```
Map getLinkedMap()
```
    Convenience method to get a LinkedHashMap instance.
    
    Returns:
    
    a java.util.LinkedHashMap instance
    
    Since:
    
    Sitevision 4.5.4.1
  - getListWrapper
```
ListWrapper getListWrapper()
```
    Gets a ListWrapper instance.
    The java.util.List interface specifies that the add method should return a boolean. This is a problem if your scripting language (e.g. Velocity) requires you to suppress the returned value so it won't end up in the resulting output. A ListWrapper instance enables such suppressing.
    
    Returns:
    
    a ListWrapper instance
    
    Since:
    
    Sitevision 3.5
  - getArraysInstance
```
ArraysInstance getArraysInstance()
```
    Gets a java.util.Arrays wrapper instance.
    The Arrays class contains static methods only and can't be instantiated. This is a problem if your scripting language (e.g. Velocity) doesn't support static class access (i.e. need an instance/object to invoke methods). An ArraysInstance instance enables Arrays method invocations.
    
    Returns:
    
    a wrapper instance for java.util.Arrays
  - getCollectionsInstance
```
CollectionsInstance getCollectionsInstance()
```
    Gets a java.util.Collections wrapper instance.
    The Collections class contains static methods only and can't be instantiated. This is a problem if your scripting language (e.g. Velocity) doesn't support static class access (i.e. need an instance/object to invoke methods). A CollectionsInstance instance enables Collections method invocations.
    
    Returns:
    
    a wrapper instance for java.util.Collections
  - getMathInstance
```
MathInstance getMathInstance()
```
    Gets a java.lang.Math wrapper instance.
    The Math class contains static methods only and can't be instantiated. This is a problem if your scripting language (e.g. Velocity) doesn't support static class access (i.e. need an instance/object to invoke methods). A MathInstance instance enables Math method invocations.
    
    Returns:
    
    a wrapper instance for java.lang.Math
  - getBooleanArray
```
boolean[] getBooleanArray(int aSize)
```
    Creates a boolean array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a boolean array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getByteArray
```
byte[] getByteArray(int aSize)
```
    Creates a byte array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a byte array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getCharArray
```
char[] getCharArray(int aSize)
```
    Creates a char array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a char array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getDoubleArray
```
double[] getDoubleArray(int aSize)
```
    Creates a double array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a double array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getFloatArray
```
float[] getFloatArray(int aSize)
```
    Creates a float array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a float array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getIntArray
```
int[] getIntArray(int aSize)
```
    Creates a int array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a int array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getLongArray
```
long[] getLongArray(int aSize)
```
    Creates a long array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a long array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getShortArray
```
short[] getShortArray(int aSize)
```
    Creates a short array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a short array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getStringArray
```
String[] getStringArray(int aSize)
```
    Creates a String array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a String array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance
  - getObjectArray
```
Object[] getObjectArray(int aSize)
```
    Creates a Object array with a given size.
    
    Parameters:
    
    aSize - the array size
    
    Returns:
    
    a Object array with aSize length, or empty array if aSize is zero or negative
    
    Since:
    
    Sitevision 4.5.5
    
    See Also:
    
    ArraysInstance

Sitevision - Content Management Made Easy
Sitevision is an advanced Java enterprise portal product that implements Java Content Repository (JSR 283).

Interface InstanceCreatorUtil

Method Summary

Method Detail

getDefaultInstance

getArgumentInstance

getArgumentsInstance

getByteArgument

getShortArgument

getIntArgument

getLongArgument

getFloatArgument

getDoubleArgument

getCharArgument

getBooleanArgument

getObjectArgument

getNullArgument

getCustomArgument

getEnumArgument

getEnumInstance

getList

getSet

getMap

getLinkedMap

getListWrapper

getArraysInstance

getCollectionsInstance

getMathInstance

getBooleanArray

getByteArray

getCharArray

getDoubleArray

getFloatArray

getIntArray

getLongArray

getShortArray

getStringArray

getObjectArray