javax.faces.model.FacesDataModel Maven / Gradle / Ivy

/*
 * 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;
}