Merge branch 'feature/nesting' into develop

Author: nicolaiparlog

.classpath

@@ -2,7 +2,9 @@
 <classpath>
 	<classpathentry kind="src" path="src"/>
 	<classpathentry kind="src" path="test"/>
+	<classpathentry kind="src" path="demo"/>
 	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
 	<classpathentry kind="con" path="org.eclipse.jdt.junit.JUNIT_CONTAINER/4"/>
+	<classpathentry kind="lib" path="lib/mockito-all-1.9.5.jar" sourcepath="lib/mockito-all-1.9.5.jar"/>
 	<classpathentry kind="output" path="bin"/>
 </classpath>

.gitignore

@@ -4,7 +4,6 @@
 .mtj.tmp/
 
 # Package Files #
-*.jar
 *.war
 *.ear
 

.project

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <projectDescription>
-	<name>CodeFX</name>
+	<name>LibFX</name>
 	<comment></comment>
 	<projects>
 	</projects>

.settings/org.eclipse.jdt.core.prefs

@@ -45,7 +45,7 @@ org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=all_standard_
 org.eclipse.jdt.core.compiler.problem.missingJavadocTags=warning
 org.eclipse.jdt.core.compiler.problem.missingJavadocTagsMethodTypeParameters=enabled
 org.eclipse.jdt.core.compiler.problem.missingJavadocTagsOverriding=disabled
-org.eclipse.jdt.core.compiler.problem.missingJavadocTagsVisibility=default
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagsVisibility=private
 org.eclipse.jdt.core.compiler.problem.missingOverrideAnnotation=warning
 org.eclipse.jdt.core.compiler.problem.missingOverrideAnnotationForInterfaceMethodImplementation=enabled
 org.eclipse.jdt.core.compiler.problem.missingSerialVersion=warning
@@ -156,7 +156,7 @@ org.eclipse.jdt.core.formatter.comment.format_header=true
 org.eclipse.jdt.core.formatter.comment.format_html=true
 org.eclipse.jdt.core.formatter.comment.format_javadoc_comments=true
 org.eclipse.jdt.core.formatter.comment.format_line_comments=false
-org.eclipse.jdt.core.formatter.comment.format_source_code=true
+org.eclipse.jdt.core.formatter.comment.format_source_code=false
 org.eclipse.jdt.core.formatter.comment.indent_parameter_description=true
 org.eclipse.jdt.core.formatter.comment.indent_root_tags=true
 org.eclipse.jdt.core.formatter.comment.insert_new_line_before_root_tags=insert

.settings/org.eclipse.jdt.ui.prefs

@@ -16,6 +16,7 @@ cleanup.convert_to_enhanced_for_loop=false
 cleanup.correct_indentation=true
 cleanup.format_source_code=true
 cleanup.format_source_code_changes_only=false
+cleanup.insert_inferred_type_arguments=false
 cleanup.make_local_variable_final=true
 cleanup.make_parameters_final=false
 cleanup.make_private_fields_final=true
@@ -30,6 +31,7 @@ cleanup.qualify_static_member_accesses_through_subtypes_with_declaring_class=tru
 cleanup.qualify_static_member_accesses_with_declaring_class=true
 cleanup.qualify_static_method_accesses_with_declaring_class=false
 cleanup.remove_private_constructors=true
+cleanup.remove_redundant_type_arguments=true
 cleanup.remove_trailing_whitespaces=true
 cleanup.remove_trailing_whitespaces_all=true
 cleanup.remove_trailing_whitespaces_ignore_empty=false
@@ -52,7 +54,8 @@ cleanup.use_this_for_non_static_field_access=false
 cleanup.use_this_for_non_static_field_access_only_if_necessary=true
 cleanup.use_this_for_non_static_method_access=false
 cleanup.use_this_for_non_static_method_access_only_if_necessary=true
-cleanup_profile=_nipa
+cleanup.use_type_arguments=false
+cleanup_profile=_'nipa'
 cleanup_settings_version=2
 eclipse.preferences.version=1
 editor_save_participant_org.eclipse.jdt.ui.postsavelistener.cleanup=true
@@ -78,6 +81,7 @@ sp_cleanup.convert_to_enhanced_for_loop=false
 sp_cleanup.correct_indentation=true
 sp_cleanup.format_source_code=true
 sp_cleanup.format_source_code_changes_only=false
+sp_cleanup.insert_inferred_type_arguments=false
 sp_cleanup.make_local_variable_final=true
 sp_cleanup.make_parameters_final=false
 sp_cleanup.make_private_fields_final=true
@@ -93,6 +97,7 @@ sp_cleanup.qualify_static_member_accesses_through_subtypes_with_declaring_class=
 sp_cleanup.qualify_static_member_accesses_with_declaring_class=true
 sp_cleanup.qualify_static_method_accesses_with_declaring_class=false
 sp_cleanup.remove_private_constructors=true
+sp_cleanup.remove_redundant_type_arguments=false
 sp_cleanup.remove_trailing_whitespaces=true
 sp_cleanup.remove_trailing_whitespaces_all=true
 sp_cleanup.remove_trailing_whitespaces_ignore_empty=false
@@ -115,3 +120,4 @@ sp_cleanup.use_this_for_non_static_field_access=false
 sp_cleanup.use_this_for_non_static_field_access_only_if_necessary=true
 sp_cleanup.use_this_for_non_static_method_access=false
 sp_cleanup.use_this_for_non_static_method_access_only_if_necessary=true
+sp_cleanup.use_type_arguments=false

README.md

@@ -1,2 +1,53 @@
-codefx
-======
+# LibFX - Nestings
+
+This feature branch revolves around JavaFX properties. The core API provides awesome capabilities but one thing I frequently need is missing: the possibility to interact with properties which are hidden in a more complex object hierarchy.
+
+Below you will find an example of the problem and its solution with some lines of code from **LibFX**. But before we come to that I wanna shortly present this feature's idea.
+
+## Idea
+
+This branch develops a simple and fluent API to create nestings, where a `Nesting` represents a hierarchy like `Employee -> Address -> ZIP code`. The nesting would collapse the hierarchy to the innermost property (in this example `zipProperty`) and update itself whenever the employee or address instances change.
+
+A nesting can than be used in several ways:
+* You can build a property which always holds the innermost value.
+* You can attach a change listener which is carried along as the innermost property changes.
+* You can create bindings which are not only updated when the innermost property's value changes but also when the property itself is replaced.
+
+These further steps can be made with the same fluent API without breaking one's stride. You can find an example below and more in the classes in the folder `demo/org/codefx/libfx/nesting` (look for methods starting with "demo").
+
+## Example
+
+Let's see an example...
+
+### The Situation
+
+Say you have an object of type `Employee` and you're creating an `EmployeeEditor` for editing a single employee at a time. You will most likely have a model for your UI which has something like a `currentEmployeeProperty`.
+Now you might want to bind some properties of the controls you're using for your editor to the current employee's properties. For example you might have a slider and want to bind it to the employee's `salaryProperty`.
+
+### The Problem
+
+Up to now that's all straight forward. But what happens when the current employee is replaced by another? Of course you want your editor to be updated.
+
+### The "Solutions"
+
+You could use `Bindings.select` but it has some downsides. For one thing, it uses strings to identify the nested properties, which breaks down quickly under refactoring. Unfortunately you won't even get an exception when trying to access properties which aren't there anymore - your binding will just forever contain null. Another downside is the return type. It's just an `ObjectBinding` (or `DoubleBinding` or ...) which does not suffice in all use cases.
+
+Another way is to explicitly listen to changes of the model's `currentEmployeeProperty` and update the binding accordingly. That's rather tedious and leads to a lot of the same code all over the place. And it gets even worse, when you're nesting deeper, e.g. binding to the current employee's address' ZIP code.
+
+### The Solution
+
+Use **LibFX**! :)
+
+``` Java
+Nestings.on(currentEmployeeProperty)
+	.nestDouble(employee -> employee.salaryProperty())
+	.bindBidirectional(slider.valueProperty());
+```
+
+``` Java
+Nestings.on(currentEmployeeProperty)
+	.nest(employee -> employee.addressProperty())
+	.nest(address -> address.zipProperty())
+	.addChangeListener(myListener);
+```
+

demo/org/codefx/libfx/nesting/Employee.java

@@ -0,0 +1,92 @@
+package org.codefx.libfx.nesting;
+
+import javafx.beans.property.DoubleProperty;
+import javafx.beans.property.ObjectProperty;
+import javafx.beans.property.Property;
+import javafx.beans.property.SimpleDoubleProperty;
+import javafx.beans.property.SimpleObjectProperty;
+import javafx.beans.property.SimpleStringProperty;
+import javafx.beans.property.StringProperty;
+
+/**
+ * A simple demo class which represents an employee.
+ */
+class Employee {
+
+	/**
+	 * The salary.
+	 */
+	private final DoubleProperty salary;
+
+	/**
+	 * The address.
+	 */
+	private final ObjectProperty<Address> address;
+
+	/**
+	 * Creates a new employee with the specified salary.
+	 *
+	 * @param initialSalary
+	 *            the employee's initial salary
+	 * @param streetName
+	 *            the name of the street the employee lives in
+	 */
+	public Employee(double initialSalary, String streetName) {
+		this.salary = new SimpleDoubleProperty(this, "salary", initialSalary);
+		this.address = new SimpleObjectProperty<>(this, "address", new Address(streetName));
+	}
+
+	/**
+	 * The salary.
+	 *
+	 * @return the salary as a property
+	 */
+	public DoubleProperty salaryProperty() {
+		return salary;
+	}
+
+	/**
+	 * The address.
+	 *
+	 * @return the address as a property
+	 */
+	public Property<Address> addressProperty() {
+		return address;
+	}
+
+	// #region INNER CLASSES
+
+	/**
+	 * A simple demo class which represents an employee's address.
+	 */
+	public static class Address {
+
+		/**
+		 * The street name.
+		 */
+		private final StringProperty streetName;
+
+		/**
+		 * Creates a new address with the specified street name.
+		 *
+		 * @param streetName
+		 *            the name of the street
+		 */
+		public Address(String streetName) {
+			this.streetName = new SimpleStringProperty(this, "streetName", streetName);
+		}
+
+		/**
+		 * The street name.
+		 *
+		 * @return the street name as a property
+		 */
+		public StringProperty streetNameProperty() {
+			return streetName;
+		}
+
+	}
+
+	//#end PRIVATE CLASSES
+
+}