javax.faces.model.FacesDataModel Maven / Gradle / Ivy
Show all versions of javax.faces-api Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2015 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.faces.model;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import java.util.Set;
import javax.faces.component.UIData;
import javax.inject.Qualifier;
/**
*
* The presence of this annotation on a class automatically registers the class with the runtime as a
* {@link DataModel} that is capable of wrapping a type indicated by the {@link FacesDataModel#forClass()} attribute.
*
*
* The runtime must maintain a collection of these {@link DataModel}s such that
* {@link UIData} and other components defined by the JSF specification can query the runtime for a
* suitable {@link DataModel} wrapper (adapter) for the type of their value
.
* This has to be done after all wrappers for specific types such as {@link Set} are tried, but before
* the {@link ScalarDataModel} is selected as the wrapper. See {@link UIData#getValue()}.
*
*
* This query must work as follows:
*
*
* For an instance of type Z
that is being bound to a UIData
component or other component
* defined by the JSF specification that utilizes DataModel
, the query for that type must return the
* most specific DataModel that can wrap Z
.
*
*
* This most specific DataModel is defined as the DataModel that is obtained by first sorting the collection in
* which the registered DataModels
are stored (for details on this sorting see below) and then
* iterating through the sorted collection from beginning to end and stopping this iteration at the first match where
* for the class ZZ
wrapped by the DataModel (as indicated by the {@link FacesDataModel#forClass()} attribute)
* it holds that ZZ.isAssignableFrom(Z)
. This match is then taken as the most specific DataModel.
*
*
* The sorting must be done as follows:
*
*
* Sort on the class wrapped by a DataModel that is stored in the above mentioned collection such that for any 2 classes
* X
and Y
from this collection, if an object of X
is an instanceof
* an object of Y
, X
appears in the collection before Y
.
* The collection's sorting is otherwise arbitrary. In other words, subclasses come before their superclasses.
*
*
* For example:
*
*
* Given class B
, class A extends B
and class Q
, two possible orders are;
*
* -
{A, B, Q}
* -
{Q, A, B}
*
*
*
* The only requirement here is that A
appears before B
, since A
is a subclass of
* B
.
*
*
The specification does not define a public method to obtain an
* instance of the "most specific DataModel for a given type". Such an
* instance can be obtained using code similar to the following.
*
*
*
* @SuppressWarnings("unchecked")
* public <T> DataModel<T> createDataModel(Class<T> forClass, Object value) {
* class LocalUIData extends UIData {
* @Override
* public DataModel<?> getDataModel() {
* return super.getDataModel();
* }
* }
* LocalUIData localUIData = new LocalUIData();
* localUIData.setValue(value);
*
* return (DataModel<T>) localUIData.getDataModel();
* }
*
*
*
* For example:
*
*
*
* public class Child1 {
*
* }
*
*
*
* and
*
*
*
* package test.jsf23;
*
* @FacesDataModel(forClass = Child1.class)
* public class Child1Model<E> extends DataModel<E> {
*
* @Override
* public int getRowCount() {
* return 0;
* }
*
* @Override
* public E getRowData() {
* return null;
* }
*
* @Override
* public int getRowIndex() {
* return 0;
* }
*
* @Override
* public Object getWrappedData() {
* return null;
* }
*
* @Override
* public boolean isRowAvailable() {
* return false;
* }
*
* @Override
* public void setRowIndex(int arg0) {
*
* }
*
* @Override
* public void setWrappedData(Object arg0) {
*
* }
* }
*
*
*
* Then the following must work:
*
*
*
* DataModel<Child1> myModel = createDataModel(Child1.class, new Child1());
* assert myModel instanceof Child1Model;
* System.out.println(myModel.getClass());
*
*
*
* The result printed should be e.g.: "class
* test.jsf23.Child1Model"
*
*
*
*/
@Retention(RUNTIME)
@Target(TYPE)
@Inherited
@Qualifier
public @interface FacesDataModel {
/**
* The value of this annotation
* attribute is taken to be the type that the DataModel that is
* annotated with this annotation is able to wrap.
*
* @return the type that the DataModel that is annotated with this annotation is able to wrap
*/
Class forClass() default Object.class;
}