Restructured 'org.codefx.libfx.dom':

* the package converts events instead of transforming them (pure naming)
* prefixed some classes with 'Dom' to clarifiy what they are converting
* replaced the former interface 'EventTransformer' with its only implementation

Author: nicolaiparlog

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

@@ -15,8 +15,8 @@
 
 import org.codefx.libfx.concurrent.when.ExecuteAlwaysWhen;
 import org.codefx.libfx.concurrent.when.ExecuteWhen;
+import org.codefx.libfx.dom.DomEventConverter;
 import org.codefx.libfx.dom.DomEventType;
-import org.codefx.libfx.dom.EventTransformer;
 import org.w3c.dom.NodeList;
 import org.w3c.dom.events.Event;
 import org.w3c.dom.events.EventListener;
@@ -61,9 +61,9 @@ class DefaultWebViewHyperlinkListenerHandle implements WebViewHyperlinkListenerH
 	private final EventListener domEventListener;
 
 	/**
-	 * Transforms DOM {@link Event}s to {@link HyperlinkEvent}s.
+	 * Converts the observed DOM {@link Event}s to {@link HyperlinkEvent}s.
 	 */
-	private final EventTransformer eventTransformer;
+	private final DomEventConverter eventConverter;
 
 	/**
 	 * Executes {@link #attachListenerInApplicationThread()} each time the web view's load worker changes its state to
@@ -89,17 +89,17 @@ class DefaultWebViewHyperlinkListenerHandle implements WebViewHyperlinkListenerH
 	 *            the {@link WebViewHyperlinkListener} which will be attached to the {@code webView}
 	 * @param eventTypeFilter
 	 *            the filter for events by their {@link EventType}
-	 * @param eventTransformer
-	 *            the transformer for DOM {@link Event}s
+	 * @param eventConverter
+	 *            the converter for DOM {@link Event}s
 	 */
 	public DefaultWebViewHyperlinkListenerHandle(
 			WebView webView, WebViewHyperlinkListener eventListener, Optional<EventType> eventTypeFilter,
-			EventTransformer eventTransformer) {
+			DomEventConverter eventConverter) {
 
 		this.webView = webView;
 		this.eventListener = eventListener;
 		this.eventTypeFilter = eventTypeFilter;
-		this.eventTransformer = eventTransformer;
+		this.eventConverter = eventConverter;
 
 		domEventListener = this::callHyperlinkListenerWithEvent;
 	}
@@ -248,18 +248,18 @@ private boolean manageListenerForEventType(DomEventType domEventType) {
 	// #region PROCESS EVENT
 
 	/**
-	 * Transforms the specified {@code domEvent} into a {@link HyperlinkEvent} and calls the {@link #eventListener} with
+	 * Converts the specified {@code domEvent} into a {@link HyperlinkEvent} and calls the {@link #eventListener} with
 	 * it.
 	 *
 	 * @param domEvent
 	 *            the DOM-{@link Event}
 	 */
 	private void callHyperlinkListenerWithEvent(Event domEvent) {
-		boolean canNotTransformEvent = !eventTransformer.canTransformToHyperlinkEvent(domEvent);
-		if (canNotTransformEvent)
+		boolean canNotConvertEvent = !eventConverter.canConvertToHyperlinkEvent(domEvent);
+		if (canNotConvertEvent)
 			return;
 
-		HyperlinkEvent event = eventTransformer.transformToHyperlinkEvent(domEvent, webView);
+		HyperlinkEvent event = eventConverter.convertToHyperlinkEvent(domEvent, webView);
 		boolean cancel = eventListener.hyperlinkUpdate(event);
 		cancel(domEvent, cancel);
 	}

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

@@ -8,9 +8,9 @@
 import javax.swing.event.HyperlinkEvent;
 import javax.swing.event.HyperlinkEvent.EventType;
 
-import org.codefx.libfx.dom.DefaultEventTransformer;
+import org.codefx.libfx.dom.DomEventConverter;
 import org.codefx.libfx.dom.DomEventType;
-import org.codefx.libfx.dom.StaticEventTransformer;
+import org.codefx.libfx.dom.StaticDomEventConverter;
 import org.w3c.dom.events.Event;
 
 /**
@@ -57,7 +57,7 @@ public static WebViewHyperlinkListenerHandle createHyperlinkListenerHandle(
 	 * <p>
 	 * Once attached, the listener will be called on any event on an hyperlink (i.e. any element with tag name "a")
 	 * which can be represented as a {@link HyperlinkEvent} with the specified event type. See
-	 * {@link DomEventType#toHyperlinkEventType()} for the transformation of event types.
+	 * {@link DomEventType#toHyperlinkEventType()} for the conversion of event types.
 	 *
 	 * @param webView
 	 *            the {@link WebView} to which the listener will be added
@@ -148,40 +148,40 @@ private static WebViewHyperlinkListenerHandle addHyperlinkListenerDetached(
 		Objects.requireNonNull(eventTypeFilter, "The argument 'eventTypeFilter' must not be null.");
 
 		return new DefaultWebViewHyperlinkListenerHandle(
-				webView, listener, eventTypeFilter, new DefaultEventTransformer());
+				webView, listener, eventTypeFilter, new DomEventConverter());
 	}
 
 	// #end HYPERLINK LISTENERS
 
 	// #region EVENTS
 
 	/**
-	 * Indicates whether the specified DOM event can be transformed to a {@link HyperlinkEvent}.
+	 * Indicates whether the specified DOM event can be converted to a {@link HyperlinkEvent}.
 	 *
 	 * @param domEvent
 	 *            the DOM-{@link Event}
 	 * @return true if the event's {@link Event#getType() type} has an equivalent {@link EventType EventType}
 	 */
-	public static boolean canTransformToHyperlinkEvent(Event domEvent) {
-		return StaticEventTransformer.canTransformToHyperlinkEvent(domEvent);
+	public static boolean canConvertToHyperlinkEvent(Event domEvent) {
+		return StaticDomEventConverter.canConvertToHyperlinkEvent(domEvent);
 	}
 
 	/**
-	 * Transforms the specified DOM event to a hyperlink event.
+	 * Converts the specified DOM event to a hyperlink event.
 	 *
 	 * @param domEvent
 	 *            the DOM-{@link Event} from which the {@link HyperlinkEvent} will be created
 	 * @param source
 	 *            the source of the {@code domEvent}
 	 * @return a {@link HyperlinkEvent}
 	 * @throws IllegalArgumentException
-	 *             if the specified event can not be transformed to a hyperlink event; this is the case if
-	 *             {@link #canTransformToHyperlinkEvent(Event)} returns false
+	 *             if the specified event can not be converted to a hyperlink event; this is the case if
+	 *             {@link #canConvertToHyperlinkEvent(Event)} returns false
 	 */
-	public static HyperlinkEvent transformToHyperlinkEvent(Event domEvent, Object source)
+	public static HyperlinkEvent convertToHyperlinkEvent(Event domEvent, Object source)
 			throws IllegalArgumentException {
 
-		return StaticEventTransformer.transformToHyperlinkEvent(domEvent, source);
+		return StaticDomEventConverter.convertToHyperlinkEvent(domEvent, source);
 	}
 
 	/**

src/main/java/org/codefx/libfx/dom/DefaultEventTransformer.java

@@ -1,26 +1,38 @@
 package org.codefx.libfx.dom;
 
+import java.util.Objects;
+
 import javax.swing.event.HyperlinkEvent;
 import javax.swing.event.HyperlinkEvent.EventType;
 
 import org.w3c.dom.events.Event;
 
 /**
- * Transforms {@link Event DOM Events} to Swing's {@link HyperlinkEvent HyperlinkEvents}.
+ * Converts {@link Event DOM Events} to Swing's {@link HyperlinkEvent HyperlinkEvents}.
+ * <p>
+ * This class is thread-safe, i.e. the provided methods can be called from different threads and concurrent executions
+ * do not interfere with each other.
  */
-public interface EventTransformer {
+public final class DomEventConverter {
 
 	/**
-	 * Indicates whether the specified DOM event can be transformed to a {@link HyperlinkEvent}.
+	 * Indicates whether the specified DOM event can be converted to a {@link HyperlinkEvent}.
 	 *
 	 * @param domEvent
 	 *            the DOM-{@link Event}
 	 * @return true if the event's {@link Event#getType() type} has an equivalent {@link EventType EventType}
 	 */
-	boolean canTransformToHyperlinkEvent(Event domEvent);
+	@SuppressWarnings("static-method")
+	public boolean canConvertToHyperlinkEvent(Event domEvent) {
+		Objects.requireNonNull(domEvent, "The argument 'domEvent' must not be null.");
+
+		Object source = "the source does not matter for this call";
+		SingleDomEventConverter converter = new SingleDomEventConverter(domEvent, source);
+		return converter.canConvert();
+	}
 
 	/**
-	 * Transforms the specified DOM event to a hyperlink event.
+	 * Converts the specified DOM event to a hyperlink event.
 	 *
 	 * @param domEvent
 	 *            the DOM-{@link Event} from which the {@link HyperlinkEvent} will be created
@@ -39,9 +51,13 @@ public interface EventTransformer {
 	 *         <li> {@link HyperlinkEvent#getSourceElement() getSourceElement()} returns null
 	 *         </ul>
 	 * @throws IllegalArgumentException
-	 *             if the specified event can not be transformed to a hyperlink event; this is the case if
-	 *             {@link #canTransformToHyperlinkEvent(Event)} returns false
+	 *             if the specified event can not be converted to a hyperlink event; this is the case if
+	 *             {@link #canConvertToHyperlinkEvent(Event)} returns false
 	 */
-	HyperlinkEvent transformToHyperlinkEvent(Event domEvent, Object source) throws IllegalArgumentException;
+	@SuppressWarnings("static-method")
+	public HyperlinkEvent convertToHyperlinkEvent(Event domEvent, Object source) throws IllegalArgumentException {
+		SingleDomEventConverter converter = new SingleDomEventConverter(domEvent, source);
+		return converter.convert();
+	}
 
 }

src/main/java/org/codefx/libfx/dom/EventTransformer.java renamed to src/main/java/org/codefx/libfx/dom/DomEventConverter.java

@@ -6,8 +6,7 @@
 import javax.swing.event.HyperlinkEvent.EventType;
 
 /**
- * The types of DOM events names. Actually, this is only a selection of those needed to determine a hyperlink
- * {@link EventType EventType}s.
+ * The names of those types of DOM events for which an equivalent hyperlink {@link EventType EventType}s exists.
  * <p>
  *
  * @see <a href="http://www.w3.org/TR/DOM-Level-3-Events/#event-types-list">DOM Level 3 Events Specification - Event
@@ -83,7 +82,7 @@ public String getDomName() {
 
 	/**
 	 * Returns the DOM event type for the specified event name.
-	 * 
+	 *
 	 * @param domEventName
 	 *            the name of the DOM event as per W3C specification
 	 * @return a {@link DomEventType} if it could be determined; otherwise {@link Optional#empty()}

src/main/java/org/codefx/libfx/dom/DomEventType.java

@@ -15,10 +15,10 @@
 /**
  * Creates a {@link HyperlinkEvent} from the DOM-{@link Event} specified during construction.
  * <p>
- * In that sense it acts like an {@link EventTransformer} but because the {@link #domEvent} and its {@link #source} have
- * to be provided during construction it can not actually implement that interface.
+ * In does the actual work for the {@link DomEventConverter} but is a "one-shot" version in the sense that it can only
+ * convert the event specified during construction.
  */
-class DomEventToHyperlinkEventTransformer {
+class SingleDomEventConverter {
 
 	/**
 	 * The DOM-{@link Event} from which the {@link HyperlinkEvent} will be created.
@@ -31,29 +31,29 @@ class DomEventToHyperlinkEventTransformer {
 	private final Object source;
 
 	/**
-	 * Creates a new transformer for the specified arguments.
+	 * Creates a new converter for the specified arguments.
 	 *
 	 * @param domEvent
 	 *            the DOM-{@link Event} from which the {@link HyperlinkEvent} will be created
 	 * @param source
 	 *            the source of the {@code domEvent}
 	 */
-	public DomEventToHyperlinkEventTransformer(Event domEvent, Object source) {
+	public SingleDomEventConverter(Event domEvent, Object source) {
 		Objects.requireNonNull(domEvent, "The argument 'domEvent' must not be null.");
 		Objects.requireNonNull(source, "The argument 'source' must not be null.");
 
 		this.domEvent = domEvent;
 		this.source = source;
 	}
 
-	// #region TRANSFORM
+	// #region CONVERT
 
 	/**
-	 * Indicates whether the DOM event specified during construction can be transformed to a {@link HyperlinkEvent}.
+	 * Indicates whether the DOM event specified during construction can be converted to a {@link HyperlinkEvent}.
 	 *
 	 * @return true if the event's {@link Event#getType() type} has an equivalent {@link EventType EventType}
 	 */
-	public boolean canTransform() {
+	public boolean canConvert() {
 		Optional<EventType> eventType = getEventTypeFrom(domEvent);
 		return eventType.isPresent();
 	}
@@ -74,14 +74,14 @@ private static Optional<EventType> getEventTypeFrom(Event domEvent) {
 	}
 
 	/**
-	 * Transforms the event specified during construction to a hyperlink event.
+	 * Converts the event specified during construction to a hyperlink event.
 	 *
 	 * @return a {@link HyperlinkEvent}
 	 * @throws IllegalArgumentException
-	 *             if the specified event can not be transformed to a hyperlink event; this is the case if
-	 *             {@link #canTransform()} returns false
+	 *             if the specified event can not be converted to a hyperlink event; this is the case if
+	 *             {@link #canConvert()} returns false
 	 */
-	public HyperlinkEvent transform() throws IllegalArgumentException {
+	public HyperlinkEvent convert() throws IllegalArgumentException {
 		EventType type = getEventTypeForDomEvent();
 		Optional<URL> url = getURL();
 		String linkDescription = getTextContent();
@@ -103,7 +103,7 @@ private EventType getEventTypeForDomEvent() throws IllegalArgumentException {
 		else
 			throw new IllegalArgumentException(
 					"The DOM event '" + domEvent + "' of type '" + domEvent.getType()
-							+ "' can not be transformed to a hyperlink event.");
+							+ "' can not be converted to a hyperlink event.");
 	}
 
 	/**
@@ -208,6 +208,6 @@ private static Optional<URL> createURL(Optional<String> baseURI, String href) {
 		return Optional.empty();
 	}
 
-	// #end TRANSFORM
+	// #end CONVERT
 
 }

src/main/java/org/codefx/libfx/dom/DomEventToHyperlinkEventTransformer.java renamed to src/main/java/org/codefx/libfx/dom/SingleDomEventConverter.java

@@ -0,0 +1,40 @@
+package org.codefx.libfx.dom;
+
+import java.util.Objects;
+
+import javax.swing.event.HyperlinkEvent;
+
+import org.w3c.dom.events.Event;
+
+/**
+ * Class which provides {@link DomEventConverter} methods statically.
+ * <p>
+ * This class is thread-safe, i.e. the provided methods can be called from different threads and concurrent executions
+ * do not interfere with each other.
+ */
+public final class StaticDomEventConverter {
+
+	/**
+	 * @see DomEventConverter#canConvertToHyperlinkEvent(Event)
+	 */
+	@SuppressWarnings("javadoc")
+	public static boolean canConvertToHyperlinkEvent(Event domEvent) {
+		Objects.requireNonNull(domEvent, "The argument 'domEvent' must not be null.");
+
+		Object source = "the source does not matter for this call";
+		SingleDomEventConverter converter = new SingleDomEventConverter(domEvent, source);
+		return converter.canConvert();
+	}
+
+	/**
+	 * @see DomEventConverter#convertToHyperlinkEvent(Event, Object)
+	 */
+	@SuppressWarnings("javadoc")
+	public static HyperlinkEvent convertToHyperlinkEvent(Event domEvent, Object source)
+			throws IllegalArgumentException {
+
+		SingleDomEventConverter converter = new SingleDomEventConverter(domEvent, source);
+		return converter.convert();
+	}
+
+}