Urls

Urls are the skeleton of a ztemplates application. They are used to trigger callbacks on the active part of a ztemplates webapp, the action-pojos.

Urls are specified by the @ZMatch annotation on the action-pojos. ztemplates computes a matching tree from all ZMatch annotations it finds in the classpath. The tree is shown in the application-server console at startup.

Url format

The url is a character string separated by '/'. A url must start with '/', except for nested urls. If it ends with '/' the trailing '/' will be ignored.

A url can contain

• zero or many url-variables in the format ${javaBeanPropertyName}. There must be a JavaBeans property with that name on the action-pojo. As of this version the type of this property must be String or ZProperty. If it is String, the pojo must define a setter and a getter for the property. If it is ZProperty, the pojo must define only a getter, as the class ZProperty has methods to set and get the url-variable. See this tutorial for code example. The url variable can not match any '/' character. The value will be decoded before calling the setter on the render-pojo and encoded if the url is created by ZTemplates.getServletService().createUrl(...) .
• zero or many url-references in the format #{javaBeanPropertyName}. There must be a JavaBeans property with that name on the action-pojo. The type of that property must be either a class that is annotated with @ZMatch or a interface. If it is a interface, the classpath must contain one ore many classes that implement that interface and are annotated with ZMatch. There is no explicit OR construct. OR functionality is implemented implicit by url-references and interfaces. A url-reference with interfaces is equivalent to a OR in the matching expression. You have to be careful to make the @ZMatch annotations on the classes implementing the same interface distinguishable, so the framework can decide which class to instantiate. See this tutorial for code example.
• zero or many optional expressions in the format [optionalExpression]. Optional expressions can be nested.
• zero or one *{var} tail-expression at the end of the expression. This will match everything to the end of the url, even '/' that cannot be otherwise matched by a url variable. The value will not be decoded. Use this to create resource loaders, where the end part of the url references the resource to be loaded.

Url parameters

Url parameters are assigned to the pojo that declares them in the @ZMatch annotation before the after() callback is called. Parameters are consumed, that means they are assigned only once, and because they are assigned before the after() callback the deepest nested action-pojo will get the parameter. Parameters are consumed depth-first. As of version 0.9.8 there are no callbacks on parameters.

The setter can accept either a String or a String array. You can use ZProperty for parameters as well.

forms parameter names with '.' are not supported anymore starting from version 0.9.9.7

You can also define a form for parameters.

@ZMatch(value = "/", parameters = {"myform.prop1"})

Define a property myform in your action-pojo, define a property prop1 in your form object. To avoid deep links into your object structure only one nesting level is allowed, myform.form.prop1 won't work. This feature was introduced to allow the definition of a form object that can be shared between action-pojo and render-pojo. (not supported anymore)

since 0.9.9.7 use the ZMatch(form="formName") feature to declare a form object.

Url creation

Urls can be created

• by hand - write your url down as you always did
• by framework - in a refactoring-safe way using a ZIUrlFactory

 //fill in all url-variables and url-references
 Object actionPojo = ...; 
 ZIUrlFactory urlFactory = new ZUrlFactory(...);
 String url = urlFactory .createUrl(actionPojo);

• by framework in webapp - use the ServletService which prepends the contextPath to the url

 //fill in all url-variables and url-references
 Object actionPojo = ...; 
 String url = ZTemplates.getServletService().createUrl(actionPojo);

Url examples

Url matching

1. split the url by the special character '/'
2. search the match tree nodes for a node that matches the expression. You can see the match tree in the console of your application server at first request. The tree is processed top down, more specific first.
3. Then instantiate the corresponding action-pojo and begin the url processing.

urls in ztemplates-web

In ztemplates-web urls are processed by the ZServletFilter. There is a tutorial on how to setup a ztemplates webapp.

The url computed from the HttpServletRequest always starts with a '/'. There are no trailing '/'.