001    package org.springframework.richclient.widget.editor.provider;
002    
003    import java.util.List;
004    
005    /**
006     * <p>
007     * The DataProvider regulates access to the back-end services. It can be used by eg a
008     * {@link org.springframework.richclient.widget.editor.DefaultDataEditorWidget} as a central access point to the services that provide the data.
009     * </p>
010     */
011    public interface DataProvider extends DataProviderEventSource
012    {
013    
014        /**
015         * <p>
016         * Each DataProvider can specify a policy that dictates when to refresh the data list. This policy must be
017         * taken into account by any class using the DataProvider in order to keep the data in a consistent state.
018         * </p>
019         * 
020         * <ul>
021         * <li><em>NEVER</em> No automatic refresh, user should trigger a refresh when needed.</li>
022         * <li><em>ON_EMPTY</em> Fetch the data once. This usually means when your client-side data list is
023         * empty.</li>
024         * <li><em>ON_USER_SWITCH</em> Data needs to be refreshed when a user switch is detected. The data may
025         * contain user specific entries.</li>
026         * <li><em>ALLWAYS</em> Data needs to be refreshed whenever the user views the list (on switching to
027         * that screen).</li>
028         * </ul>
029         */
030        public static enum RefreshPolicy {
031            NEVER, ON_EMPTY, ON_USER_SWITCH, ALLWAYS
032        }
033    
034        /**
035         * Fetch the detailed object from the back-end. To optimize your code, a flag is passed (forceLoad) to
036         * specify if a back-end load is absolutely necessary or not. If forceLoad is <code>false</code> you may
037         * return the selectedObject directly if it is already detailed. On the other hand if forceLoad is
038         * <code>true</code> you MUST fetch the detailed object from the back-end. If your object doesn't have a
039         * specific detail the same logic must be applied to allow the fetching of a fresh individual object.
040         * 
041         * @param selectedObject
042         *            the object that must be used to fetch the detailed one.
043         * @param forceLoad
044         *            if <code>true</code> always go to back-end and load the object; if <code>false</code> a
045         *            shortcut can be used to return an already detailed selected object.
046         */
047        public Object getDetailObject(Object selectedObject, boolean forceLoad);
048    
049        public Object getSimpleObject(Object selectedObject);
050    
051        public boolean supportsFiltering();
052    
053        public List getList(Object criteria);
054    
055        public boolean supportsUpdate();
056    
057        public Object update(Object updatedData);
058    
059        public boolean supportsCreate();
060    
061        public Object create(Object newData);
062    
063        public Object newInstance(Object criteria);
064    
065        public boolean supportsClone();
066    
067        public Object clone(Object sampleData);
068    
069        public boolean supportsDelete();
070    
071        public void delete(Object dataToRemove);
072    
073        public boolean supportsBaseCriteria();
074    
075        public void setBaseCriteria(Object criteria);
076    
077        public boolean exists(Object data);
078    
079        public RefreshPolicy getRefreshPolicy();
080    
081    }