Skip to content

Commit 0177086

Browse files
fugerit79fugerit79
committed
Documenting QueryHelper api
1 parent c7aa4e0 commit 0177086

File tree

2 files changed

+252
-12
lines changed

2 files changed

+252
-12
lines changed

‎fj-core/src/main/java/org/fugerit/java/core/db/daogen/QueryHelper.java‎

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,56 @@
22

33
import org.fugerit.java.core.db.dao.FieldList;
44

5+
/**
6+
*
7+
* QueryHelper is basically a wrapper which encapsulates information needed to setup a <code>java.sql.PreparedStatement</code>.
8+
*
9+
* This is achieved by use of a query buffer (getQuery()) and a list of field (getFields())
10+
*
11+
* Here is a very simple example :
12+
*
13+
* <code>
14+
* QueryHelper helper = new QueryHelper( "sample_table", new FieldList() );
15+
* helper.get
16+
* </code>
17+
*
18+
* @author Matteo Franci a.k.a. Fugerit
19+
*
20+
*/
521
public class QueryHelper extends BasicHelper {
622

723
private static final long serialVersionUID = -5078435202864156086L;
824

25+
/**
26+
* Constant for '('
27+
*/
928
public static final String OPEN_PARA = " ( ";
1029

30+
/**
31+
* Constant for ')'
32+
*/
1133
public static final String CLOSE_PARA = " ) ";
1234

35+
/**
36+
* Constant for '?'
37+
*/
1338
public static final String QUESTION_MARK = " ? ";
1439

40+
/**
41+
* Constant for ' '
42+
*/
43+
public static final String WHITESPACE = " ";
44+
45+
/**
46+
* Add '(' to query buffer
47+
*/
1548
public void openPara() {
1649
this.appendToQuery( OPEN_PARA );
1750
}
18-
51+
52+
/**
53+
* Add ')' to query buffer
54+
*/
1955
public void closePara() {
2056
this.appendToQuery( CLOSE_PARA );
2157
}
@@ -26,17 +62,36 @@ public void closePara() {
2662

2763
private String table;
2864

65+
/**
66+
* Getter method for the query buffer
67+
*
68+
* @return the query buffer
69+
*/
2970
public StringBuilder getQuery() {
3071
return query;
3172
}
3273

74+
/**
75+
* Getter method for the field list
76+
*
77+
* @return the field list
78+
*/
3379
public FieldList getFields() {
3480
return fields;
3581
}
3682

3783
public String getTable() {
3884
return table;
3985
}
86+
87+
public QueryHelper append( String s ) {
88+
this.getQuery().append( s );
89+
return this;
90+
}
91+
92+
public QueryHelper appendWithSpace( String s ) {
93+
return this.append( WHITESPACE ).append( s ).append( WHITESPACE );
94+
}
4095

4196
public void appendToQuery( String s ) {
4297
this.getQuery().append( s );
@@ -54,6 +109,12 @@ public QueryHelper( String table, FieldList fl ) {
54109
this.table = table;
55110
}
56111

112+
/**
113+
* Builds the query context of all query buffer.
114+
* (To be preferred to getQuery().toString() method).
115+
*
116+
* @return the current query content
117+
*/
57118
public String getQueryContent() {
58119
return this.getQuery().toString();
59120
}

‎fj-core/src/main/java/org/fugerit/java/core/db/daogen/SelectHelper.java‎

Lines changed: 190 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,30 +8,76 @@
88
import org.fugerit.java.core.db.dao.FieldList;
99
import org.fugerit.java.core.lang.helpers.StringUtils;
1010

11+
/**
12+
*
13+
* Query helper for select operations.
14+
*
15+
* {@link QueryHelper} for basic informations.
16+
*
17+
* @author Matteo Franci a.k.a. Fugerit
18+
*
19+
*/
1120
public class SelectHelper extends QueryHelper {
1221

22+
/**
23+
* Constant for empty string
24+
*/
1325
public static final String MODE_NONE = "";
1426

27+
/**
28+
* Constant for 'AND'
29+
*/
1530
public static final String MODE_AND = " AND ";
1631

32+
/**
33+
* Constant for 'OR'
34+
*/
1735
public static final String MODE_OR = " OR ";
1836

37+
/**
38+
* Constant for '='
39+
*/
1940
public static final String COMPARE_EQUAL = " = ";
2041

42+
/**
43+
* Constant for '&lt;&gt;'
44+
*/
2145
public static final String COMPARE_DIFFERENT = " <> ";
2246

47+
48+
/**
49+
* Constant for '&lt;'
50+
*/
2351
public static final String COMPARE_LT = " < ";
2452

53+
/**
54+
* Constant for '&gt;'
55+
*/
2556
public static final String COMPARE_GT = " > ";
2657

58+
/**
59+
* Constant for 'LIKE'
60+
*/
2761
public static final String COMPARE_LIKE = " LIKE ";
2862

63+
/**
64+
* Constant for '&lt;='
65+
*/
2966
public static final String COMPARE_LT_EQUAL = " <= ";
30-
67+
68+
/**
69+
* Constant for '&gt;='
70+
*/
3171
public static final String COMPARE_GT_EQUAL = " >= ";
32-
72+
73+
/**
74+
* Constant for 'ASC'
75+
*/
3376
public static final String ORDER_ASC = "ASC";
3477

78+
/**
79+
* Constant for 'DESC'
80+
*/
3581
public static final String ORDER_DESC = "DESC";
3682

3783
/**
@@ -61,54 +107,187 @@ public static SelectHelper newCustomSelectHelper( String table, FieldList fl, bo
61107
return helper;
62108
}
63109

110+
/**
111+
* Constructor for a SelectHelper
112+
*
113+
* @param table the table to be wrapped
114+
* @param fl the field list
115+
*/
64116
public SelectHelper( String table, FieldList fl ) {
65117
super( table, fl );
66118
this.firstParam = true;
67119
this.orderByList = new ArrayList<>();
68120
}
69121

122+
/**
123+
* Initialize this helper.
124+
*
125+
*/
70126
public void initSelectEntity() {
71127
this.getQuery().append( "SELECT * FROM " );
72128
this.getQuery().append( this.getTable() );
73129
}
74130

75-
public boolean addParam( String columnName, Object value, String mode, String compare ) {
131+
/**
132+
* If no field has been set, WHERE will be added, otherwise 'mode' will be added.
133+
*
134+
* @param mode the mode to be added ( AND, OR )
135+
* @return <code>true</code> if WHERE has been added, <code>false</code> otherwise.
136+
*
137+
* @since 8.0.1
138+
*/
139+
public boolean addWhereOrMode( String mode ) {
140+
boolean res = this.firstParam;
141+
if ( this.firstParam ) {
142+
this.firstParam = false;
143+
this.getQuery().append( " WHERE " );
144+
} else {
145+
this.getQuery().append( mode );
146+
}
147+
return res;
148+
}
149+
150+
/**
151+
* Add a parameter to the query.
152+
* The parameter is added if and only if the value is not null.
153+
* If you want to add a null comparison use addNullComparison() method()
154+
*
155+
* @param columnName the name of the column
156+
* @param value the value
157+
* @param mode the mode (AND, OR)
158+
* @param compare the comparison type ( = , &lt;&gt;, &gt;, &lt;, &lt;=, &gt;=, LIKE )
159+
* @param parameter the parameter (for example section '?' or 'UPPER(?)')
160+
* @return <code>true</code> if the parameter has been added, <code>false</code> otherwise.
161+
*
162+
* @since 8.0.1
163+
*/
164+
public boolean addParam( String columnName, Object value, String mode, String compare, String parameter ) {
76165
boolean added = (value != null);
77166
if ( added ) {
78-
if ( this.firstParam ) {
79-
this.firstParam = false;
80-
this.getQuery().append( " WHERE " );
81-
} else {
82-
this.getQuery().append( mode );
83-
}
167+
this.addWhereOrMode(mode);
84168
this.getQuery().append( columnName );
85169
this.getQuery().append( compare );
86-
this.getQuery().append( QUESTION_MARK );
170+
this.getQuery().append( parameter );
87171
this.getFields().addField( value );
88172
}
89173
return added;
90174
}
175+
176+
/**
177+
* Add a NULL check to the query.
178+
*
179+
* @param columnName the name of the column
180+
* @param isNull <code>true</code> to add 'IS NULL' check, <code>false</code> to add 'IS NOT NULL' check.
181+
* @param mode the mode (AND, OR)
182+
* @return <code>true</code> if the parameter has been added, <code>false</code> otherwise.
183+
*
184+
* @since 8.0.1
185+
*/
186+
public boolean addNullComparison( String columnName, String mode, boolean isNull ) {
187+
boolean res = true;
188+
this.addWhereOrMode(mode);
189+
this.getQuery().append( columnName );
190+
if ( isNull ) {
191+
this.getQuery().append( " IS NULL " );
192+
} else {
193+
this.getQuery().append( " IS NOT NULL " );
194+
}
195+
return res;
196+
}
197+
198+
199+
/**
200+
* Add a parameter to the query.
201+
* The parameter is added if and only if the value is not null.
202+
* If you want to add a null comparison use addNullComparison() method()
203+
* The parameter will be added as a parameter (?) for prepared statement
204+
*
205+
* @param columnName the name of the column
206+
* @param value the value
207+
* @param mode the mode (AND, OR)
208+
* @param compare the comparison type ( = , &lt;&gt;, &gt;, &lt;, &lt;=, &gt;=, LIKE )
209+
* @return <code>true</code> if the parameter has been added, <code>false</code> otherwise.
210+
*
211+
*/
212+
public boolean addParam( String columnName, Object value, String mode, String compare ) {
213+
return this.addParam(columnName, value, mode, compare, QUESTION_MARK);
214+
}
91215

216+
/**
217+
* Add a parameter to the query.
218+
* The parameter is added if and only if the value is not null.
219+
* If you want to add a null comparison use addNullComparison() method().
220+
* The parameter will be added as a parameter (?) for prepared statement.
221+
* The mode will be OR and the comparison =
222+
*
223+
* @param columnName the name of the column
224+
* @param value the value
225+
* @return <code>true</code> if the parameter has been added, <code>false</code> otherwise.
226+
*/
92227
public boolean orEqualParam( String columnName, Object value ) {
93228
return this.addParam( columnName , value, MODE_OR, COMPARE_EQUAL );
94229
}
95-
230+
231+
/**
232+
* Add a parameter to the query.
233+
* The parameter is added if and only if the value is not null.
234+
* If you want to add a null comparison use addNullComparison() method().
235+
* The parameter will be added as a parameter (?) for prepared statement.
236+
* The mode will be OR and the comparison LIKE
237+
*
238+
* @param columnName the name of the column
239+
* @param value the value
240+
* @return <code>true</code> if the parameter has been added, <code>false</code> otherwise.
241+
*/
96242
public boolean orLikeParam( String columnName, Object value ) {
97243
return this.addParam( columnName , value, MODE_OR, COMPARE_LIKE );
98244
}
99245

246+
/**
247+
* Add a parameter to the query.
248+
* The parameter is added if and only if the value is not null.
249+
* If you want to add a null comparison use addNullComparison() method().
250+
* The parameter will be added as a parameter (?) for prepared statement.
251+
* The mode will be AND and the comparison =
252+
*
253+
* @param columnName the name of the column
254+
* @param value the value
255+
* @return <code>true</code> if the parameter has been added, <code>false</code> otherwise.
256+
*/
100257
public boolean andEqualParam( String columnName, Object value ) {
101258
return this.addParam( columnName , value, MODE_AND, COMPARE_EQUAL );
102259
}
103260

261+
/**
262+
* Add a parameter to the query.
263+
* The parameter is added if and only if the value is not null.
264+
* If you want to add a null comparison use addNullComparison() method().
265+
* The parameter will be added as a parameter (?) for prepared statement.
266+
* The mode will be AND and the comparison LIKE
267+
*
268+
* @param columnName the name of the column
269+
* @param value the value
270+
* @return <code>true</code> if the parameter has been added, <code>false</code> otherwise.
271+
*/
104272
public boolean andLikeParam( String columnName, Object value ) {
105273
return this.addParam( columnName , value, MODE_AND, COMPARE_LIKE );
106274
}
107275

276+
/**
277+
* Add ORDER BY to the query.
278+
*
279+
* @param columnName the column name
280+
* @param orderByMode the order mode (ASC, DESC)
281+
*/
108282
public void addOrderBy( String columnName, String orderByMode ) {
109283
this.orderByList.add( new OrderByHandler(columnName, orderByMode) );
110284
}
111285

286+
/**
287+
* Directly add ORDER BY to the query.
288+
*
289+
* @param orderBy string "ORDER BY ${orderBy}" will be added to the query buffer.
290+
*/
112291
public void addOrderBy( String orderBy ) {
113292
if ( StringUtils.isNotEmpty( orderBy ) ) {
114293
this.appendToQuery( " ORDER BY " );

0 commit comments

Comments
 (0)