1 /* 2 * Copyright (c) 2010, 2017, 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 }