Skip to content

Commit fe8b286

Browse files
author
nicolaiparlog
committed
Unified names and comments for methods which return a handle with respect to whether the handle is initially attached or not.
1 parent 20e7963 commit fe8b286

16 files changed

+75
-73
lines changed

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ private void simpleCase() {
5555
ControlProperties.<String> on(properties)
5656
.forKey("Key")
5757
.processValue(value -> System.out.println(" -> " + value))
58-
.build();
58+
.buildAttached();
5959

6060
// set values of the correct type for the correct key
6161
System.out.print("Set \"Value\" for the correct key for the first time: ");
@@ -119,7 +119,7 @@ private void timeNoTypeCheck() {
119119
ControlProperties.<String> on(properties)
120120
.forKey("Key")
121121
.processValue(unreached)
122-
.build();
122+
.buildAttached();
123123

124124
// add a couple of values of the wrong type to average the time that takes
125125
Integer valueOfWrongType = 5;
@@ -151,7 +151,7 @@ ControlProperties.<String> on(properties)
151151
.forKey("Key")
152152
.forValueType(String.class)
153153
.processValue(unreached)
154-
.build();
154+
.buildAttached();
155155

156156
// add a couple of values of the wrong type to average the time that takes
157157
Integer valueOfWrongType = 5;

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,12 +69,11 @@ private void createCustomListenerHandle() {
6969

7070
// use 'ListenerHandles' to get a 'ListenerHandleBuilder' which can be used to create a handle for this
7171
// observable and listener
72-
ListenerHandle handleForCustomClasses = ListenerHandles
72+
ListenerHandles
7373
.createFor(customObservable, customListener)
7474
.onAttach((observable, listener) -> observable.addListener(listener))
7575
.onDetach((observable, listener) -> observable.removeListener(listener))
76-
.build();
77-
handleForCustomClasses.attach();
76+
.buildAttached();
7877
}
7978

8079
// attach & detach

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

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
* case occurs frequently, specifying the type to allow the check will improve performance considerably.
2121
* <p>
2222
* A typical use looks like this:
23-
*
23+
*
2424
* <pre>
2525
* ControlProperties.<Boolean> on(control.getProperties())
2626
* .forKey("visible")
@@ -120,7 +120,7 @@ public ControlPropertyListenerBuilder<T> forValueType(Class<T> valueType) {
120120
}
121121

122122
/**
123-
* Sets the processor for the key's values. This must be called before {@link #build()}.
123+
* Sets the processor for the key's values. This must be called before {@link #buildAttached()}.
124124
*
125125
* @param valueProcessor
126126
* the {@link Consumer} for the key's values
@@ -140,10 +140,10 @@ public ControlPropertyListenerBuilder<T> processValue(Consumer<? super T> valueP
140140
* Creates a new property listener according to the arguments specified before and
141141
* {@link ControlPropertyListenerHandle#attach() attaches} it.
142142
*
143-
* @return a {@link ControlPropertyListenerHandle}
144-
* @see ControlPropertyListenerHandle#attach()
143+
* @return a {@link ControlPropertyListenerHandle}; initially attached
144+
* @see #buildDetached()
145145
*/
146-
public ControlPropertyListenerHandle build() {
146+
public ControlPropertyListenerHandle buildAttached() {
147147
ControlPropertyListenerHandle listener = buildDetached();
148148
listener.attach();
149149
return listener;
@@ -155,9 +155,8 @@ public ControlPropertyListenerHandle build() {
155155
* Note that this builder is not yet attached to the map! This can be done by calling
156156
* {@link ControlPropertyListenerHandle#attach() attach()} on the returned instance.
157157
*
158-
* @return a {@link ControlPropertyListenerHandle}
159-
* @see #build()
160-
* @see ControlPropertyListenerHandle#attach()
158+
* @return a {@link ControlPropertyListenerHandle}; initially detached
159+
* @see #buildAttached()
161160
*/
162161
public ControlPropertyListenerHandle buildDetached() {
163162
checkFields();

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

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -41,9 +41,8 @@ private WebViews() {
4141
* the {@link WebView} to which the listener will be added
4242
* @param listener
4343
* the {@link WebViewHyperlinkListener} to add to the web view
44-
* @return a handle on the created listener which allows to attach and detach it
44+
* @return a handle on the created listener which allows to attach and detach it; initially detached
4545
* @see WebViews#addHyperlinkListener(WebView, WebViewHyperlinkListener)
46-
* @see WebViewHyperlinkListenerHandle#attach()
4746
*/
4847
public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
4948
WebView webView, WebViewHyperlinkListener listener) {
@@ -65,18 +64,14 @@ public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
6564
* the {@link WebViewHyperlinkListener} to add to the web view
6665
* @param eventType
6766
* the {@link EventType} of all events passed to the listener
68-
* @return a handle on the created listener which allows to attach and detach it
67+
* @return a handle on the created listener which allows to attach and detach it; initially detached
6968
* @see WebViews#addHyperlinkListener(WebView, WebViewHyperlinkListener, EventType)
70-
* @see WebViewHyperlinkListenerHandle#attach()
7169
*/
7270
public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
7371
WebView webView, WebViewHyperlinkListener listener, EventType eventType) {
7472

7573
Objects.requireNonNull(eventType, "The argument 'eventType' must not be null.");
76-
WebViewHyperlinkListenerHandle listenerHandle =
77-
addHyperlinkListenerDetached(webView, listener, Optional.of(eventType));
78-
listenerHandle.attach();
79-
return listenerHandle;
74+
return addHyperlinkListenerDetached(webView, listener, Optional.of(eventType));
8075
}
8176

8277
// create and attach listener handles
@@ -89,9 +84,8 @@ public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
8984
* the {@link WebView} to which the listener will be added
9085
* @param listener
9186
* the {@link WebViewHyperlinkListener} to add to the web view
92-
* @return a handle on the created listener which allows to attach and detach it
87+
* @return a handle on the created listener which allows to attach and detach it; initially attached
9388
* @see #createHyperlinkListenerHandle(WebView, WebViewHyperlinkListener)
94-
* @see WebViewHyperlinkListenerHandle#attach()
9589
*/
9690
public static WebViewHyperlinkListenerHandle addHyperlinkListener(
9791
WebView webView, WebViewHyperlinkListener listener) {
@@ -112,9 +106,8 @@ public static WebViewHyperlinkListenerHandle addHyperlinkListener(
112106
* the {@link WebViewHyperlinkListener} to add to the web view
113107
* @param eventType
114108
* the {@link EventType} of all events passed to the listener
115-
* @return a handle on the created listener which allows to attach and detach it
109+
* @return a handle on the created listener which allows to attach and detach it; initially attached
116110
* @see #createHyperlinkListenerHandle(WebView, WebViewHyperlinkListener, EventType)
117-
* @see WebViewHyperlinkListenerHandle#attach()
118111
*/
119112
public static WebViewHyperlinkListenerHandle addHyperlinkListener(
120113
WebView webView, WebViewHyperlinkListener listener, EventType eventType) {

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

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -147,14 +147,28 @@ public ListenerHandleBuilder<O, L> onDetach(BiConsumer<? super O, ? super L> rem
147147
}
148148

149149
/**
150-
* Creates a new listener handle. This will only succeed if {@link #onAttach(BiConsumer)} and
150+
* Creates a new listener handle and attaches the listener. This will only succeed if {@link #onAttach(BiConsumer)}
151+
* and {@link #onDetach(BiConsumer)} have been called.
152+
*
153+
* @return a new {@link ListenerHandle}; initially attached
154+
* @throws IllegalStateException
155+
* if {@link #onAttach(BiConsumer)} or {@link #onDetach(BiConsumer)} have not been called
156+
*/
157+
public ListenerHandle buildAttached() throws IllegalStateException {
158+
ListenerHandle handle = buildDetached();
159+
handle.attach();
160+
return handle;
161+
}
162+
163+
/**
164+
* Creates a new, initially detached listener handle. This will only succeed if {@link #onAttach(BiConsumer)} and
151165
* {@link #onDetach(BiConsumer)} have been called.
152166
*
153167
* @return a new {@link ListenerHandle}; initially detached
154168
* @throws IllegalStateException
155169
* if {@link #onAttach(BiConsumer)} or {@link #onDetach(BiConsumer)} have not been called
156170
*/
157-
public ListenerHandle build() throws IllegalStateException {
171+
public ListenerHandle buildDetached() throws IllegalStateException {
158172
verifyAddAndRemovePresent();
159173
return new GenericListenerHandle<O, L>(observable, listener, add.get(), remove.get());
160174
}

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ public static ListenerHandle createDetached(Observable observable, InvalidationL
7575
.from(observable, invalidationListener)
7676
.onAttach((obs, listener) -> obs.addListener(listener))
7777
.onDetach((obs, listener) -> obs.removeListener(listener))
78-
.build();
78+
.buildDetached();
7979
}
8080

8181
// ObservableValue + ChangeListener
@@ -117,7 +117,7 @@ public static <T> ListenerHandle createDetached(
117117
.from(observableValue, changeListener)
118118
.onAttach((observable, listener) -> observable.addListener(listener))
119119
.onDetach((observable, listener) -> observable.removeListener(listener))
120-
.build();
120+
.buildDetached();
121121
}
122122

123123
// ObservableArray + ArrayChangeListener
@@ -159,7 +159,7 @@ public static <T extends ObservableArray<T>> ListenerHandle createDetached(
159159
.from(observableArray, changeListener)
160160
.onAttach((observable, listener) -> observable.addListener(listener))
161161
.onDetach((observable, listener) -> observable.removeListener(listener))
162-
.build();
162+
.buildDetached();
163163
}
164164

165165
// ObservableList + ListChangeListener
@@ -201,7 +201,7 @@ public static <E> ListenerHandle createDetached(
201201
.from(observableList, changeListener)
202202
.onAttach((observable, listener) -> observable.addListener(listener))
203203
.onDetach((observable, listener) -> observable.removeListener(listener))
204-
.build();
204+
.buildDetached();
205205
}
206206

207207
// ObservableSet + SetChangeListener
@@ -243,7 +243,7 @@ public static <E> ListenerHandle createDetached(
243243
.from(observableSet, changeListener)
244244
.onAttach((observable, listener) -> observable.addListener(listener))
245245
.onDetach((observable, listener) -> observable.removeListener(listener))
246-
.build();
246+
.buildDetached();
247247
}
248248

249249
// ObservableMap + MapChangeListener
@@ -289,7 +289,7 @@ public static <K, V> ListenerHandle createDetached(
289289
.from(observableMap, changeListener)
290290
.onAttach((observable, listener) -> observable.addListener(listener))
291291
.onDetach((observable, listener) -> observable.removeListener(listener))
292-
.build();
292+
.buildDetached();
293293
}
294294

295295
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ public NestedInvalidationListenerHandle addListener(InvalidationListener listene
177177
return NestedInvalidationListenerBuilder
178178
.forNesting(nesting)
179179
.withListener(listener)
180-
.build();
180+
.buildAttached();
181181
}
182182

183183
//#end LISTENERS

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ public NestedChangeListenerHandle<T> addListener(ChangeListener<? super T> liste
6262
return NestedChangeListenerBuilder
6363
.forNesting(nesting)
6464
.withListener(listener)
65-
.build();
65+
.buildAttached();
6666
}
6767

6868
//#end LISTENERS

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ public static <T, O extends ObservableValue<T>> NestedChangeListenerBuilder<T, O
7979
*
8080
* @param listener
8181
* the {@link ChangeListener} which will be added to the nesting's inner observable value
82-
* @return a {@link NestedChangeListenerBuilder} which provides a {@link Buildable#build() build}-method
82+
* @return a {@link NestedChangeListenerBuilder} which provides a {@link Buildable#buildAttached() build}-method
8383
*/
8484
public Buildable withListener(ChangeListener<? super T> listener) {
8585
Objects.requireNonNull(listener, "The argument 'listener' must not be null.");
@@ -93,7 +93,8 @@ public Buildable withListener(ChangeListener<? super T> listener) {
9393
// #region PRIVATE CLASSES
9494

9595
/**
96-
* A subtype of {@link NestedChangeListenerBuilder} which can actually build a listener with {@link #build()}.
96+
* A subtype of {@link NestedChangeListenerBuilder} which can actually build a listener with
97+
* {@link #buildAttached()}.
9798
*/
9899
public class Buildable extends NestedChangeListenerBuilder<T, O> {
99100

@@ -119,10 +120,10 @@ private Buildable(NestedChangeListenerBuilder<T, O> builder) {
119120
* This method can only be called once as the same {@link ChangeListener} should not be added more than once to
120121
* the same {@link Nesting}.
121122
*
122-
* @return a new instance of {@link NestedChangeListenerHandle}
123-
* @see NestedChangeListenerHandle#attach()
123+
* @return a new instance of {@link NestedChangeListenerHandle}; initially attached
124+
* @see #buildDetached()
124125
*/
125-
public NestedChangeListenerHandle<T> build() {
126+
public NestedChangeListenerHandle<T> buildAttached() {
126127
NestedChangeListenerHandle<T> listenerHandle = buildDetached();
127128
listenerHandle.attach();
128129
return listenerHandle;
@@ -136,9 +137,8 @@ public NestedChangeListenerHandle<T> build() {
136137
* This method can only be called once as the same {@link ChangeListener} should not be added more than once to
137138
* the same {@link Nesting}.
138139
*
139-
* @return a new instance of {@link NestedChangeListenerHandle}
140-
* @see #build()
141-
* @see NestedChangeListenerHandle#attach()
140+
* @return a new instance of {@link NestedChangeListenerHandle}; initially detached
141+
* @see #buildAttached()
142142
*/
143143
public NestedChangeListenerHandle<T> buildDetached() {
144144
if (built)

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

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ public static NestedInvalidationListenerBuilder forNesting(Nesting<?> nesting) {
7171
*
7272
* @param listener
7373
* the {@link InvalidationListener} which will be added to the nesting's inner observable
74-
* @return a {@link NestedInvalidationListenerBuilder} which provides a {@link Buildable#build() build}-method
74+
* @return a {@link NestedInvalidationListenerBuilder} which provides a {@link Buildable#buildAttached() build}-method
7575
*/
7676
public Buildable withListener(InvalidationListener listener) {
7777
Objects.requireNonNull(listener, "The argument 'listener' must not be null.");
@@ -85,7 +85,7 @@ public Buildable withListener(InvalidationListener listener) {
8585
// #region PRIVATE CLASSES
8686

8787
/**
88-
* A subtype of {@link NestedInvalidationListenerBuilder} which can actually build a listener with {@link #build()}.
88+
* A subtype of {@link NestedInvalidationListenerBuilder} which can actually build a listener with {@link #buildAttached()}.
8989
*/
9090
public class Buildable extends NestedInvalidationListenerBuilder {
9191

@@ -111,10 +111,10 @@ private Buildable(NestedInvalidationListenerBuilder builder) {
111111
* This method can only be called once as the same {@link InvalidationListener} should not be added more than
112112
* once to the same {@link Nesting}.
113113
*
114-
* @return a new instance of {@link NestedInvalidationListenerHandle}
115-
* @see NestedInvalidationListenerHandle#attach()
114+
* @return a new instance of {@link NestedInvalidationListenerHandle}; initially attached
115+
* @see #buildDetached()
116116
*/
117-
public NestedInvalidationListenerHandle build() {
117+
public NestedInvalidationListenerHandle buildAttached() {
118118
NestedInvalidationListenerHandle listenerHandle = buildDetached();
119119
listenerHandle.attach();
120120
return listenerHandle;
@@ -128,9 +128,8 @@ public NestedInvalidationListenerHandle build() {
128128
* This method can only be called once as the same {@link InvalidationListener} should not be added more than
129129
* once to the same {@link Nesting}.
130130
*
131-
* @return a new instance of {@link NestedInvalidationListenerHandle}
132-
* @see #build()
133-
* @see NestedInvalidationListenerHandle#attach()
131+
* @return a new instance of {@link NestedInvalidationListenerHandle}; initially detached
132+
* @see #buildAttached()
134133
*/
135134
public NestedInvalidationListenerHandle buildDetached() {
136135
if (built)

0 commit comments

Comments
 (0)