Differences

This shows you the differences between two versions of the page.

--- jvx:reference [2018/05/22 11:22]
robot
+++ jvx:reference [2020/06/10 12:20]
cduncan [Conclusion]
@@ Line 2: / Line 2: @@
 ~~Title: JVx Concepts and Reference~~
-Version: 1.0 / 2018-05-22
+Version: 1.0 / 2019-07-01
 ====== Introduction ======
-This collection of various tutorials is aimed to provide you with a broad overview over the concepts and mechanics of the [[https://sourceforge.net/projects/jvx/|JVx]] application framework.
+This collection of various tutorials is aimed at providing you with a broad overview over the concepts and mechanics of the [[https://sourceforge.net/projects/jvx/|JVx]] application framework.
 ====== Of Technologies and Factories ======
-Let’s talk about the UI layer, the implementations and the factory that powers it all.
+Let’s talk about the UI layer, the implementations, and the factory that powers it all.
-===== The basics =====
+===== The Basics =====
-For everyone who does not know, [[https://sourceforge.net/projects/jvx/|JVx]] allows you to write code once and run it on different GUI frameworks, without changing your code. This is achieved by hiding the concrete GUI implementations behind our own classes, the UI classes, and providing “bindings” for different GUI frameworks behind the scenes. Such a “[[https://en.wikipedia.org/wiki/Single_source_publishing|single sourcing]]” approach has many advantages, and just one of them is that migrating to a new GUI framework requires only the change of a single line, the one which controls which factory is used.
+For everyone who does not know, [[https://sourceforge.net/projects/jvx/|JVx]] allows you to write code once and run it on different GUI frameworks without changing your code. This is achieved by hiding the concrete GUI implementations behind our own classes, the UI classes, and providing “bindings” for different GUI frameworks behind the scenes. Such a “[[https://en.wikipedia.org/wiki/Single-source_publishing|single sourcing]]” approach has many advantages, one of which is that migrating to a new GUI framework requires only the change of a single line, the one which controls which factory is used.
-===== The patterns =====
+===== The Patterns =====
-[[https://en.wikipedia.org/wiki/Factory_%28object_oriented_programming%29|The factory pattern]] is an important pattern in [[https://en.wikipedia.org/wiki/Object_oriented_programming|Object-oriented programming]], it empowers us to delegate the creation of objects to another object which must not be known at design and/or compile time. That allows us to use objects which have not been created by us but merely “provided” to us by an, for us unknown, source.
+[[https://en.wikipedia.org/wiki/Factory_%28object-oriented_programming%29|The factory pattern]] is an important pattern in [[https://en.wikipedia.org/wiki/Object-oriented_programming|Object-oriented programming]] It empowers us to delegate the creation of objects to another object that is not known at design and/or compile time. That allows us to use objects which have not been created by us but merely “provided” to us by an unknown-to-us source.
-[[https://en.wikipedia.org/wiki/Bridge_pattern|The bridge pattern]] on the other hand describes a technique which wraps implementations in another implementation and forwards all/most functionality to that wrapped implementation. This allows us to mix and match functionality without the need to have it in all implementations at once.
+[[https://en.wikipedia.org/wiki/Bridge_pattern|The bridge pattern]], on the other hand, describes a technique which wraps implementations in another implementation and forwards all or most functionality to that wrapped implementation. This allows us to mix and match functionality without the need to have it in all implementations at once.
-===== Like an onion =====
+===== Like an Onion =====
-[[https://sourceforge.net/projects/jvx/|JVx]] is separated into different layers, with the UI layer being at the top and of the most concern to users.
+[[https://sourceforge.net/projects/jvx/|JVx]] is separated into different layers with the UI layer being at the top and of the most concern to users.
 {{:jvx:reference:layers.png?nolink|The four layers of VisionX: UI, Implementation, Extension and Technology.}}
@@ Line 30: / Line 30: @@
 ==== Technology ====
-Obviously, the first one in the chain is the so called “technology” layer. It represents the UI technology, for example Swing, JavaFX or Vaadin, which is used to power the [[https://sourceforge.net/projects/jvx/|JVx]] application.
+Obviously, the first one in the chain is the so-called “technology” layer. It represents the UI technology -- for example Swing, JavaFX or Vaadin -- that is used to power the [[https://sourceforge.net/projects/jvx/|JVx]] application.
-To put it into a more simple term:
+To put it more simply:
 <code java>
@@ Line 39: / Line 39: @@
 ==== Extension ====
-Next comes the extension layer, components from the technology are extended to support needed features of [[https://sourceforge.net/projects/jvx/|JVx]]. This includes creating bindings for the databook, additional style options and changing of behavior if necessary. From time to time this also includes creating components from scratch if the provided ones do not meet the needs or there simply are none with the required functionality. For the most part, we do our best that these layers can be used without [[https://sourceforge.net/projects/jvx/|JVx]], meaning that they represent a solitary extension to the technology. A very good example is our JavaFX implementation, which compiles into two separate jars, the first being the complete [[https://sourceforge.net/projects/jvxfx/|JVx/JavaFX]] stack, the second being stand-alone JavaFX extensions which can be used in any application and without [[https://sourceforge.net/projects/jvx/|JVx]].
+Next comes the extension layer. Components from the technology are extended to support needed features of [[https://sourceforge.net/projects/jvx/|JVx]]. This includes creating bindings for the databook, additional style options, and changing of behavior, if necessary. From time to time, this also includes creating components from scratch if the provided ones do not meet the needs or there simply are none with the required functionality. For the most part, we do our best that these layers can be used without [[https://sourceforge.net/projects/jvx/|JVx]], meaning that they represent a solitary extension to the technology. A very good example is our JavaFX implementation, which compiles into two separate jars, the first being the complete [[https://sourceforge.net/projects/jvxfx/|JVx/JavaFX]] stack, the second being stand-alone JavaFX extensions that can be used in any application and without [[https://sourceforge.net/projects/jvx/|JVx]].
-Theoretically one can skip this layer and directly jump to the Implementation layer, but so far it has proven necessary (for cleanliness of the code, object structure and sanity reasons) to create a separate extension layer.
+Theoretically, one can skip this layer and directly jump to the implementation layer, but, so far, it has proven necessary (for cleanliness of the code, object structure, and sanity reasons) to create a separate extension layer.
 <code java>
@@ Line 48: / Line 48: @@
 ==== Implementation ====
-After that comes the implementation layer. These implementations of the [[https://sourceforge.net/projects/jvx/|JVx]] interfaces are the actual objects returned by the factory. This is some sort of “glue” layer, it binds the technology or extended components against the interfaces which are provided by [[https://sourceforge.net/projects/jvx/|JVx]].
+After that comes the implementation layer. These implementations of the [[https://sourceforge.net/projects/jvx/|JVx]] interfaces are the actual objects returned by the factory. This is some sort of “glue” layer: it binds the technology or extended components against the interfaces which are provided by [[https://sourceforge.net/projects/jvx/|JVx]].
 <code java>
@@ Line 55: / Line 55: @@
 ==== UI ====
-Last but for sure not least is the UI layer, which wraps the implementations. It is completely Implementation independent, that means that one can swap out the stack underneath:
+Last, but definitely not least, is the UI layer, which wraps the implementations. It is completely implementation-independent, which means that one can swap out the stack underneath:
 {{:jvx:reference:swappable-layers.png?nolink|The Extension, Implementation and Technology can be swapped at will}}
-This is achieved because the UI layer is not extending the Implementation layer, but wrapping instances provided by the factory. It is oblivious to what Technology is actually underneath it.
+This is achieved because the UI layer is not extending the implementation layer but wrapping instances provided by the factory. It is oblivious to what technology is actually underneath it.
 <code java>
@@ Line 68: / Line 68: @@
 ===== Why is the UI layer necessary? =====
-It isn’t, not at all. The Implementations could be used directly without any problems, but having yet another layer has two key benefits:
+It isn’t, not at all. The implementations could be used directly without any problems, but having yet another layer has two key benefits:
   * It allows easier usage.
-  * It allows to add Technology independent features.
+  * It allows to add technology-independent features.
-By wrapping it one more time we gain a lot of freedom which we would not have otherwise, when it comes to features as when it comes to coding. The user does not need to call the factory directly and instead just needs to create a new object:
+By wrapping it one more time, we gain a lot of freedom which we would not have otherwise when it comes to features and coding. The user does not need to call the factory directly and, instead, just needs to create a new object:
 <code java>
 IButton button = new UIButton();
 </code>
-Internally, of course, the Factory is called and an implementation instance is created, but that is an implementation detail. If we would use the implementation layer directly, our code would either need to know about the implementations, which doesn’t follow the single-sourcing principle:
+Internally, of course, the factory is called and an implementation instance is created, but that is an implementation detail. If we would use the implementation layer directly, our code would need to know about the implementations, which doesn’t follow the single-sourcing principle:
 <code java>
@@ Line 88: / Line 88: @@
 IButton button = UIFactoryManager.getFactory().createButton();
 </code>
-Both can be avoided by using another layer which does the factory calls for us:
+Both can be avoided by using another layer that the factory calls for us:
 <code java>
@@ Line 106: / Line 106: @@
 }
 </code>
-Additionally this layer allows us to implement features which can be technology independent, our naming scheme, which we created during stress testing of an Vaadin application, is a very good example of that. The names of the components are derived in the UI layer without any knowledge of the underlying Technology or Implementation.
+Additionally, this layer allows us to implement features that can be technology-independent. Our naming scheme, which we created during stress testing of a Vaadin application, is a very good example of that. The names of the components are derived in the UI layer without any knowledge of the underlying technology or implementation.
-Also it does provide us (and everyone else of course) with a layer which allows to rapidly and easily build [[#compound_components|compound components]] out of already existing ones, like this:
+Also, it provides us (and everyone else, of course) with a layer which allows to rapidly and easily build [[#compound_components|compound components]] out of already existing ones, like this:
 <code java>
@@ Line 134: / Line 134: @@
 }
 </code>
-Of course that is not even close to sophisticated, or a good example for that matter. But it shows that one can build new components out of already existing ones without having to deal with the Technology or Implementation at all, creating truly cross-technology controls.
+Of course, that is not even close to sophisticated, or even a good example for that matter. However, it shows that one can build new components out of already existing ones without having to deal with the technology or implementation at all, creating truly cross-technology controls.
 ===== The Factory =====
-The heart piece of the UI layer is the Factory, which is creating the implemented classes. It’s a rather simple system, a singleton which is set to the Technology specific implementation and can be retrieved later:
+The heart piece of the UI layer is the factory that is creating the implemented classes. It’s a rather simple system, a singleton which is set to the Technology specific implementation and can be retrieved later:
 <code java>
@@ Line 166: / Line 166: @@
 It “just returns new objects” from the implementation layer. That’s about it when it comes to the factory, it is as simple as that.
-===== Piecing it together =====
+===== Piecing It Together =====
-With all this in mind, we know now that [[https://sourceforge.net/projects/jvx/|JVx]] has swappable implementations underneath its UI layer for each technology it utilizes:
+With all this in mind, we know now that [[https://sourceforge.net/projects/jvx/|JVx]] has swapable implementations underneath its UI layer for each technology it utilizes:
 {{:jvx:reference:multi-layers.png?nolink|Multiple Extensions/Implementations/Technologies can be used}}
-Changing between them can be as easy as setting a different factory. I say “can”, because that is only true for Swing, JavaFX and similar technologies, Vaadin, obviously, requires some more setup work. I mean, theoretically one could embed a complete application server and launch it when the factory for Vaadin is created, allowing the application to be basically stand-alone and be started as easily as a Swing application. That is possible.
+Changing between them can be as easy as setting a different factory. I say “can” because that is only true for Swing, JavaFX, and similar technologies. Vaadin, obviously, requires some more setup work. Theoretically, one could embed a complete application server and launch it when the factory for Vaadin is created, allowing the application to be basically stand-alone and be started as easily as a Swing application. That is possible.
 ===== What else? =====
-That is how [[https://sourceforge.net/projects/jvx/|JVx]] works in regards to the UI layer. It depends on “technology specific stacks” which can be swapped out and implemented for pretty much every GUI framework out there. We currently provide support for Swing, JavaFX and Vaadin, but we also had implementations for GWT and Qt. Additionally we do support a “headless” implementation which uses lightweight objects which can be serialized and send over the wire without much effort.
+That is how [[https://sourceforge.net/projects/jvx/|JVx]] works in regards to the UI layer. It depends on “technology specific stacks” which can be swapped out and implemented for pretty much every GUI framework out there. We currently provide support for Swing, JavaFX, and Vaadin, but we also had implementations for GWT and Qt. Additionally, we do support a “headless” implementation which uses lightweight objects which can be serialized and send over the wire without much effort.
-===== Adding a new Technology =====
+===== Adding a New Technology =====
-Adding support for a new Technology is as straightforward as one can imagine, simply creating the Extensions/Implementations layers and implementing the factory for that Technology. Giving a complete manual would be out for scope for this document, but the most simple approach to adding a new stack to [[https://sourceforge.net/projects/jvx/|JVx]] is to start with stubbing out the ''%%IFactory%%'' and implementing ''%%IWindow%%''. Once that one window shows up, it’s just implementing one interface after another in a quite straightforward manner. And in the end, your application can switch to yet another GUI framework without the need to change your code.
+Adding support for a new technology is as straightforward as one can imagine: simply creating the extensions/implementations layers and implementing the factory for that technology. Giving a complete manual would be out for scope for this document, but the most simple approach to adding a new stack to [[https://sourceforge.net/projects/jvx/|JVx]] is to start with stubbing out the ''%%IFactory%%'' and implementing ''%%IWindow%%''. Once that one window shows up, it’s just implementing one interface after another in a quite straightforward manner. In the end, your application can switch to yet another GUI framework without the need to change your code.
 ===== Conclusion =====
-Even though the stack of [[https://sourceforge.net/projects/jvx/|JVx]] is more complicated compared with other GUI or application frameworks, this complexity is set off by the benefits it brings. One can change the used GUI Technology without much effort and, most important of all, without touching the application logic at all.
+Even though the stack of [[https://sourceforge.net/projects/jvx/|JVx]] is more complicated compared with other GUI or application frameworks, this complexity is set off by the benefits it brings. One can change the used GUI technology without much effort and, most importantly, without touching the application logic at all.
 ====== Resource and UIResource ======
@@ Line 716: / Line 716: @@
   * Binary Data
-Text and Binary Data are both objects (arrays of primitives are Objects after all) and Numbers are either primitives or Objects. Most of the time if we deal with numbers inside a database we want them to be of arbitrary precision, which means we must represent them as ''%%BigDecimal%%''. Supporting ''%%double%%'' or ''%%float%%'' in these cases would be dangerously, because one might write a ''%%float%%'' into the database [[https://en.wikipedia.org/wiki/Floating_point_arithmetic|which might or might not end up with the correct value]] in the database. To completely eliminate such problems, we do only support Objects, which means that one is “limited” to the usage of Number extensions like ''%%BigLong%%'' and ''%%BigDecimal%%'', which do not suffer from such problems.
+Text and Binary Data are both objects (arrays of primitives are Objects after all) and Numbers are either primitives or Objects. Most of the time if we deal with numbers inside a database we want them to be of arbitrary precision, which means we must represent them as ''%%BigDecimal%%''. Supporting ''%%double%%'' or ''%%float%%'' in these cases would be dangerously, because one might write a ''%%float%%'' into the database [[https://en.wikipedia.org/wiki/Floating-point_arithmetic|which might or might not end up with the correct value]] in the database. To completely eliminate such problems, we do only support Objects, which means that one is “limited” to the usage of Number extensions like ''%%BigLong%%'' and ''%%BigDecimal%%'', which do not suffer from such problems.
 ==== Where are the DataPages? ====
@@ Line 800: / Line 800: @@
 But first, we will start without anything. The most simple application you can create with [[https://sourceforge.net/projects/jvx/|JVx]] is an application which does open a single window and only works with in memory data (if at all). This can be easily achieved by “just starting” the application.
-[[https://blog.sibvisions.com/2016/12/07/jvx_reference_of_technologies_and_factories/|The JVx GUI is a simple layer on top of the Technology]] which implements the actual functionality. So if we want to have a GUI we’ll need to initialize the factory before doing anything else:
+[[https://blog.sibvisions.com/2016/12/07/jvx-reference-of-technologies-and-factories/|The JVx GUI is a simple layer on top of the Technology]] which implements the actual functionality. So if we want to have a GUI we’ll need to initialize the factory before doing anything else:
 <code java>
@@ Line 827: / Line 827: @@
 Of course [[https://sourceforge.net/projects/jvx/|JVx]] wouldn’t be that useful if it would just provide static GUI components. Now, to explain what else is required for a remote [[https://sourceforge.net/projects/jvx/|JVx]] application I have to go far afield, so let’s head down the rabbit hole.
-{{:jvx:reference:jvx-client-server.png?nolink|JVx Layers}}
+{{:jvx:reference:jvx-client-server.png?nolink| Layers}}
 What you are seeing here is a rough sketch of how the architecture of [[https://sourceforge.net/projects/jvx/|JVx]] looks like. Let’s walk through the image step by step. We will look at each successive layer and work our way from the database on the server to the databook on the client.
@@ Line 982: / Line 982: @@
 ===== Interactive Demo =====
-[[https://blog.sibvisions.com/wp_content/uploads/2017/04/lifecycle_objects_demo.html|There is an interactive demo on our blog]] which allows you to explore the connections between the client and server side. The complement classes are always highlighted and you can click on the names of the objects to receive additional information about them.
+[[https://blog.sibvisions.com/wp-content/uploads/2017/04/lifecycle-objects-demo.html|There is an interactive demo on our blog]] which allows you to explore the connections between the client and server side. The complement classes are always highlighted and you can click on the names of the objects to receive additional information about them.
 ===== The JVx application: Manual example =====
@@ Line 1194: / Line 1194: @@
 If we take a good look at the CellEditorHandler interface, we see that it contains everything that is required for setting up a component to be able to edit data coming from a DataRow. One method is especially important, the ''%%getCellEditorComponent()%%'' function. It returns the actual technology component that is to be embedded into the Editor. That means that even though there are implementations for the CellEditors on the UI layer, the actual components which will provide the functionality for editing the data are implemented on the technology layer. A short refresher:
-{{:jvx:reference:layers.png?nolink|The different layers of JVx, User, UI Wrappers, Implementations, Extensions and the Technology.}}
+{{:jvx:reference:layers.png?nolink|The different layers of , User, UI Wrappers, Implementations, Extensions and the Technology.}}
 Revisiting our simple screen from above, we’d actually need to represent it as something like this:
@@ Line 1632: / Line 1632: @@
 ===== Interactive demo =====
-Sometimes, however, it might not be obvious what anchors are created and how they are used. For this we have created a simple interactive demonstration application which allows to inspect the created anchors of a layout, the [[https://github.com/sibvisions/jvx.formlayout_visualization|JVx FormLayout Visualization]].
+Sometimes, however, it might not be obvious what anchors are created and how they are used. For this we have created a simple interactive demonstration application which allows to inspect the created anchors of a layout, the [[https://github.com/sibvisions/jvx.formlayout-visualization|JVx FormLayout Visualization]].
 {{:jvx:reference:formlayout-visualization.png?nolink|FormLayout Visualization Demo}}
-On the left is the possibility to show and hide anchors together with the information about the currently highlighted anchor. On the right is a Lua scripting area which allows you to quickly and easily rebuild and test layouts. It utilizes the [[https://blog.sibvisions.com/2017/09/25/jvx_lua_proof_of_concept/|JVx-Lua bridge from a previous blog post]] and so any changes to the code are directly applied.
+On the left is the possibility to show and hide anchors together with the information about the currently highlighted anchor. On the right is a Lua scripting area which allows you to quickly and easily rebuild and test layouts. It utilizes the [[https://blog.sibvisions.com/2017/09/25/jvx-lua-proof-of-concept/|JVx-Lua bridge from a previous blog post]] and so any changes to the code are directly applied.
 ===== The most simple usage: Flow-like =====
@@ Line 1758: / Line 1758: @@
 ===== What are events… =====
-Events are an [[https://en.wikipedia.org/wiki/Event_driven_programming|important mechanism no matter to what programming language or framework you turn to]]. It allows us to react on certain actions and “defer” actions until something triggered them. Such triggers can be anything, like a certain condition is hit in another thread, the user clicked a button or another action has finally finished. Long story short, you get notified that something happened, and that you can now do something.
+Events are an [[https://en.wikipedia.org/wiki/Event-driven_programming|important mechanism no matter to what programming language or framework you turn to]]. It allows us to react on certain actions and “defer” actions until something triggered them. Such triggers can be anything, like a certain condition is hit in another thread, the user clicked a button or another action has finally finished. Long story short, you get notified that something happened, and that you can now do something.
 ===== …and why do I need to handle them? =====
@@ Line 1977: / Line 1977: @@
 Now every time the event is dispatched, the ''%%somethingOtherHappened%%'' method will be invoked. Anyway, don’t use this. The upside of having a “simple” listener interface with just one method is that it allows to use lambdas with it. A listener interface with multiple methods won’t allow this.
-In [[https://sourceforge.net/projects/jvx/|JVx]] [[http://blog.sibvisions.com/2015/01/28/jvx_and_java_8_events_and_lambdas/|we reduced our listener interfaces to just one method (in a backward compatible way)]] to make sure all events can be used with lambdas.
+In [[https://sourceforge.net/projects/jvx/|JVx]] [[http://blog.sibvisions.com/2015/01/28/jvx-and-java-8-events-and-lambdas/|we reduced our listener interfaces to just one method (in a backward compatible way)]] to make sure all events can be used with lambdas.
 ===== Fire away! =====