Spec-Zone .ru
спецификации, руководства, описания, API
001/*
002 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package javafx.beans.binding;
027
028import javafx.beans.value.ObservableStringValue;
029import javafx.beans.value.ObservableValue;
030
031import com.sun.javafx.binding.StringFormatter;
032
033/**
034 * A {@code StringExpression} is a
035 * {@link javafx.beans.value.ObservableStringValue} plus additional convenience
036 * methods to generate bindings in a fluent style.
037 * <p>
038 * A concrete sub-class of {@code StringExpression} has to implement the method
039 * {@link javafx.beans.value.ObservableStringValue#get()}, which provides the
040 * actual value of this expression.
041 * <p>
042 * Note: all implementation of {@link javafx.beans.binding.BooleanBinding}
043 * returned by the comparisons in this class consider a {@code String} that is
044 * {@code null} equal to an empty {@code String}.
045 */
046public abstract class StringExpression implements ObservableStringValue {
047
048    @Override
049    public String getValue() {
050        return get();
051    }
052
053    /**
054     * Returns usually the value of this {@code StringExpression}. Only if the
055     * value is {@code null} an empty {@code String} is returned instead.
056     * 
057     * @return the value of this {@code StringExpression} or the empty
058     *         {@code String}
059     */
060    public final String getValueSafe() {
061        final String value = get();
062        return value == null ? "" : value;
063    }
064
065    /**
066     * Returns a {@code StringExpression} that wraps a
067     * {@link javafx.beans.value.ObservableValue}. If the
068     * {@code ObservableValue} is already a {@code StringExpression}, it will be
069     * returned. Otherwise a new {@link javafx.beans.binding.StringBinding} is
070     * created that holds the value of the {@code ObservableValue} converted to
071     * a {@code String}.
072     * 
073     * @param value
074     *            The source {@code ObservableValue}
075     * @return A {@code StringExpression} that wraps the {@code ObservableValue}
076     *         if necessary
077     * @throws NullPointerException
078     *             if {@code value} is {@code null}
079     */
080    public static StringExpression stringExpression(
081            final ObservableValue<?> value) {
082        if (value == null) {
083            throw new NullPointerException("Value must be specified.");
084        }
085        return StringFormatter.convert(value);
086    }
087
088    /**
089     * Returns a {@code StringExpression} that holds the value of this
090     * {@code StringExpression} concatenated with another {@code Object}.
091     * <p>
092     * If the value of this {@code StringExpression} changes, the value of the
093     * resulting {@code StringExpression} is updated automatically. Also if the
094     * other {@code Object} is an implementation of
095     * {@link javafx.beans.value.ObservableValue}, changes in the other
096     * {@code Object} are reflected automatically in the resulting
097     * {@code StringExpression}.
098     * 
099     * @param other
100     *            the other {@code Object}
101     * @return the new {@code StringExpression}
102     */
103    public StringExpression concat(Object other) {
104        return Bindings.concat(this, other);
105    }
106
107    /**
108     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
109     * if this and another {@link javafx.beans.value.ObservableStringValue} are
110     * equal.
111     * <p>
112     * Note: In this comparison a {@code String} that is {@code null} is
113     * considered equal to an empty {@code String}.
114     * 
115     * @param other
116     *            the constant value
117     * @return the new {@code BooleanBinding}
118     */
119    public BooleanBinding isEqualTo(final ObservableStringValue other) {
120        return Bindings.equal(this, other);
121    }
122
123    /**
124     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
125     * if this {@code StringExpression} is equal to a constant value.
126     * <p>
127     * Note: In this comparison a {@code String} that is {@code null} is
128     * considered equal to an empty {@code String}.
129     * 
130     * @param other
131     *            the constant value
132     * @return the new {@code BooleanBinding}
133     */
134    public BooleanBinding isEqualTo(final String other) {
135        return Bindings.equal(this, other);
136    }
137
138    /**
139     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
140     * if this and another {@link javafx.beans.value.ObservableStringValue} are
141     * not equal.
142     * <p>
143     * Note: In this comparison a {@code String} that is {@code null} is
144     * considered equal to an empty {@code String}.
145     * 
146     * @param other
147     *            the constant value
148     * @return the new {@code BooleanBinding}
149     */
150    public BooleanBinding isNotEqualTo(final ObservableStringValue other) {
151        return Bindings.notEqual(this, other);
152    }
153
154    /**
155     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
156     * if this {@code StringExpression} is not equal to a constant value.
157     * <p>
158     * Note: In this comparison a {@code String} that is {@code null} is
159     * considered equal to an empty {@code String}.
160     * 
161     * @param other
162     *            the constant value
163     * @return the new {@code BooleanBinding}
164     */
165    public BooleanBinding isNotEqualTo(final String other) {
166        return Bindings.notEqual(this, other);
167    }
168
169    /**
170     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
171     * if this and another {@link javafx.beans.value.ObservableStringValue} are
172     * equal ignoring case.
173     * <p>
174     * Note: In this comparison a {@code String} that is {@code null} is
175     * considered equal to an empty {@code String}.
176     * 
177     * @param other
178     *            the second {@code ObservableStringValue}
179     * @return the new {@code BooleanBinding}
180     */
181    public BooleanBinding isEqualToIgnoreCase(final ObservableStringValue other) {
182        return Bindings.equalIgnoreCase(this, other);
183    }
184
185    /**
186     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
187     * if this {@code StringExpression} is equal to a constant value ignoring
188     * case.
189     * <p>
190     * Note: In this comparison a {@code String} that is {@code null} is
191     * considered equal to an empty {@code String}.
192     * 
193     * @param other
194     *            the constant value
195     * @return the new {@code BooleanBinding}
196     */
197    public BooleanBinding isEqualToIgnoreCase(final String other) {
198        return Bindings.equalIgnoreCase(this, other);
199    }
200
201    /**
202     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
203     * if this and another {@link javafx.beans.value.ObservableStringValue} are
204     * not equal ignoring case.
205     * <p>
206     * Note: In this comparison a {@code String} that is {@code null} is
207     * considered equal to an empty {@code String}.
208     * 
209     * @param other
210     *            the second {@code ObservableStringValue}
211     * @return the new {@code BooleanBinding}
212     */
213    public BooleanBinding isNotEqualToIgnoreCase(
214            final ObservableStringValue other) {
215        return Bindings.notEqualIgnoreCase(this, other);
216    }
217
218    /**
219     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
220     * if this {@code StringExpression} is not equal to a constant value
221     * ignoring case.
222     * <p>
223     * Note: In this comparison a {@code String} that is {@code null} is
224     * considered equal to an empty {@code String}.
225     * 
226     * @param other
227     *            the constant value
228     * @return the new {@code BooleanBinding}
229     */
230    public BooleanBinding isNotEqualToIgnoreCase(final String other) {
231        return Bindings.notEqualIgnoreCase(this, other);
232    }
233
234    /**
235     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
236     * if this {@code StringExpression} is greater than another
237     * {@link javafx.beans.value.ObservableStringValue}.
238     * <p>
239     * Note: In this comparison a {@code String} that is {@code null} is
240     * considered equal to an empty {@code String}.
241     * 
242     * @param other
243     *            the second {@code ObservableStringValue}
244     * @return the new {@code BooleanBinding}
245     */
246    public BooleanBinding greaterThan(final ObservableStringValue other) {
247        return Bindings.greaterThan(this, other);
248    }
249
250    /**
251     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
252     * if this {@code StringExpression} is greater than a constant value.
253     * <p>
254     * Note: In this comparison a {@code String} that is {@code null} is
255     * considered equal to an empty {@code String}.
256     * 
257     * @param other
258     *            the constant value
259     * @return the new {@code BooleanBinding}
260     */
261    public BooleanBinding greaterThan(final String other) {
262        return Bindings.greaterThan(this, other);
263    }
264
265    /**
266     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
267     * if this {@code StringExpression} is less than another
268     * {@link javafx.beans.value.ObservableStringValue}.
269     * <p>
270     * Note: In this comparison a {@code String} that is {@code null} is
271     * considered equal to an empty {@code String}.
272     * 
273     * @param other
274     *            the second {@code ObservableStringValue}
275     * @return the new {@code BooleanBinding}
276     */
277    public BooleanBinding lessThan(final ObservableStringValue other) {
278        return Bindings.lessThan(this, other);
279    }
280
281    /**
282     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
283     * if this {@code StringExpression} is less than a constant value.
284     * <p>
285     * Note: In this comparison a {@code String} that is {@code null} is
286     * considered equal to an empty {@code String}.
287     * 
288     * @param other
289     *            the constant value
290     * @return the new {@code BooleanBinding}
291     */
292    public BooleanBinding lessThan(final String other) {
293        return Bindings.lessThan(this, other);
294    }
295
296    /**
297     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
298     * if this {@code StringExpression} is greater than or equal to another
299     * {@link javafx.beans.value.ObservableStringValue}.
300     * <p>
301     * Note: In this comparison a {@code String} that is {@code null} is
302     * considered equal to an empty {@code String}.
303     * 
304     * @param other
305     *            the second {@code ObservableStringValue}
306     * @return the new {@code BooleanBinding}
307     */
308    public BooleanBinding greaterThanOrEqualTo(final ObservableStringValue other) {
309        return Bindings.greaterThanOrEqual(this, other);
310    }
311
312    /**
313     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
314     * if this {@code StringExpression} is greater than or equal to a constant
315     * value.
316     * <p>
317     * Note: In this comparison a {@code String} that is {@code null} is
318     * considered equal to an empty {@code String}.
319     * 
320     * @param other
321     *            the constant value
322     * @return the new {@code BooleanBinding}
323     */
324    public BooleanBinding greaterThanOrEqualTo(final String other) {
325        return Bindings.greaterThanOrEqual(this, other);
326    }
327
328    /**
329     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
330     * if this {@code StringExpression} is less than or equal to another
331     * {@link javafx.beans.value.ObservableStringValue}.
332     * <p>
333     * Note: In this comparison a {@code String} that is {@code null} is
334     * considered equal to an empty {@code String}.
335     * 
336     * @param other
337     *            the second {@code ObservableStringValue}
338     * @return the new {@code BooleanBinding}
339     */
340    public BooleanBinding lessThanOrEqualTo(final ObservableStringValue other) {
341        return Bindings.lessThanOrEqual(this, other);
342    }
343
344    /**
345     * Creates a new {@link javafx.beans.binding.BooleanBinding} that holds {@code true}
346     * if this {@code StringExpression} is less than or equal to a constant
347     * value.
348     * <p>
349     * Note: In this comparison a {@code String} that is {@code null} is
350     * considered equal to an empty {@code String}.
351     * 
352     * @param other
353     *            the constant value
354     * @return the new {@code BooleanBinding}
355     */
356    public BooleanBinding lessThanOrEqualTo(final String other) {
357        return Bindings.lessThanOrEqual(this, other);
358    }
359    
360    /**
361     * Creates a new {@link BooleanBinding} that holds {@code true} if this
362     * {@code StringExpression} is {@code null}.
363     * 
364     * @return the new {@code BooleanBinding}
365     */
366    public BooleanBinding isNull() {
367        return Bindings.isNull(this);
368    }
369    
370    /**
371     * Creates a new {@link BooleanBinding} that holds {@code true} if this
372     * {@code StringExpression} is not {@code null}.
373     * 
374     * @return the new {@code BooleanBinding}
375     */
376    public BooleanBinding isNotNull() {
377        return Bindings.isNotNull(this);
378    }
379
380    /**
381     * Creates a new {@link IntegerBinding} that holds the length of this
382     * {@code StringExpression}.
383     * <p>
384     * Note: If the value of this {@code StringExpression} is {@code null},
385     * the length is considered to be {@code 0}.
386     *
387     * @return the new {@code IntegerBinding}
388     */
389    public IntegerBinding length() {
390        return Bindings.length(this);
391    }
392
393    /**
394     * Creates a new {@link BooleanBinding} that holds {@code true} if this
395     * {@code StringExpression} is empty.
396     * <p>
397     * Note: If the value of this {@code StringExpression} is {@code null},
398     * it is considered to be empty.
399     *
400     * @return the new {@code BooleanBinding}
401     */
402    public BooleanBinding isEmpty() {
403        return Bindings.isEmpty(this);
404    }
405
406    /**
407     * Creates a new {@link BooleanBinding} that holds {@code true} if this
408     * {@code StringExpression} is not empty.
409     * <p>
410     * Note: If the value of this {@code StringExpression} is {@code null},
411     * it is considered to be empty.
412     *
413     * @return the new {@code BooleanBinding}
414     */
415    public BooleanBinding isNotEmpty() {
416        return Bindings.isNotEmpty(this);
417    }
418}