Unified names and comments for methods which return a handle with respect to whether the handle is initially attached or not.

Author: nicolaiparlog

src/demo/java/org/codefx/libfx/control/ControlPropertyListenerDemo.java

@@ -55,7 +55,7 @@ private void simpleCase() {
 		ControlProperties.<String> on(properties)
 				.forKey("Key")
 				.processValue(value -> System.out.println(" -> " + value))
-				.build();
+				.buildAttached();
 
 		// set values of the correct type for the correct key
 		System.out.print("Set \"Value\" for the correct key for the first time: ");
@@ -119,7 +119,7 @@ private void timeNoTypeCheck() {
 		ControlProperties.<String> on(properties)
 				.forKey("Key")
 				.processValue(unreached)
-				.build();
+				.buildAttached();
 
 		// add a couple of values of the wrong type to average the time that takes
 		Integer valueOfWrongType = 5;
@@ -151,7 +151,7 @@ ControlProperties.<String> on(properties)
 				.forKey("Key")
 				.forValueType(String.class)
 				.processValue(unreached)
-				.build();
+				.buildAttached();
 
 		// add a couple of values of the wrong type to average the time that takes
 		Integer valueOfWrongType = 5;

src/demo/java/org/codefx/libfx/listener/handle/ListenerHandleDemo.java

@@ -69,12 +69,11 @@ private void createCustomListenerHandle() {
 
 		// use 'ListenerHandles' to get a 'ListenerHandleBuilder' which can be used to create a handle for this
 		// observable and listener
-		ListenerHandle handleForCustomClasses = ListenerHandles
+		ListenerHandles
 				.createFor(customObservable, customListener)
 				.onAttach((observable, listener) -> observable.addListener(listener))
 				.onDetach((observable, listener) -> observable.removeListener(listener))
-				.build();
-		handleForCustomClasses.attach();
+				.buildAttached();
 	}
 
 	// attach & detach

src/main/java/org/codefx/libfx/control/properties/ControlPropertyListenerBuilder.java

@@ -20,7 +20,7 @@
  * case occurs frequently, specifying the type to allow the check will improve performance considerably.
  * <p>
  * A typical use looks like this:
- * 
+ *
  * <pre>
  * ControlProperties.<Boolean> on(control.getProperties())
  * 	.forKey("visible")
@@ -120,7 +120,7 @@ public ControlPropertyListenerBuilder<T> forValueType(Class<T> valueType) {
 	}
 
 	/**
-	 * Sets the processor for the key's values. This must be called before {@link #build()}.
+	 * Sets the processor for the key's values. This must be called before {@link #buildAttached()}.
 	 *
 	 * @param valueProcessor
 	 *            the {@link Consumer} for the key's values
@@ -140,10 +140,10 @@ public ControlPropertyListenerBuilder<T> processValue(Consumer<? super T> valueP
 	 * Creates a new property listener according to the arguments specified before and
 	 * {@link ControlPropertyListenerHandle#attach() attaches} it.
 	 *
-	 * @return a {@link ControlPropertyListenerHandle}
-	 * @see ControlPropertyListenerHandle#attach()
+	 * @return a {@link ControlPropertyListenerHandle}; initially attached
+	 * @see #buildDetached()
 	 */
-	public ControlPropertyListenerHandle build() {
+	public ControlPropertyListenerHandle buildAttached() {
 		ControlPropertyListenerHandle listener = buildDetached();
 		listener.attach();
 		return listener;
@@ -155,9 +155,8 @@ public ControlPropertyListenerHandle build() {
 	 * Note that this builder is not yet attached to the map! This can be done by calling
 	 * {@link ControlPropertyListenerHandle#attach() attach()} on the returned instance.
 	 *
-	 * @return a {@link ControlPropertyListenerHandle}
-	 * @see #build()
-	 * @see ControlPropertyListenerHandle#attach()
+	 * @return a {@link ControlPropertyListenerHandle}; initially detached
+	 * @see #buildAttached()
 	 */
 	public ControlPropertyListenerHandle buildDetached() {
 		checkFields();

src/main/java/org/codefx/libfx/control/webview/WebViews.java

@@ -41,9 +41,8 @@ private WebViews() {
 	 *            the {@link WebView} to which the listener will be added
 	 * @param listener
 	 *            the {@link WebViewHyperlinkListener} to add to the web view
-	 * @return a handle on the created listener which allows to attach and detach it
+	 * @return a handle on the created listener which allows to attach and detach it; initially detached
 	 * @see WebViews#addHyperlinkListener(WebView, WebViewHyperlinkListener)
-	 * @see WebViewHyperlinkListenerHandle#attach()
 	 */
 	public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
 			WebView webView, WebViewHyperlinkListener listener) {
@@ -65,18 +64,14 @@ public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
 	 *            the {@link WebViewHyperlinkListener} to add to the web view
 	 * @param eventType
 	 *            the {@link EventType} of all events passed to the listener
-	 * @return a handle on the created listener which allows to attach and detach it
+	 * @return a handle on the created listener which allows to attach and detach it; initially detached
 	 * @see WebViews#addHyperlinkListener(WebView, WebViewHyperlinkListener, EventType)
-	 * @see WebViewHyperlinkListenerHandle#attach()
 	 */
 	public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
 			WebView webView, WebViewHyperlinkListener listener, EventType eventType) {
 
 		Objects.requireNonNull(eventType, "The argument 'eventType' must not be null.");
-		WebViewHyperlinkListenerHandle listenerHandle =
-				addHyperlinkListenerDetached(webView, listener, Optional.of(eventType));
-		listenerHandle.attach();
-		return listenerHandle;
+		return addHyperlinkListenerDetached(webView, listener, Optional.of(eventType));
 	}
 
 	// create and attach listener handles
@@ -89,9 +84,8 @@ public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
 	 *            the {@link WebView} to which the listener will be added
 	 * @param listener
 	 *            the {@link WebViewHyperlinkListener} to add to the web view
-	 * @return a handle on the created listener which allows to attach and detach it
+	 * @return a handle on the created listener which allows to attach and detach it; initially attached
 	 * @see #createHyperlinkListenerHandle(WebView, WebViewHyperlinkListener)
-	 * @see WebViewHyperlinkListenerHandle#attach()
 	 */
 	public static WebViewHyperlinkListenerHandle addHyperlinkListener(
 			WebView webView, WebViewHyperlinkListener listener) {
@@ -112,9 +106,8 @@ public static WebViewHyperlinkListenerHandle addHyperlinkListener(
 	 *            the {@link WebViewHyperlinkListener} to add to the web view
 	 * @param eventType
 	 *            the {@link EventType} of all events passed to the listener
-	 * @return a handle on the created listener which allows to attach and detach it
+	 * @return a handle on the created listener which allows to attach and detach it; initially attached
 	 * @see #createHyperlinkListenerHandle(WebView, WebViewHyperlinkListener, EventType)
-	 * @see WebViewHyperlinkListenerHandle#attach()
 	 */
 	public static WebViewHyperlinkListenerHandle addHyperlinkListener(
 			WebView webView, WebViewHyperlinkListener listener, EventType eventType) {

src/main/java/org/codefx/libfx/listener/handle/ListenerHandleBuilder.java

@@ -147,14 +147,28 @@ public ListenerHandleBuilder<O, L> onDetach(BiConsumer<? super O, ? super L> rem
 	}
 
 	/**
-	 * Creates a new listener handle. This will only succeed if {@link #onAttach(BiConsumer)} and
+	 * Creates a new listener handle and attaches the listener. This will only succeed if {@link #onAttach(BiConsumer)}
+	 * and {@link #onDetach(BiConsumer)} have been called.
+	 *
+	 * @return a new {@link ListenerHandle}; initially attached
+	 * @throws IllegalStateException
+	 *             if {@link #onAttach(BiConsumer)} or {@link #onDetach(BiConsumer)} have not been called
+	 */
+	public ListenerHandle buildAttached() throws IllegalStateException {
+		ListenerHandle handle = buildDetached();
+		handle.attach();
+		return handle;
+	}
+
+	/**
+	 * Creates a new, initially detached listener handle. This will only succeed if {@link #onAttach(BiConsumer)} and
 	 * {@link #onDetach(BiConsumer)} have been called.
 	 *
 	 * @return a new {@link ListenerHandle}; initially detached
 	 * @throws IllegalStateException
 	 *             if {@link #onAttach(BiConsumer)} or {@link #onDetach(BiConsumer)} have not been called
 	 */
-	public ListenerHandle build() throws IllegalStateException {
+	public ListenerHandle buildDetached() throws IllegalStateException {
 		verifyAddAndRemovePresent();
 		return new GenericListenerHandle<O, L>(observable, listener, add.get(), remove.get());
 	}

src/main/java/org/codefx/libfx/listener/handle/ListenerHandles.java

@@ -75,7 +75,7 @@ public static ListenerHandle createDetached(Observable observable, InvalidationL
 				.from(observable, invalidationListener)
 				.onAttach((obs, listener) -> obs.addListener(listener))
 				.onDetach((obs, listener) -> obs.removeListener(listener))
-				.build();
+				.buildDetached();
 	}
 
 	// ObservableValue + ChangeListener
@@ -117,7 +117,7 @@ public static <T> ListenerHandle createDetached(
 				.from(observableValue, changeListener)
 				.onAttach((observable, listener) -> observable.addListener(listener))
 				.onDetach((observable, listener) -> observable.removeListener(listener))
-				.build();
+				.buildDetached();
 	}
 
 	// ObservableArray + ArrayChangeListener
@@ -159,7 +159,7 @@ public static <T extends ObservableArray<T>> ListenerHandle createDetached(
 				.from(observableArray, changeListener)
 				.onAttach((observable, listener) -> observable.addListener(listener))
 				.onDetach((observable, listener) -> observable.removeListener(listener))
-				.build();
+				.buildDetached();
 	}
 
 	// ObservableList + ListChangeListener
@@ -201,7 +201,7 @@ public static <E> ListenerHandle createDetached(
 				.from(observableList, changeListener)
 				.onAttach((observable, listener) -> observable.addListener(listener))
 				.onDetach((observable, listener) -> observable.removeListener(listener))
-				.build();
+				.buildDetached();
 	}
 
 	// ObservableSet + SetChangeListener
@@ -243,7 +243,7 @@ public static <E> ListenerHandle createDetached(
 				.from(observableSet, changeListener)
 				.onAttach((observable, listener) -> observable.addListener(listener))
 				.onDetach((observable, listener) -> observable.removeListener(listener))
-				.build();
+				.buildDetached();
 	}
 
 	// ObservableMap + MapChangeListener
@@ -289,7 +289,7 @@ public static <K, V> ListenerHandle createDetached(
 				.from(observableMap, changeListener)
 				.onAttach((observable, listener) -> observable.addListener(listener))
 				.onDetach((observable, listener) -> observable.removeListener(listener))
-				.build();
+				.buildDetached();
 	}
 
 }

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

@@ -177,7 +177,7 @@ public NestedInvalidationListenerHandle addListener(InvalidationListener listene
 		return NestedInvalidationListenerBuilder
 				.forNesting(nesting)
 				.withListener(listener)
-				.build();
+				.buildAttached();
 	}
 
 	//#end LISTENERS

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

@@ -62,7 +62,7 @@ public NestedChangeListenerHandle<T> addListener(ChangeListener<? super T> liste
 		return NestedChangeListenerBuilder
 				.forNesting(nesting)
 				.withListener(listener)
-				.build();
+				.buildAttached();
 	}
 
 	//#end LISTENERS

src/main/java/org/codefx/libfx/nesting/listener/NestedChangeListenerBuilder.java

@@ -79,7 +79,7 @@ public static <T, O extends ObservableValue<T>> NestedChangeListenerBuilder<T, O
 	 *
 	 * @param listener
 	 *            the {@link ChangeListener} which will be added to the nesting's inner observable value
-	 * @return a {@link NestedChangeListenerBuilder} which provides a {@link Buildable#build() build}-method
+	 * @return a {@link NestedChangeListenerBuilder} which provides a {@link Buildable#buildAttached() build}-method
 	 */
 	public Buildable withListener(ChangeListener<? super T> listener) {
 		Objects.requireNonNull(listener, "The argument 'listener' must not be null.");
@@ -93,7 +93,8 @@ public Buildable withListener(ChangeListener<? super T> listener) {
 	// #region PRIVATE CLASSES
 
 	/**
-	 * A subtype of {@link NestedChangeListenerBuilder} which can actually build a listener with {@link #build()}.
+	 * A subtype of {@link NestedChangeListenerBuilder} which can actually build a listener with
+	 * {@link #buildAttached()}.
 	 */
 	public class Buildable extends NestedChangeListenerBuilder<T, O> {
 
@@ -119,10 +120,10 @@ private Buildable(NestedChangeListenerBuilder<T, O> builder) {
 		 * This method can only be called once as the same {@link ChangeListener} should not be added more than once to
 		 * the same {@link Nesting}.
 		 *
-		 * @return a new instance of {@link NestedChangeListenerHandle}
-		 * @see NestedChangeListenerHandle#attach()
+		 * @return a new instance of {@link NestedChangeListenerHandle}; initially attached
+		 * @see #buildDetached()
 		 */
-		public NestedChangeListenerHandle<T> build() {
+		public NestedChangeListenerHandle<T> buildAttached() {
 			NestedChangeListenerHandle<T> listenerHandle = buildDetached();
 			listenerHandle.attach();
 			return listenerHandle;
@@ -136,9 +137,8 @@ public NestedChangeListenerHandle<T> build() {
 		 * This method can only be called once as the same {@link ChangeListener} should not be added more than once to
 		 * the same {@link Nesting}.
 		 *
-		 * @return a new instance of {@link NestedChangeListenerHandle}
-		 * @see #build()
-		 * @see NestedChangeListenerHandle#attach()
+		 * @return a new instance of {@link NestedChangeListenerHandle}; initially detached
+		 * @see #buildAttached()
 		 */
 		public NestedChangeListenerHandle<T> buildDetached() {
 			if (built)

src/main/java/org/codefx/libfx/nesting/listener/NestedInvalidationListenerBuilder.java

@@ -71,7 +71,7 @@ public static NestedInvalidationListenerBuilder forNesting(Nesting<?> nesting) {
 	 *
 	 * @param listener
 	 *            the {@link InvalidationListener} which will be added to the nesting's inner observable
-	 * @return a {@link NestedInvalidationListenerBuilder} which provides a {@link Buildable#build() build}-method
+	 * @return a {@link NestedInvalidationListenerBuilder} which provides a {@link Buildable#buildAttached() build}-method
 	 */
 	public Buildable withListener(InvalidationListener listener) {
 		Objects.requireNonNull(listener, "The argument 'listener' must not be null.");
@@ -85,7 +85,7 @@ public Buildable withListener(InvalidationListener listener) {
 	// #region PRIVATE CLASSES
 
 	/**
-	 * A subtype of {@link NestedInvalidationListenerBuilder} which can actually build a listener with {@link #build()}.
+	 * A subtype of {@link NestedInvalidationListenerBuilder} which can actually build a listener with {@link #buildAttached()}.
 	 */
 	public class Buildable extends NestedInvalidationListenerBuilder {
 
@@ -111,10 +111,10 @@ private Buildable(NestedInvalidationListenerBuilder builder) {
 		 * This method can only be called once as the same {@link InvalidationListener} should not be added more than
 		 * once to the same {@link Nesting}.
 		 *
-		 * @return a new instance of {@link NestedInvalidationListenerHandle}
-		 * @see NestedInvalidationListenerHandle#attach()
+		 * @return a new instance of {@link NestedInvalidationListenerHandle}; initially attached
+		 * @see #buildDetached()
 		 */
-		public NestedInvalidationListenerHandle build() {
+		public NestedInvalidationListenerHandle buildAttached() {
 			NestedInvalidationListenerHandle listenerHandle = buildDetached();
 			listenerHandle.attach();
 			return listenerHandle;
@@ -128,9 +128,8 @@ public NestedInvalidationListenerHandle build() {
 		 * This method can only be called once as the same {@link InvalidationListener} should not be added more than
 		 * once to the same {@link Nesting}.
 		 *
-		 * @return a new instance of {@link NestedInvalidationListenerHandle}
-		 * @see #build()
-		 * @see NestedInvalidationListenerHandle#attach()
+		 * @return a new instance of {@link NestedInvalidationListenerHandle}; initially detached
+		 * @see #buildAttached()
 		 */
 		public NestedInvalidationListenerHandle buildDetached() {
 			if (built)