001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.markup.repeater.data;
018
019import java.util.Iterator;
020
021import org.apache.wicket.model.IDetachable;
022import org.apache.wicket.model.IModel;
023
024
025/**
026 * Interface used to provide data to data views.
027 * 
028 * Example:
029 * 
030 * <pre>
031 * class UsersProvider implements IDataProvider
032 * {
033 * 
034 *      public Iterator iterator(long first, long count)
035 *      {
036 *              ((MyApplication)Application.get()).getUserDao().iterator(first, count);
037 *      }
038 * 
039 *      public long size()
040 *      {
041 *              ((MyApplication)Application.get()).getUserDao().getCount();
042 *      }
043 * 
044 *      public IModel model(Object object)
045 *      {
046 *              return new DetachableUserModel((User)object);
047 *      }
048 * }
049 * </pre>
050 * 
051 * You can use the {@link IDetachable#detach()} method for cleaning up your IDataProvider instance.
052 * So that you can do one query that returns both the size and the values if your dataset is small
053 * enough the be able to do that.
054 * 
055 * @see IDetachable
056 * @see DataViewBase
057 * @see DataView
058 * @see GridView
059 * 
060 * @author Igor Vaynberg (ivaynberg)
061 * @param <T>
062 * 
063 */
064public interface IDataProvider<T> extends IDetachable
065{
066        /**
067         * Gets an iterator for the subset of total data
068         * 
069         * @param first
070         *            first row of data
071         * @param count
072         *            minimum number of elements to retrieve
073         * 
074         * @return iterator capable of iterating over {first, first+count} items
075         */
076        Iterator<? extends T> iterator(long first, long count);
077
078        /**
079         * Gets total number of items in the collection represented by the DataProvider
080         * 
081         * @return total item count
082         */
083        long size();
084
085        /**
086         * Callback used by the consumer of this data provider to wrap objects retrieved from
087         * {@link #iterator(long, long)} with a model (usually a detachable one).
088         * 
089         * @param object
090         *            the object that needs to be wrapped
091         * 
092         * @return the model representation of the object
093         */
094        IModel<T> model(T object);
095
096        @Override
097        default void detach()
098        {}
099}