Merge branch 'feature/nesting_missing' into develop

Author: nicolaiparlog

src/demo/java/org/codefx/libfx/nesting/NestedDemo.java

@@ -50,7 +50,8 @@ public static void main(String[] args) {
 		demo.nestedPropertyCreation();
 		demo.nestedPropertyCreationWithBuilder();
 		demo.nestedPropertyBinding();
-		demo.nestedPropertyBindingWithMissingInnerObservable();
+		demo.nestedPropertyBindingWithMissingInnerObservableAndDefaultBehavior();
+		demo.nestedPropertyBindingWithMissingInnerObservableAndCustomizedBehavior();
 		demo.additionalNestedFeatures();
 	}
 
@@ -281,10 +282,11 @@ private void nestedPropertyBinding() {
 	}
 
 	/**
-	 * Demonstrates how a {@link NestedProperty} behaves when the inner observable is missing.
+	 * Demonstrates how a {@link NestedProperty} behaves by default when the inner observable is missing.
 	 */
-	private void nestedPropertyBindingWithMissingInnerObservable() {
-		print("NESTED PROPERTY BINDING WHEN INNER OBSERVABLE IS MISSING");
+	private void nestedPropertyBindingWithMissingInnerObservableAndDefaultBehavior() {
+		print("NESTED PROPERTY BINDING WHEN INNER OBSERVABLE IS MISSING (DEFAULT)");
+		currentEmployee.getValue().addressProperty().getValue().streetNameProperty().set("Some Street");
 
 		// create a nested property for the current employee's street name
 		NestedStringProperty currentEmployeesStreetName = Nestings.on(currentEmployee)
@@ -298,8 +300,43 @@ private void nestedPropertyBindingWithMissingInnerObservable() {
 		print("The inner observable is now missing (is present: \""
 				+ currentEmployeesStreetName.isInnerObservablePresent() + "\")");
 
-		currentEmployeesStreetName.set("Null Street");
-		print("The nested property can still be changed: \"" + currentEmployeesStreetName.get() + "\"");
+		try {
+			currentEmployeesStreetName.set("Null Street");
+			print("You should never see this on the console.");
+		} catch (Exception ex) {
+			print("By default, the nested property can not be changed: " + ex.getClass());
+			// reset the example to a proper state
+			currentEmployee.getValue().addressProperty().setValue(new Employee.Address("Some Street"));
+		}
+
+		print();
+	}
+
+	/**
+	 * Demonstrates how a {@link NestedProperty} can be configured to behave differently when the inner observable is
+	 * missing.
+	 */
+	private void nestedPropertyBindingWithMissingInnerObservableAndCustomizedBehavior() {
+		print("NESTED PROPERTY BINDING WHEN INNER OBSERVABLE IS MISSING (CUSTOM)");
+
+		// create a nested property for the current employee's street name
+		NestedStringProperty currentEmployeesStreetName = Nestings.on(currentEmployee)
+				.nest(Employee::addressProperty)
+				.nestStringProperty(Address::streetNameProperty)
+				.buildPropertyWithBuilder()
+				.onInnerObservableMissingSetValue("Null street")
+				.onUpdateWhenInnerObservableMissingAcceptValues()
+				.build();
+
+		print("Nested property's initial street name: \"" + currentEmployeesStreetName.get() + "\"");
+
+		currentEmployee.getValue().addressProperty().setValue(null);
+		print("The inner observable is now missing (is present: \""
+				+ currentEmployeesStreetName.isInnerObservablePresent() + "\")");
+		print("The street name changed to the specified value: \"" + currentEmployeesStreetName.get() + "\"");
+
+		currentEmployeesStreetName.set("Another Street");
+		print("The nested property can be changed: \"" + currentEmployeesStreetName.get() + "\"");
 
 		currentEmployee.getValue().addressProperty().setValue(new Employee.Address("New Street"));
 		print("When a new inner observable is present (\"" + currentEmployeesStreetName.isInnerObservablePresent()

src/main/java/org/codefx/libfx/nesting/Nesting.java

@@ -8,10 +8,11 @@
 
 /**
  * <p>
- * A nesting encapsulates a hierarchy of nested {@link ObservableValue ObservableValues} and its
- * {@link #innerObservableProperty() innerObservable} property always contains the current innermost {@code Observable}
- * in that hierarchy as an {@link Optional}. A {@code Nesting} can be used as a basic building block for other nested
- * functionality.
+ * A nesting encapsulates a hierarchy of nested {@link ObservableValue ObservableValues}.
+ * <p>
+ * Its {@link #innerObservableProperty() innerObservable} property always contains the current innermost
+ * {@code Observable} in that hierarchy as an {@link Optional}. A {@code Nesting} can be used as a basic building block
+ * for other nested functionality.
  * <h2>Nesting Hierarchy</h2> A nesting hierarchy is composed of some {@code ObservableValues}, often simply called
  * <b>observables</b>, and <b>nesting steps</b> which lead from one observable to the next.
  * <p>
@@ -24,7 +25,7 @@
  * Hence they must all implement {@link ObservableValue ObservableValue}. No step is used on the inner observable so it
  * suffices that it implements {@link Observable}.
  * <h3>Example</h3> Consider a class {@code Employee} which has an {@code Property<Address> address}, where
- * {@code Address} has a {@code StringProperty streetName}. There might be a {@code Property<Emplyee> currentEmployee},
+ * {@code Address} has a {@code StringProperty streetName}. There might be a {@code Property<Employee> currentEmployee},
  * which always holds the current employee.
  * <p>
  * In this case the hierarchy would be {@code currentEmployee -> address -> streetName} where {@code currentEmployee} is