001/*
002 * Stallion Core: A Modern Web Framework
003 *
004 * Copyright (C) 2015 - 2016 Stallion Software LLC.
005 *
006 * This program is free software: you can redistribute it and/or modify it under the terms of the
007 * GNU General Public License as published by the Free Software Foundation, either version 2 of
008 * the License, or (at your option) any later version. This program is distributed in the hope that
009 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
010 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
011 * License for more details. You should have received a copy of the GNU General Public License
012 * along with this program.  If not, see <http://www.gnu.org/licenses/gpl-2.0.html>.
013 *
014 *
015 *
016 */
017
018package io.stallion.dataAccess;
019
020import io.stallion.dataAccess.db.DB;
021import io.stallion.dataAccess.filtering.FilterChain;
022import io.stallion.reflection.PropertyUtils;
023
024import java.util.List;
025import java.util.Map;
026
027/**
028 * A Persister actually handles interaction with the data store. There are
029 * persister implementations for storing to a database, JSON files, text files,
030 * etc.
031 *
032 * @param <T>
033 */
034public interface Persister<T extends Model> {
035
036    /**
037     * Initialize the persister, called during DalRegistery.register
038     * @param registration
039     * @param controller
040     * @param stash
041     */
042    public void init(DataAccessRegistration registration, ModelController<T> controller, Stash<T> stash);
043
044    /**
045     * The Class of the model associated with this persister
046     * @return
047     */
048    public Class<T> getModelClass();
049    public Persister<T> setModelClass(Class<T> modelClass);
050
051    /**
052     * The bucket name associated with this persister.
053     * @return
054     */
055    public String getBucket();
056    public Persister<T> setBucket(String bucket);
057
058    /**
059     * Fetch all the items from the underlying data store.
060     * @return
061     */
062    public List fetchAll();
063
064    /**
065     * Fetch one object with the given ID
066     * @param id
067     * @return
068     */
069    public T fetchOne(Long id);
070
071    /**
072     * Re-fetch the passed in object from the underlying data stores
073     * @param obj
074     * @return
075     */
076    public T fetchOne(T obj);
077
078    /**
079     * Get the controller associated with this persister
080     * @return
081     */
082    public ModelController<T> getItemController();
083    public Persister setItemController(ModelController<T> controller);
084
085    /**
086     * Get the Stash associated with this persister
087     *
088     * @return
089     */
090    public Stash<T> getStash();
091    public Persister<T> setStash(Stash<T> stash);
092
093    /**
094     * Callback for file-based datastores when an object is changed in the file system
095     *
096     * @param relativePath
097     */
098    void watchEventCallback(String relativePath);
099
100    /**
101     * Persist the object to the underlying data store
102     * @param obj
103     */
104    public void persist(T obj);
105
106    /**
107     * Update the specified values. For datastores that support it, it should only save the updated
108     * values to the datastore -- not the entire object.
109     *
110     * @param obj
111     * @param values
112     */
113    public default void update(T obj, Map<String, Object> values) {
114        T clone = getStash().detach(obj);
115        for(Map.Entry<String, Object> entry: values.entrySet()) {
116            PropertyUtils.setProperty(obj, entry.getKey(), entry.getValue());
117        }
118        persist(clone);
119    }
120
121    /**
122     * Permanently delete the object from the datastore
123     * @param obj
124     */
125    public void hardDelete(T obj);
126
127    /**
128     * Attach any file system watchers for changed objects
129     */
130    public void attachWatcher();
131
132    /**
133     * Called by fetchOne() after the object has been loaded from the datastore
134     *
135     * @param obj
136     */
137    public void handleFetchOne(T obj);
138
139    /**
140     * Called after an object has been fetched from the data store
141     */
142    public void onFetchOne();
143
144    /**
145     * Called before any read operation.
146     */
147    public void onPreRead();
148
149    /**
150     * Reload the object if the version in the datastore is more recent than the
151     * local object
152     * @param obj
153     * @return
154     */
155    public boolean reloadIfNewer(T obj);
156
157
158
159    public FilterChain<T> filterChain();
160
161    public boolean isDbBacked();
162
163}