1 /*
2 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javafx.beans.binding;
27
28 import javafx.beans.value.ObservableStringValue;
29 import javafx.beans.value.ObservableValue;
30
31 import com.sun.javafx.binding.StringFormatter;
32
33 /**
34 * {@code StringExpression} is an
35 * {@link javafx.beans.value.ObservableStringValue} plus additional convenience
36 * methods to generate bindings in a fluent style.
37 * <p>
38 * A concrete sub-class of {@code StringExpression} has to implement the method
39 * {@link javafx.beans.value.ObservableStringValue#get()}, which provides the
40 * actual value of this expression.
41 * <p>
42 * Note: all implementation of {@link javafx.beans.binding.BooleanBinding}
43 * returned by the comparisons in this class consider a {@code String} that is
44 * {@code null} equal to an empty {@code String}.
45 * @since JavaFX 2.0
46 */
47 public abstract class StringExpression implements ObservableStringValue {
48
49 @Override
50 public String getValue() {
51 return get();
52 }
53
54 /**
55 * Returns usually the value of this {@code StringExpression}. Only if the
56 * value is {@code null} an empty {@code String} is returned instead.
57 *
58 * @return the value of this {@code StringExpression} or the empty
59 * {@code String}
60 */
61 public final String getValueSafe() {
62 final String value = get();
63 return value == null ? "" : value;
64 }
65
66 /**
67 * Returns a {@code StringExpression} that wraps a
68 * {@link javafx.beans.value.ObservableValue}. If the
69 * {@code ObservableValue} is already a {@code StringExpression}, it will be
70 * returned. Otherwise a new {@link javafx.beans.binding.StringBinding} is
71 * created that holds the value of the {@code ObservableValue} converted to
72 * a {@code String}.
73 *
74 * @param value
75 * The source {@code ObservableValue}
76 * @return A {@code StringExpression} that wraps the {@code ObservableValue}
77 * if necessary
78 * @throws NullPointerException
79 * if {@code value} is {@code null}
80 */
81 public static StringExpression stringExpression(
82 final ObservableValue<?> value) {
83 if (value == null) {
84 throw new NullPointerException("Value must be specified.");
85 }
86 return StringFormatter.convert(value);
87 }
88
89 /**
90 * Returns a {@code StringExpression} that holds the value of this
91 * {@code StringExpression} concatenated with another {@code Object}.
92 * <p>
93 * If the value of this {@code StringExpression} changes, the value of the
94 * resulting {@code StringExpression} is updated automatically. Also if the
95 * other {@code Object} is an implementation of
96 * {@link javafx.beans.value.ObservableValue}, changes in the other
97 * {@code Object} are reflected automatically in the resulting
98 * {@code StringExpression}.
99 *
100 * @param other
101 * the other {@code Object}
102 * @return the new {@code StringExpression}
103 */
104 public StringExpression concat(Object other) {
105 return Bindings.concat(this, other);
106 }
107
108 /**
109 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
110 * if this and another {@link javafx.beans.value.ObservableStringValue} are
111 * equal.
112 * <p>
113 * Note: In this comparison a {@code String} that is {@code null} is
114 * considered equal to an empty {@code String}.
115 *
116 * @param other
117 * the constant value
118 * @return the new {@code BooleanBinding}
119 */
120 public BooleanBinding isEqualTo(final ObservableStringValue other) {
121 return Bindings.equal(this, other);
122 }
123
124 /**
125 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
126 * if this {@code StringExpression} is equal to a constant value.
127 * <p>
128 * Note: In this comparison a {@code String} that is {@code null} is
129 * considered equal to an empty {@code String}.
130 *
131 * @param other
132 * the constant value
133 * @return the new {@code BooleanBinding}
134 */
135 public BooleanBinding isEqualTo(final String other) {
136 return Bindings.equal(this, other);
137 }
138
139 /**
140 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
141 * if this and another {@link javafx.beans.value.ObservableStringValue} are
142 * not equal.
143 * <p>
144 * Note: In this comparison a {@code String} that is {@code null} is
145 * considered equal to an empty {@code String}.
146 *
147 * @param other
148 * the constant value
149 * @return the new {@code BooleanBinding}
150 */
151 public BooleanBinding isNotEqualTo(final ObservableStringValue other) {
152 return Bindings.notEqual(this, other);
153 }
154
155 /**
156 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
157 * if this {@code StringExpression} is not equal to a constant value.
158 * <p>
159 * Note: In this comparison a {@code String} that is {@code null} is
160 * considered equal to an empty {@code String}.
161 *
162 * @param other
163 * the constant value
164 * @return the new {@code BooleanBinding}
165 */
166 public BooleanBinding isNotEqualTo(final String other) {
167 return Bindings.notEqual(this, other);
168 }
169
170 /**
171 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
172 * if this and another {@link javafx.beans.value.ObservableStringValue} are
173 * equal ignoring case.
174 * <p>
175 * Note: In this comparison a {@code String} that is {@code null} is
176 * considered equal to an empty {@code String}.
177 *
178 * @param other
179 * the second {@code ObservableStringValue}
180 * @return the new {@code BooleanBinding}
181 */
182 public BooleanBinding isEqualToIgnoreCase(final ObservableStringValue other) {
183 return Bindings.equalIgnoreCase(this, other);
184 }
185
186 /**
187 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
188 * if this {@code StringExpression} is equal to a constant value ignoring
189 * case.
190 * <p>
191 * Note: In this comparison a {@code String} that is {@code null} is
192 * considered equal to an empty {@code String}.
193 *
194 * @param other
195 * the constant value
196 * @return the new {@code BooleanBinding}
197 */
198 public BooleanBinding isEqualToIgnoreCase(final String other) {
199 return Bindings.equalIgnoreCase(this, other);
200 }
201
202 /**
203 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
204 * if this and another {@link javafx.beans.value.ObservableStringValue} are
205 * not equal ignoring case.
206 * <p>
207 * Note: In this comparison a {@code String} that is {@code null} is
208 * considered equal to an empty {@code String}.
209 *
210 * @param other
211 * the second {@code ObservableStringValue}
212 * @return the new {@code BooleanBinding}
213 */
214 public BooleanBinding isNotEqualToIgnoreCase(
215 final ObservableStringValue other) {
216 return Bindings.notEqualIgnoreCase(this, other);
217 }
218
219 /**
220 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
221 * if this {@code StringExpression} is not equal to a constant value
222 * ignoring case.
223 * <p>
224 * Note: In this comparison a {@code String} that is {@code null} is
225 * considered equal to an empty {@code String}.
226 *
227 * @param other
228 * the constant value
229 * @return the new {@code BooleanBinding}
230 */
231 public BooleanBinding isNotEqualToIgnoreCase(final String other) {
232 return Bindings.notEqualIgnoreCase(this, other);
233 }
234
235 /**
236 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
237 * if this {@code StringExpression} is greater than another
238 * {@link javafx.beans.value.ObservableStringValue}.
239 * <p>
240 * Note: In this comparison a {@code String} that is {@code null} is
241 * considered equal to an empty {@code String}.
242 *
243 * @param other
244 * the second {@code ObservableStringValue}
245 * @return the new {@code BooleanBinding}
246 */
247 public BooleanBinding greaterThan(final ObservableStringValue other) {
248 return Bindings.greaterThan(this, other);
249 }
250
251 /**
252 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
253 * if this {@code StringExpression} is greater than a constant value.
254 * <p>
255 * Note: In this comparison a {@code String} that is {@code null} is
256 * considered equal to an empty {@code String}.
257 *
258 * @param other
259 * the constant value
260 * @return the new {@code BooleanBinding}
261 */
262 public BooleanBinding greaterThan(final String other) {
263 return Bindings.greaterThan(this, other);
264 }
265
266 /**
267 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
268 * if this {@code StringExpression} is less than another
269 * {@link javafx.beans.value.ObservableStringValue}.
270 * <p>
271 * Note: In this comparison a {@code String} that is {@code null} is
272 * considered equal to an empty {@code String}.
273 *
274 * @param other
275 * the second {@code ObservableStringValue}
276 * @return the new {@code BooleanBinding}
277 */
278 public BooleanBinding lessThan(final ObservableStringValue other) {
279 return Bindings.lessThan(this, other);
280 }
281
282 /**
283 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
284 * if this {@code StringExpression} is less than a constant value.
285 * <p>
286 * Note: In this comparison a {@code String} that is {@code null} is
287 * considered equal to an empty {@code String}.
288 *
289 * @param other
290 * the constant value
291 * @return the new {@code BooleanBinding}
292 */
293 public BooleanBinding lessThan(final String other) {
294 return Bindings.lessThan(this, other);
295 }
296
297 /**
298 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
299 * if this {@code StringExpression} is greater than or equal to another
300 * {@link javafx.beans.value.ObservableStringValue}.
301 * <p>
302 * Note: In this comparison a {@code String} that is {@code null} is
303 * considered equal to an empty {@code String}.
304 *
305 * @param other
306 * the second {@code ObservableStringValue}
307 * @return the new {@code BooleanBinding}
308 */
309 public BooleanBinding greaterThanOrEqualTo(final ObservableStringValue other) {
310 return Bindings.greaterThanOrEqual(this, other);
311 }
312
313 /**
314 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
315 * if this {@code StringExpression} is greater than or equal to a constant
316 * value.
317 * <p>
318 * Note: In this comparison a {@code String} that is {@code null} is
319 * considered equal to an empty {@code String}.
320 *
321 * @param other
322 * the constant value
323 * @return the new {@code BooleanBinding}
324 */
325 public BooleanBinding greaterThanOrEqualTo(final String other) {
326 return Bindings.greaterThanOrEqual(this, other);
327 }
328
329 /**
330 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
331 * if this {@code StringExpression} is less than or equal to another
332 * {@link javafx.beans.value.ObservableStringValue}.
333 * <p>
334 * Note: In this comparison a {@code String} that is {@code null} is
335 * considered equal to an empty {@code String}.
336 *
337 * @param other
338 * the second {@code ObservableStringValue}
339 * @return the new {@code BooleanBinding}
340 */
341 public BooleanBinding lessThanOrEqualTo(final ObservableStringValue other) {
342 return Bindings.lessThanOrEqual(this, other);
343 }
344
345 /**
346 * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
347 * if this {@code StringExpression} is less than or equal to a constant
348 * value.
349 * <p>
350 * Note: In this comparison a {@code String} that is {@code null} is
351 * considered equal to an empty {@code String}.
352 *
353 * @param other
354 * the constant value
355 * @return the new {@code BooleanBinding}
356 */
357 public BooleanBinding lessThanOrEqualTo(final String other) {
358 return Bindings.lessThanOrEqual(this, other);
359 }
360
361 /**
362 * Creates a new {@link BooleanBinding} that holds {@code true} if this
363 * {@code StringExpression} is {@code null}.
364 *
365 * @return the new {@code BooleanBinding}
366 */
367 public BooleanBinding isNull() {
368 return Bindings.isNull(this);
369 }
370
371 /**
372 * Creates a new {@link BooleanBinding} that holds {@code true} if this
373 * {@code StringExpression} is not {@code null}.
374 *
375 * @return the new {@code BooleanBinding}
376 */
377 public BooleanBinding isNotNull() {
378 return Bindings.isNotNull(this);
379 }
380
381 /**
382 * Creates a new {@link IntegerBinding} that holds the length of this
383 * {@code StringExpression}.
384 * <p>
385 * Note: If the value of this {@code StringExpression} is {@code null},
386 * the length is considered to be {@code 0}.
387 *
388 * @return the new {@code IntegerBinding}
389 * @since JavaFX 8.0
390 */
391 public IntegerBinding length() {
392 return Bindings.length(this);
393 }
394
395 /**
396 * Creates a new {@link BooleanBinding} that holds {@code true} if this
397 * {@code StringExpression} is empty.
398 * <p>
399 * Note: If the value of this {@code StringExpression} is {@code null},
400 * it is considered to be empty.
401 *
402 * @return the new {@code BooleanBinding}
403 * @since JavaFX 8.0
404 */
405 public BooleanBinding isEmpty() {
406 return Bindings.isEmpty(this);
407 }
408
409 /**
410 * Creates a new {@link BooleanBinding} that holds {@code true} if this
411 * {@code StringExpression} is not empty.
412 * <p>
413 * Note: If the value of this {@code StringExpression} is {@code null},
414 * it is considered to be empty.
415 *
416 * @return the new {@code BooleanBinding}
417 * @since JavaFX 8.0
418 */
419 public BooleanBinding isNotEmpty() {
420 return Bindings.isNotEmpty(this);
421 }
422 }