~~ Licensed to the Apache Software Foundation (ASF) under one or more | |
~~ contributor license agreements. See the NOTICE file distributed with | |
~~ this work for additional information regarding copyright ownership. | |
~~ The ASF licenses this file to You under the Apache License, Version 2.0 | |
~~ (the "License"); you may not use this file except in compliance with | |
~~ the License. You may obtain a copy of the License at | |
~~ | |
~~ http://www.apache.org/licenses/LICENSE-2.0 | |
~~ | |
~~ Unless required by applicable law or agreed to in writing, software | |
~~ distributed under the License is distributed on an "AS IS" BASIS, | |
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
~~ See the License for the specific language governing permissions and | |
~~ limitations under the License. | |
------ | |
Properties | |
------ | |
Properties | |
Components, converters and validators have properties. Usually, | |
properties must be defined on .tld files. Also, property getter/setter | |
and saveState/restoreState methods can be generated automatically, | |
reducing the amount of code that should be maintained. | |
Properties are inherited, so if a component/converter/validator extends | |
from a parent component/converter/validator that has some property | |
defined, the child must have it on its .tld. | |
But sometimes we have the following scenarios: | |
* Components, converters and validators also have properties with | |
no getter and setters (like "binding" property), which are implemented | |
in their tag classes or facelets tag handler. | |
* Also, some properties implemented on a parent class are not | |
implemented on some children, so we need to exclude it from its | |
tld definition. | |
* Users can implement its own setter and getter methods for properties. | |
* Some properties are related only to component but should not be on | |
tld. | |
* Some properties have some specific behavior (for example they could | |
contains objects implementing StateHolder interface). | |
All these cases could be handled using @JSFProperty and @JSFJspProperty | |
annotations. Below there are some examples describing how to use it. | |
* General case | |
The most common case is let the property body be generated. | |
------------------- | |
@JSFProperty | |
public abstract String getAutocomplete(); | |
------------------- | |
* Custom Implementation of getter/setters | |
One example is UIViewRoot "renderKitId" property: | |
------------------- | |
@JSFProperty | |
public String getRenderKitId() | |
{ | |
//... custom implementation ... | |
} | |
public void setRenderKitId(String renderKitId) | |
{ | |
//... custom implementation ... | |
} | |
------------------- | |
* Properties without getter/setters | |
This syntax should be used only in very special cases and users should | |
use @JSFProperty annotation/doclet instead. | |
------------------- | |
@JSFComponent(type = "javax.faces.ComponentBase", family = "javax.faces.ComponentBase", desc = "base component when all components must inherit", tagClass = "javax.faces.webapp.UIComponentELTag", configExcluded = true) | |
@JSFJspProperty(name = "binding", | |
returnType = "javax.faces.component.UIComponent", | |
longDesc = "Identifies a backing bean property (of type UIComponent or appropriate subclass) to bind to this component instance. This value must be an EL expression.", desc = "backing bean property to bind to this component instance") | |
public abstract class UIComponentBase extends UIComponent | |
{ | |
// .... some code ... | |
} | |
------------------- | |
* Excluding properties from tld | |
One example is UIParameter "rendered" property: | |
------------------- | |
/** | |
* Disable this property; although this class extends a base-class that defines a read/write rendered property, this | |
* particular subclass does not support setting it. Yes, this is broken OO design: direct all complaints to the JSF | |
* spec group. | |
*/ | |
@Override | |
@JSFProperty(tagExcluded = true) | |
public void setRendered(boolean state) | |
{ | |
super.setRendered(state); | |
// call parent method due TCK problems | |
// throw new UnsupportedOperationException(); | |
} | |
------------------- | |
* Properties with different name in component and tag class | |
One example is UICommand "action" property. To change it on tld, | |
use "jspName". | |
------------------- | |
@JSFProperty(stateHolder = true, returnSignature = "java.lang.Object", jspName = "action") | |
public MethodExpression getActionExpression() | |
{ | |
// .... some code ... | |
} | |
------------------- | |
* MethodExpression/MethodBinding properties | |
------------------- | |
@JSFProperty(stateHolder = true, returnSignature = "void", methodSignature = "javax.faces.event.ActionEvent") | |
public MethodBinding getActionListener() | |
{ | |
// .... some code ... | |
} | |
@JSFProperty(stateHolder = true, returnSignature = "java.lang.Object", jspName = "action") | |
public MethodExpression getActionExpression() | |
{ | |
// .... some code ... | |
} | |
------------------- | |