001/**
002 *
003 * Copyright (c) 2014, the Railo Company Ltd. All rights reserved.
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either 
008 * version 2.1 of the License, or (at your option) any later version.
009 * 
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013 * Lesser General Public License for more details.
014 * 
015 * You should have received a copy of the GNU Lesser General Public 
016 * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
017 * 
018 **/
019package lucee.runtime.orm;
020//FUTURE add to loader
021
022import lucee.runtime.Component;
023import lucee.runtime.PageContext;
024import lucee.runtime.db.DataSource;
025import lucee.runtime.exp.PageException;
026import lucee.runtime.type.Array;
027import lucee.runtime.type.Query;
028import lucee.runtime.type.Struct;
029
030public interface ORMSession {
031        
032        /**
033         * flush all elements in all sessions (for all datasources)
034         * @param pc
035         * @throws PageException
036         */
037        public void flushAll(PageContext pc) throws PageException;
038
039        /**
040         * flush all elements in the sessions of the default datasource
041         * @param pc
042         * @throws PageException
043         */
044        public void flush(PageContext pc) throws PageException;
045
046        /**
047         * flush all elements in a specific sessions defined by datasource name
048         * @param pc
049         * @throws PageException
050         */
051        public void flush(PageContext pc,String datasource) throws PageException;
052        
053        /**
054         * delete elememt from datasource
055         * @param name
056         * @throws PageException 
057         */
058        public void delete(PageContext pc, Object obj) throws PageException;
059        
060        /**
061         * insert entity into datasource, even the entry already exist
062         * @param entity
063         * @throws PageException 
064         */
065        public void save(PageContext pc, Object obj, boolean forceInsert) throws PageException;
066        
067
068        /**
069         * Reloads data for an entity that is already loaded. This method refetches data from the database and repopulates the entity with the refreshed data.
070         * @param obj 
071         */
072        public void reload(PageContext pc, Object obj) throws PageException;
073
074        /**
075         * creates a entity matching the given name
076         * @param entityName
077         * @return
078         */
079        public Component create(PageContext pc, String entityName) throws PageException;
080        
081        /**
082         * Attaches the specified entity to the current ORM session. It copies the state of the given object onto the persistent object with the same identifier and returns the persistent object.
083         * If there is no persistent instance currently associated with the session, it is loaded. The given instance is not associated with the session. User have to use the returned object from this session.
084         * @param entity
085         * @return
086         * @throws PageException 
087         */
088        public Component merge(PageContext pc, Object obj) throws PageException;
089        
090        /**
091         * clear all elements in the default sessions
092         * @param pc
093         * @throws PageException
094         */
095        public void clear(PageContext pc) throws PageException;
096        
097        /**
098         * clear all elements in a specific sessions defined by datasource name
099         * @param pc
100         * @param dataSource
101         * @throws PageException
102         */
103        public void clear(PageContext pc, String dataSource) throws PageException;
104        
105        /**
106         * load and return a Object that match given filter, if there is more than one Object matching the filter, only the first Object is returned
107         * @param name
108         * @param filter
109         * @return
110         */
111        public Component load(PageContext pc, String name, Struct filter) throws PageException;
112        
113        public Query toQuery(PageContext pc, Object obj, String name) throws PageException;
114
115
116        
117        /**
118         * load and return a Object that match given id, if there is more than one Object matching the id, only the first Object is returned
119         * @param name
120         * @param id
121         */
122        public Component load(PageContext pc, String name, String id) throws PageException;
123        
124        /**
125         * load and return a array of Objects matching given filter
126         * @param name
127         * @param filter
128         * @return
129         */
130        public Array loadAsArray(PageContext pc, String name, Struct filter) throws PageException;
131        
132        
133        /**
134         * load and return a array of Objects matching given filter
135         * @param name
136         * @param filter
137         * @param options
138         * @return
139         */
140        public Array loadAsArray(PageContext pc, String name, Struct filter, Struct options)throws PageException;
141        
142        /**
143         * @param pc
144         * @param name
145         * @param filter
146         * @param options
147         * @param order
148         * @return
149         * @throws PageException
150         */
151        public Array loadAsArray(PageContext pc, String name, Struct filter, Struct options, String order)throws PageException;
152
153        /**
154         * load and return a array of Objects matching given id
155         * @param name
156         * @param id
157         */
158        public Array loadAsArray(PageContext pc, String name, String id) throws PageException;
159        
160        /**
161         * @param pc
162         * @param name
163         * @param id
164         * @param order
165         * @return
166         * @throws PageException
167         */
168        public Array loadAsArray(PageContext pc, String name, String id, String order) throws PageException;
169
170        /**
171         * load and return a array of Objects matching given sampleEntity
172         * @param name
173         * @param id
174         */
175        public Array loadByExampleAsArray(PageContext pc, Object obj) throws PageException;
176        
177        /**
178         * load and return a Object that match given sampleEntity, if there is more than one Object matching the id, only the first Object is returned
179         * @param name
180         * @param id
181         */
182        public Component loadByExample(PageContext pc, Object obj) throws PageException;
183        
184        public void evictCollection(PageContext pc,String entity, String collection) throws PageException;
185        
186        public void evictCollection(PageContext pc,String entity, String collection, String id) throws PageException;
187
188        public void evictEntity(PageContext pc,String entity) throws PageException;
189        
190        public void evictEntity(PageContext pc,String entity, String id) throws PageException;
191
192        public void evictQueries(PageContext pc) throws PageException;
193        public void evictQueries(PageContext pc,String cacheName) throws PageException;
194        public void evictQueries(PageContext pc,String cacheName, String datasource) throws PageException;
195
196        public Object executeQuery(PageContext pc, String dataSourceName,String hql, Array params, boolean unique,Struct queryOptions) throws PageException;
197
198        public Object executeQuery(PageContext pc, String dataSourceName,String hql, Struct params, boolean unique,Struct queryOptions) throws PageException;
199
200        /**
201         * close all elements in all sessions
202         * @param pc
203         * @throws PageException
204         */
205        public void closeAll(PageContext pc) throws PageException;
206        
207        /**
208         * close all elements in the default sessions
209         * @param pc
210         * @throws PageException
211         */
212        public void close(PageContext pc) throws PageException;
213        
214        /**
215         * close all elements in a specific sessions defined by datasource name
216         * @param pc
217         * @param datasource
218         * @throws PageException
219         */
220        public void close(PageContext pc, String datasource) throws PageException;
221        
222        /**
223         * is session valid or not
224         * @return is session valid
225         */
226        public boolean isValid(DataSource ds);
227        public boolean isValid();
228        
229        /**
230         * engine from session
231         * @return engine
232         */
233        public ORMEngine getEngine();
234        
235        public Object getRawSession(String dataSourceName) throws PageException;
236        public Object getRawSessionFactory(String dataSourceName) throws PageException;
237
238        public ORMTransaction getTransaction(String dataSourceName,boolean autoManage) throws PageException;
239
240        public String[] getEntityNames();
241
242        public DataSource[] getDataSources(); 
243}