MentaBean

Rev

Rev 195 | Rev 217 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 soliveira 1
/*
22 soliveira 2
 * This program is free software: you can redistribute it and/or modify
3
 * it under the terms of the GNU General Public License as published by
4
 * the Free Software Foundation, either version 3 of the License, or
5
 * (at your option) any later version.
6
 *
7
 * This program is distributed in the hope that it will be useful,
2 soliveira 8
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 soliveira 9
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10
 * GNU General Public License for more details.
11
 *
12
 * You should have received a copy of the GNU General Public License
13
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
14
 *
15
 * MentaBean => http://www.mentabean.org
16
 * Author: Sergio Oliveira Jr. (sergio.oliveira.jr@gmail.com)
2 soliveira 17
 */
18
package org.mentabean;
19
 
54 soliveira 20
import java.sql.Connection;
32 soliveira 21
import java.sql.ResultSet;
2 soliveira 22
import java.util.List;
23
 
149 erico 24
import org.mentabean.event.TriggerListener;
25
import org.mentabean.jdbc.QueryBuilder;
167 soliveira 26
import org.mentabean.sql.TableAlias;
126 soliveira 27
import org.mentabean.util.Limit;
125 soliveira 28
import org.mentabean.util.OrderBy;
29
 
2 soliveira 30
/**
22 soliveira 31
 * Describe a simple ORM interface that can perform CRUD for Beans according to properties defined programmatically on BeanManager. It can also load lists and unique beans based on properties set on a given bean. It also supports dynamic update, in other words, it will only update fields from a bean
32
 * loaded from the database that were actually modified during the session. The behavior can be turned off when necessary ,in other words, when you want to blindly update all properties from a bean in the database regarding of whether they were modified or not.
2 soliveira 33
 *
34
 * @author Sergio Oliveira Jr.
35
 */
36
public interface BeanSession {
61 soliveira 37
 
148 erico 38
        public static final int UPDATE = 0, INSERT = 1;
39
 
54 soliveira 40
        /**
41
         * Get the database connection being used by this bean session.
61 soliveira 42
         *
54 soliveira 43
         * @return the database connection
44
         */
45
        public Connection getConnection();
2 soliveira 46
 
47
        /**
22 soliveira 48
         * Load the bean from the database, injecting all its properties through reflection. Note that the bean passed MUST have its primary key set otherwise there is no way we can load it from the database.
2 soliveira 49
         *
50
         * @param bean
51
         *            The bean we want to load from the DB.
52
         * @return true if the bean was found in the database, false otherwise
53
         */
4 soliveira 54
        public boolean load(Object bean);
114 soliveira 55
 
126 soliveira 56
        public boolean load(Object bean, Object... properties);
114 soliveira 57
 
126 soliveira 58
        public boolean loadMinus(Object bean, Object... minus);
2 soliveira 59
 
60
        /**
22 soliveira 61
         * Update the bean in the database. Only the bean fields that have been modified (dirty) will be updated.
2 soliveira 62
         *
22 soliveira 63
         * It will return 1 if an update did happen or 0 if the bean could not be found in the database or if there was nothing modified in bean.
2 soliveira 64
         *
22 soliveira 65
         * The bean MUST have its primary key set, otherwise it is impossible to update the bean in the database, and an exception will be thrown.
2 soliveira 66
         *
67
         * @param bean
68
         *            The bean to be updated
144 erico 69
         * @param forceNull
184 erico 70
         *                        Database columns that will be forced to null if the bean property is not set
22 soliveira 71
         * @return 1 if update was successful, 0 if the update did not happen or was not necessary
4 soliveira 72
         */
144 erico 73
        public int update(Object bean, Object... forceNull);
4 soliveira 74
 
75
        /**
22 soliveira 76
         * Same as update(bean) but here you can turn off the default dynamic update behavior and force all bean properties to be updated regardless whether they have been modified or not.
4 soliveira 77
         *
78
         * @param bean
13 soliveira 79
         * @return the number of rows that were updated
2 soliveira 80
         * @throws Exception
81
         */
17 soliveira 82
        public int updateAll(Object bean);
195 erico 83
 
84
        /**
85
         * Updates an object using only the differences between newBean and oldBean instances.
86
         * This method is useful in distributed environments like RMI or web services because these approaches should serialize objects to send/receive informations from client to server and vice versa
87
         * @param newBean
88
         * @param oldBean
89
         * @return 1 if update was successful, 0 if the update did not happen or was not necessary (when bean instances have no differences)
90
         */
91
        public <E> int updateDiff(E newBean, E oldBean);
2 soliveira 92
 
93
        /**
94
         * Insert the bean in the database.
95
         *
22 soliveira 96
         * Depending on the type of PK, the generation of the PK can and should be taken care by the DB itself. The generated PK should be inserted in the bean by reflection, before the method returns.
2 soliveira 97
         *
22 soliveira 98
         * The default, database-independent implementation of this method, insert all fields in the database not worrying about PK generation strategies.
2 soliveira 99
         *
100
         * @param bean
101
         *            The bean to insert
102
         */
4 soliveira 103
        public void insert(Object bean);
143 erico 104
 
105
        /**
106
         * Tries to update or insert a bean using the <code>update</code> method.
107
         *
108
         * @param bean The bean to update or insert
161 erico 109
         * @param forceNull Database columns that will be forced to null (or zero) if the bean property is not set
143 erico 110
         * @return      A value <b>0 (zero)</b> if operation executed an <code>update</code> and <b>1 (one)</b> if <code>insert</code> method was executed
111
         * @see #saveAll(Object)
147 erico 112
         * @see #update(Object, Object...)
143 erico 113
         */
152 erico 114
        public int save(Object bean, Object... forceNull);
143 erico 115
 
116
        /**
117
         * Tries to update or insert a bean object into database. The update uses the <code>updateAll</code> method.
118
         *
119
         * @param bean The bean to update or insert
120
         * @return      A value <b>0 (zero)</b> if operation executed an <code>update</code> and <b>1 (one)</b> if <code>insert</code> method was executed
121
         * @see #updateAll(Object)
122
         */
123
        public int saveAll(Object bean);
2 soliveira 124
 
125
        /**
126
         * Delete the bean from the database.
127
         *
4 soliveira 128
         * The PK of the bean MUST be set. The bean can only be deleted by its PK.
2 soliveira 129
         *
130
         * @param bean
131
         * @return true if it was deleted or false if it did not exist
132
         * @throws Exception
133
         */
4 soliveira 134
        public boolean delete(Object bean);
192 erico 135
 
136
        /**
137
         * Delete all data based on the properties present in the bean passed
138
         *
139
         * The PK doesn't need to be set
140
         *
141
         * @param bean
142
         * @return The total of tuples removed from database
143
         */
144
        public int deleteAll(final Object bean);
2 soliveira 145
 
4 soliveira 146
        /**
19 soliveira 147
         * Count the number of beans that would be returned by a loadList method.
148
         *
149
         * @param bean
150
         *            The bean holding the properties used by the list query.
151
         * @return the number of beans found in the database
152
         */
153
        public int countList(Object bean);
154
 
155
        /**
22 soliveira 156
         * Load a list of beans based on the properties present in the bean passed. For example, if you want to load all users with lastName equal to 'saoj' you would instantiate a bean and set its lastName property to 'saoj' before passing it as an argument to this method.
4 soliveira 157
         *
158
         * @param <E>
159
         * @param bean
160
         *            The bean holding the properties used by the list query.
22 soliveira 161
         * @return A list of beans the match the properties in the given bean. Or an empty list if nothing was found.
4 soliveira 162
         */
163
        public <E> List<E> loadList(E bean);
61 soliveira 164
 
126 soliveira 165
        public <E> List<E> loadList(E bean, Object... properties);
61 soliveira 166
 
126 soliveira 167
        public <E> List<E> loadListMinus(E bean, Object... minus);
61 soliveira 168
 
4 soliveira 169
        /**
22 soliveira 170
         * Same as loadList(bean) except that you can order the list returned by passing an SQL orderBy clause.
4 soliveira 171
         *
172
         * @param <E>
173
         * @param bean
174
         *            The bean holding the properties used by the list query.
175
         * @param orderBy
176
         *            The orderBy SQL clause.
22 soliveira 177
         * @return A list of beans the match the properties in the given bean. Or an empty list if nothing was found.
4 soliveira 178
         */
125 soliveira 179
        public <E> List<E> loadList(E bean, OrderBy orderBy);
61 soliveira 180
 
126 soliveira 181
        public <E> List<E> loadList(E bean, OrderBy orderBy, Object... properties);
61 soliveira 182
 
126 soliveira 183
        public <E> List<E> loadListMinus(E bean, OrderBy orderBy, Object... minus);
61 soliveira 184
 
4 soliveira 185
        /**
22 soliveira 186
         * Same as loadList(bean) except that you can limit the number of beans returned in the list.
4 soliveira 187
         *
188
         * @param <E>
189
         * @param bean
190
         *            The bean holding the properties used by the list query.
191
         * @param limit
192
         *            The max number of beans returned in the list.
22 soliveira 193
         * @return A list of beans the match the properties in the given bean. Or an empty list if nothing was found.
4 soliveira 194
         */
126 soliveira 195
        public <E> List<E> loadList(E bean, Limit limit);
61 soliveira 196
 
126 soliveira 197
        public <E> List<E> loadList(E bean, Limit limit, Object... properties);
61 soliveira 198
 
126 soliveira 199
        public <E> List<E> loadListMinus(E bean, Limit limit, Object... minus);
2 soliveira 200
 
4 soliveira 201
        /**
22 soliveira 202
         * Same as loadList(bean) except that you can limit the number of beans returned in the list as well as sort them by passing a orderBy SQL clause.
4 soliveira 203
         *
204
         * @param <E>
205
         * @param bean
206
         *            The bean holding the properties used by the list query.
207
         * @param orderBy
208
         *            The orderBy SQL clause.
209
         * @param limit
210
         *            The max number of beans returned in the list.
22 soliveira 211
         * @return A list of beans the match the properties in the given bean. Or an empty list if nothing was found.
4 soliveira 212
         */
126 soliveira 213
        public <E> List<E> loadList(E bean, OrderBy orderBy, Limit limit);
61 soliveira 214
 
126 soliveira 215
        public <E> List<E> loadList(E bean, OrderBy orderBy, Limit limit, Object... properties);
61 soliveira 216
 
126 soliveira 217
        public <E> List<E> loadListMinus(E bean, OrderBy orderBy, Limit limit, Object... minus);
2 soliveira 218
 
4 soliveira 219
        /**
22 soliveira 220
         * Same as loadList(bean) but it attempts to load a single bean only. If more than one bean is found it throws an exception.
4 soliveira 221
         *
102 soliveira 222
         * NOTE: The returned bean will be attached by the session so only the modified properties will be updated in case update() is called.
223
         *
4 soliveira 224
         * @param <E>
225
         * @param bean
226
         *            The bean holding the properties used by the load query.
22 soliveira 227
         * @return A unique bean that match the properties in the given bean. Or null if nothing was found.
4 soliveira 228
         * @throws BeanException
229
         *             if more than one bean is found by the query.
230
         */
231
        public <E> E loadUnique(E bean);
114 soliveira 232
 
126 soliveira 233
        public <E> E loadUnique(E bean, Object... properties);
114 soliveira 234
 
126 soliveira 235
        public <E> E loadUniqueMinus(E bean, Object... minus);
2 soliveira 236
 
32 soliveira 237
        public String buildSelect(final Class<? extends Object> beanClass);
61 soliveira 238
 
126 soliveira 239
        public String buildSelect(final Class<? extends Object> beanClass, Object... properties);
61 soliveira 240
 
126 soliveira 241
        public String buildSelectMinus(final Class<? extends Object> beanClass, Object... minus);
32 soliveira 242
 
243
        public String buildSelect(final Class<? extends Object> beanClass, String tableName);
61 soliveira 244
 
126 soliveira 245
        public String buildSelect(final Class<? extends Object> beanClass, String tableName, Object... properties);
61 soliveira 246
 
126 soliveira 247
        public String buildSelectMinus(final Class<? extends Object> beanClass, String tableName, Object... minus);
61 soliveira 248
 
135 soliveira 249
        public void populateBean(final ResultSet rset, final Object bean);
61 soliveira 250
 
135 soliveira 251
        public void populateBean(final ResultSet rset, final Object bean, Object... properties);
61 soliveira 252
 
135 soliveira 253
        public void populateBeanMinus(final ResultSet rset, final Object bean, Object... minus);
61 soliveira 254
 
135 soliveira 255
        public void populateBean(final ResultSet rset, final Object bean, String tableName);
61 soliveira 256
 
135 soliveira 257
        public void populateBean(final ResultSet rset, final Object bean, String tableName, Object... properties);
61 soliveira 258
 
126 soliveira 259
        public void populateBeanMinus(final ResultSet rset, final Object bean, String tableName, Object... minus);
61 soliveira 260
 
261
        // some experiment with metadata...
262
 
263
        public void createTable(Class<? extends Object> beanKlass);
155 erico 264
 
265
        public void dropTable(Class<? extends Object> beanKlass);
61 soliveira 266
 
267
        public void createTables();
143 erico 268
 
269
        // some useful methods to handle with manual queries
270
 
271
        public String propertyToColumn(Class<? extends Object> clazz, Object property, String alias);
272
 
273
        public String propertyToColumn(Class<? extends Object> clazz, Object property);
274
 
150 erico 275
        /**
276
         * Creates an single instance only with primary keys according the given object
277
         * @param bean - The bean with all primary key set
278
         * @return A new instance of the bean
279
         */
149 erico 280
        public <E> E createBasicInstance(E bean);
281
 
282
        /**
195 erico 283
         * Compare differences between two beans holding the properties of first bean passed and
284
         * adding null properties in nullProps list. This method returns null when beans has no differences
285
         * @param
286
         *              bean
287
         * @param
288
         *              another
289
         * @param
290
         *              nullProps An empty list
212 soliveira 291
         * @return A new instance of the bean
195 erico 292
         */
293
        public <E> E compareDifferences(E bean, E another, List<String> nullProps);
294
 
295
        /**
149 erico 296
         * Returns the table name configured for the given class
297
         * @param clazz - The bean class
298
         * @return Table name
299
         */
143 erico 300
        public String buildTableName(Class<? extends Object> clazz);
301
 
149 erico 302
        /**
303
         * Returns the BeanConfig object from the given bean class
304
         * @param clazz
305
         * @return BeanConfig
306
         */
307
        public BeanConfig getConfigFor(Class<?> clazz);
308
 
309
        /**
310
         * Builds a new QueryBuilder so it's possible to create fluent custom SQL queries
311
         * @return QueryBuilder object
312
         */
313
        public QueryBuilder buildQuery();
314
 
315
        //trigger..
316
        /**
317
         * Add a TriggerListener in this session. Remember that it's not added in BeanConfig, only in current session
318
         * @param trigger
319
         */
320
        public void addTrigger(TriggerListener trigger);
321
 
322
        /**
323
         * Removes the TriggerListener from session
324
         * @param trigger
325
         */
326
        public void removeTrigger(TriggerListener trigger);
327
 
167 soliveira 328
        /**
329
         * Return a table alias for this bean class
330
         *
331
         * @param beanClass
332
         * @return TableAlias
333
         */
169 erico 334
        public <E> TableAlias<E> createTableAlias(Class<? extends E> beanClass);
167 soliveira 335
 
336
        /**
337
         * Return a table alias for this bean class with a prefix.
338
         *
339
         * @param beanClass
340
         * @param prefix
341
         * @return TableAlias
342
         */
169 erico 343
        public <E> TableAlias<E> createTableAlias(Class<? extends E> beanClass, String prefix);
167 soliveira 344
 
2 soliveira 345
}