4.3 Properties

Velocity allows you to access properties through a short-hand notation. The objects to look up the properties must be available through a Velocity variable and the notation consists of a leading variable followed by the dot (".") character and another VTL Identifier.

Example 4.2. Valid property names

$customer.address
$purchase.total
$cart.customerDiscount

A property name can represent the following elements depending on the object used for look-up:

Take the first example, $customer.address. It can have multiple meanings:[4]

[Note]Note

When a property name refers to a getter method, $obj.property and $obj.Property will both invoke the same method (either getproperty() or getProperty()). However, if the object represented by $obj has a get(String) method, $obj.property and $obj.Property will pass different values to this get(String) method. This can lead to hard-to-find problems. It's a good practice to standardize the capitalization of property names in your application.

If you wonder about setting property values, please look up the #set() directive chapter. The setting of properties is discussed there.

Default property lookup rules

Velocity is quite clever when figuring out which method corresponds to a requested property.[5]It tries out different alternatives based on several established naming conventions. The exact lookup sequence depends on whether or not the property name starts with an upper-case letter. For lower-case names, such as $customer.address, the sequence is

  • getaddress()

  • getAddress()

  • get("address")

  • isAddress()

For upper-case property names like $customer.Address, it is slightly different:

  • getAddress()

  • getaddress()

  • get("Address")

  • isAddress()

As regular bean properties tend to be written in lowercase notation, you should talk to your programmers that they don't add both lower-case and upper-case methods to their objects. It would be a bad idea anyway.

[Caution]Caution

There are some exotic naming cases, such as a property starting with multiple upper-case letters which are treated specially according to the Java Bean specification. Velocity does not conform to this specification to the last letter, so if you have a method called getURL(), you cannot use $obj.url to invoke the method, you must use $obj.URL or $obj.uRL. This might change in future versions of Velocity.



[4] The sequence of these lookups is determined by the Velocity Uberspector. This is merely the default lookup. A Java developer can customize this behaviour by using a custom Uberspector.

[5] Some people would say that it is entirely too clever.