Trace:
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
jvx:reference [2020/06/10 13:09] cduncan [The application] |
jvx:reference [2020/06/15 08:27] cduncan [The simplest JVx application: Just the GUI] |
||
|---|---|---|---|
| Line 335: | Line 335: | ||
| Which is easy enough, but let’s say we’d like to add logic to that wrapper. At that point, it becomes more complicated. We can’t use the same technique as the custom component from above because, in that case, the “overlaying panel” would simply not be displayed. However, there is a similar mechanism for containers: setting the UI resource container. | Which is easy enough, but let’s say we’d like to add logic to that wrapper. At that point, it becomes more complicated. We can’t use the same technique as the custom component from above because, in that case, the “overlaying panel” would simply not be displayed. However, there is a similar mechanism for containers: setting the UI resource container. | ||
| - | The UI resource container is another special mechanism that works similar to setting the UI resource, but it works exactly the other way round. While setting the UI resource “hides” components from the technology in UI layer, setting the UI resource container hides components from the UI layer, while they are added in the technology. A little complicated, here is our example using this technique again: | + | The UI resource container is another special mechanism that works similar to setting the UI resource, but it works the other way round. While setting the UI resource “hides” components from the technology in UI layer, setting the UI resource container hides components from the UI layer, while they are added in the technology.. As it is a little complicated, here is our example using this technique again: |
| <code java> | <code java> | ||
| Line 411: | Line 411: | ||
| ===== Conclusion ===== | ===== Conclusion ===== | ||
| - | Because of the way the [[https://sourceforge.net/projects/jvx/|JVx]] framework is designed, it is easy to access all layers of the GUI framework and also facilitate the usage of these layers to create custom components and allow easy access to the wrapped components, no matter on what layer or of what kind they are. | + | Because of the way the [[https://sourceforge.net/projects/jvx/|JVx]] framework is designed, it is easy to access all layers of the GUI framework and facilitate the usage of these layers to create custom components and allow easy access to the wrapped components, no matter on what layer or of what kind they are. |
| - | ====== Launchers and applications ====== | + | ====== Launchers and Applications ====== |
| - | Let’s talk about Launchers, and how they are used to start [[https://sourceforge.net/projects/jvx/|JVx]] applications. | + | Let’s talk about launchers, and how they are used to start [[https://sourceforge.net/projects/jvx/|JVx]] applications. |
| - | ===== Starting an application ===== | + | ===== Starting an Application ===== |
| From a technical point of view, there are two prerequisites which must be fulfilled before a [[https://sourceforge.net/projects/jvx/|JVx]] application can run: | From a technical point of view, there are two prerequisites which must be fulfilled before a [[https://sourceforge.net/projects/jvx/|JVx]] application can run: | ||
| - | * the JVM must have started. | + | * The JVM must have started. |
| - | * the technology specific system must have started. | + | * The technology specific system must have started. |
| - | Then, and only then, the [[https://sourceforge.net/projects/jvx/|JVx]] application can run. Depending on the implementation that is used, that can be as easily as instancing the factory (Swing, JavaFX), but can also mean that a servlet server has to start (Vaadin). Because we do not wish to encumber our applications with technology specific code, we have to entrust all this to an encapsulated entity, meaning the implementations of ''%%ILauncher%%'' and ''%%IApplication%%''. | + | Then, and only then, the [[https://sourceforge.net/projects/jvx/|JVx]] application can run. Depending on the implementation that is used, that can be as easy as instancing the factory (Swing, JavaFX), but it can also mean that a servlet server has to start (Vaadin). Because we do not wish to encumber our applications with technology-specific code, we have to entrust all this to an encapsulated entity, meaning the implementations of ''%%ILauncher%%'' and ''%%IApplication%%''. |
| ===== Following the Chain ===== | ===== Following the Chain ===== | ||
| Line 574: | Line 574: | ||
| Because the launcher has previously started the technology and created the factory, we can now use UI components, which means we are already independent of the underlying technology. So, the ''%%IApplication%%'' implementation can already be used with different technologies and is completely independent. | Because the launcher has previously started the technology and created the factory, we can now use UI components, which means we are already independent of the underlying technology. So, the ''%%IApplication%%'' implementation can already be used with different technologies and is completely independent. | ||
| - | ===== Notes on the launcher ===== | + | ===== Notes on the Launcher ===== |
| - | As you might have noticed, in our example the launcher is a (window) frame, that makes sense for nearly every desktop GUI toolkit as they all depend upon a window as main method to display their applications. But the launcher could also be simpler, for example just a call to start the GUI thread. Or it could be something completely different, for example an incoming HTTP request. | + | As you might have noticed, in our example the launcher is a (window) frame. That makes sense for nearly every desktop GUI toolkit as they all depend upon a window as main method to display their applications. But the launcher could also be simpler: for example, just a call to start the GUI thread. Or it could be something completely different: for example, an incoming HTTP request. |
| - | Also don’t forget that the launcher is providing additional functionality to the application, like saving file handles, reading and writing the configuration and similar platform and toolkit dependent operations, see the [[https://sourceforge.net/p/jvx/code/HEAD/tree/trunk/java/swing/src/com/sibvisions/rad/ui/swing/impl/SwingApplication.java|launcher for Swing for further details]]. | + | Also, don’t forget that the launcher is providing additional functionality to the application, like saving file handles, reading and writing the configuration, and similar platform and toolkit-dependent operations. See the [[https://sourceforge.net/p/jvx/code/HEAD/tree/trunk/java/swing/src/com/sibvisions/rad/ui/swing/impl/SwingApplication.java|launcher for Swing for further details]]. |
| ===== Conclusion ===== | ===== Conclusion ===== | ||
| Line 590: | Line 590: | ||
| ===== What is it? ===== | ===== What is it? ===== | ||
| - | DataBooks are an active model, which allow you to directly query and manipulate the data. Contrary to many other systems [[https://sourceforge.net/projects/jvx/|JVx]] does not map the data into objects, but instead allows you to directly access it in a table like fashion, exposing columns, rows and values. | + | DataBooks are an active model, which allow you to directly query and manipulate the data. Contrary to many other systems, [[https://sourceforge.net/projects/jvx/|JVx]] does not map the data into objects, but allows you to directly access it in a table-like fashion exposing columns, rows, and values. |
| - | One could say that it is like a three dimensional array, with these dimensions: | + | One could say that it is like a three dimensional array with these dimensions: |
| * DataPages | * DataPages | ||
| Line 598: | Line 598: | ||
| * Columns/Values | * Columns/Values | ||
| - | With DataPages containing DataRows, which itself contain the values and everything is referencing the RowDefinition, which outlines how a row looks like. | + | with DataPages containing DataRows, which in turn contain the values and everything referencing the RowDefinition, which further outlines how a row looks like. |
| {{:jvx:reference:databook.png?nolink|DataBook Architecture, the DataBook contains DataPages, which contain DataRows.}} | {{:jvx:reference:databook.png?nolink|DataBook Architecture, the DataBook contains DataPages, which contain DataRows.}} | ||
| Line 616: | Line 616: | ||
| dataBook.setRowDefinition(rowDefinition); | dataBook.setRowDefinition(rowDefinition); | ||
| </code> | </code> | ||
| - | ==== ColumnDefinition ==== | + | ==== Column Definition ==== |
| - | The ColumnDefinition defines and provides all necessary information about the column, like its DataType, its size and if it is nullable or not. You can think of it as one column in a table. | + | The column definition defines and provides all necessary information about the column, like its datatype, its size, and whether it is nullable or not. You can think of it as one column in a table. |
| <code java> | <code java> | ||
| Line 626: | Line 626: | ||
| ==== MetaData ==== | ==== MetaData ==== | ||
| - | Most of the ColumnDefinition is additional information about the column, like if it is nullable, the label of the column, default values, allowed values and similar information. | + | Most of the column definition is additional information about the column, like if it is nullable, the label of the column, default values, allowed values, and similar information. |
| ==== DataType ==== | ==== DataType ==== | ||
| - | Of course we must define what type the value in the column has, this is done by setting a DataType on the ColumnDefinition. The DataType defines what kind of values the column holds, like if it is a String, or a Number or something else. We do provide the most often used DataTypes out of the box: | + | Of course, we must define what type the value in the column has. This is done by setting a data type on the column definition. The data type defines what kind of values the column holds, like if it is a String, a Number, or something else. We provide the most often used data types out of the box: |
| * BigDecimal | * BigDecimal | ||
| Line 640: | Line 640: | ||
| * Timestamp | * Timestamp | ||
| - | It is possible to add new DataTypes by simply implementing ''%%IDataType%%''. | + | It is possible to add new data types by simply implementing ''%%IDataType%%''. |
| ===== DataRow ===== | ===== DataRow ===== | ||
| - | The DataRow repesents a single row of data, it holds/references its own RowDefinition and of course provides access to the values of the row. Accessing the DataRow can be done either by column index or column name, and the methods do either return or accept Objects. Let’s look at a simple usage example: | + | The data row represents a single row of data; it holds/references its own row definition and, of course, provides access to the values of the row. Accessing the data row can be done either by column index or column name, and the methods either return or accept objects. Let’s look at a simple usage example: |
| <code java> | <code java> | ||
| Line 655: | Line 655: | ||
| ===== DataPage ===== | ===== DataPage ===== | ||
| - | The DataPage is basically a list of DataRows, it also holds its own RowDefinition which is shared with all the contained DataRows. | + | The data page is basically a list of data rows, it also holds its own row definition, which is shared with all the contained data rows. |
| - | The main usage of DataPages is to allow paging in a master/detail relationship. If the master selects a different row, the detail databook does select the related DataPage. | + | The main usage of data pages is to allow paging in a master/detail relationship. If the master selects a different row, the detail databook selects the related data page. |
| ===== DataBook ===== | ===== DataBook ===== | ||
| - | The DataBook is the main model of [[https://sourceforge.net/projects/jvx/|JVx]], it provides direct access to its current DataPage and DataRow by extending from IDataRow and IDataPage. | + | The data book is the main model of [[https://sourceforge.net/projects/jvx/|JVx]], it provides direct access to its current data page and data row by extending from IDataRow and IDataPage. |
| - | By default, the DataBook holds one DataPage and only has multiple DataPages if it is the detail in a master/detail relationship. | + | By default, the data book holds one data page and only has multiple data pages if it is the detail in a master/detail relationship. |
| - | ===== Usage example ===== | + | ===== Usage Example ===== |
| - | Here is a simple usage example of a ''%%MemDataBook%%'', an ''%%IDataBook%%'' implementation which does only operate in memory: | + | Here is a simple example of a ''%%MemDataBook%%'', an ''%%IDataBook%%'' implementation which only operates in memory: |
| <code java> | <code java> | ||
| Line 704: | Line 704: | ||
| dataBook.delete(); | dataBook.delete(); | ||
| </code> | </code> | ||
| - | ==== Accessing the data with Strings ==== | + | ==== Accessing the Data With Strings ==== |
| - | One of the major advantages of the DataBook concept is that there is no need to create new classes to represent each table, view or query result. One can always use the DataBook, directly and easily and model changes don’t necessitate changes on the client side. The downside to this approach is that we lose compile time checks because we access the data dynamically. However, This can be mitigated by using [[https://marketplace.eclipse.org/content/eplug-jvx|EPlug, an Eclipse plugin]] which provides compile time checks and many more features. | + | One of the major advantages of the data book concept is that there is no need to create new classes to represent each table, view, or query result. One can always use the data book directly and easily, and model changes don’t necessitate changes on the client side. The downside to this approach is that we lose compile time checks because we access the data dynamically. However, this can be mitigated by using [[https://marketplace.eclipse.org/content/eplug-jvx|EPlug, an Eclipse plugin]] which provides compile time checks and many more features. |
| - | ==== No primitives, Objects only ==== | + | ==== No Primitives, Objects Only ==== |
| - | We do not provide overloads to fetch primitives, that is because there are mainly three types of data inside a database: | + | We do not provide overloads to fetch primitives. This is because there are mainly three types of data inside a database: |
| * Numbers | * Numbers | ||
| Line 716: | Line 716: | ||
| * Binary Data | * 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 dangerous 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 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? ==== | + | ==== Where Are the Data Pages? ==== |
| - | What is not clear from this example is how and when DataPages are used. As a matter of fact, most of the time there is no need to think about DataPages because they are managed directly by the DataBook, and if used like this there is only one DataPage. Multiple DataPages will be used if there is a Master/Detail relationship defined in which case the DataBook does select the correct DataPage automatically. | + | What is not clear from this example is how and when data pages are used. As a matter of fact, most of the time there is no need to think about data pages because they are managed directly by the data book, and, if used like this, there is only one data page. Multiple data pages will be used if there is a master/detail relationship defined, in which case the data book selects the correct data page automatically. |
| ===== Master/Detail ===== | ===== Master/Detail ===== | ||
| Line 733: | Line 733: | ||
| left join DETAIL d on m.ID=d.MASTER_ID; | left join DETAIL d on m.ID=d.MASTER_ID; | ||
| </code> | </code> | ||
| - | We can of course express a master/detail relationship when using DataBooks. For that we just create a ''%%ReferenceDefinition%%'' and assign it to the detail DataBook: | + | We can of course express a master/detail relationship when using data books. For that we just create a ''%%ReferenceDefinition%%'' and assign it to the detail data book: |
| <code java> | <code java> | ||
| Line 751: | Line 751: | ||
| detailDataBook.open(); | detailDataBook.open(); | ||
| </code> | </code> | ||
| - | Let’s assume the following data for illustration purposes: | + | Let’s assume the following data for illustrative purposes: |
| <code> | <code> | ||
| Line 782: | Line 782: | ||
| ===== Conclusion ===== | ===== Conclusion ===== | ||
| - | The DataBook is the backbone of [[https://sourceforge.net/projects/jvx/|JVx]], it provides a clean and easy way to access and manipulate data. At the same time, it is flexible and can be customized to specific needs with ease. | + | The data book is the backbone of [[https://sourceforge.net/projects/jvx/|JVx]], it provides a clean and easy way to access and manipulate data. At the same time, it is flexible and can be customized to specific needs with ease. |
| ====== Application Basics ====== | ====== Application Basics ====== | ||
| Line 796: | Line 796: | ||
| The following method is a simplified way to launch a [[https://sourceforge.net/projects/jvx/|JVx]] application. Normally, you’d use the technology specific launcher to launch the application. These launchers do know exactly what is required to set it up and start the technology and the application. However, covering the launchers is out of scope for this post, so we will review them and their mechanics in a follow-up. | The following method is a simplified way to launch a [[https://sourceforge.net/projects/jvx/|JVx]] application. Normally, you’d use the technology specific launcher to launch the application. These launchers do know exactly what is required to set it up and start the technology and the application. However, covering the launchers is out of scope for this post, so we will review them and their mechanics in a follow-up. | ||
| - | ===== The simplest JVx application: Just the GUI ===== | + | ===== The Simplest JVx Application: Just the GUI ===== |
| - | 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. | + | 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 opens 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: | ||
| Line 805: | Line 805: | ||
| UIFactoryManager.getFactoryInstance(SwingFactory.class); | UIFactoryManager.getFactoryInstance(SwingFactory.class); | ||
| </code> | </code> | ||
| - | With this little code we have initialized everything we need to create a simple Swing application. Now we can start to create and populate a window with something: | + | With this little code, we have initialized everything we need to create a simple Swing application. Now we can start to create and populate a window with something: |
| <code java> | <code java> | ||
| Line 817: | Line 817: | ||
| frame.eventWindowClosed().addListener(() -> System.exit(0)); | frame.eventWindowClosed().addListener(() -> System.exit(0)); | ||
| </code> | </code> | ||
| - | We can start to create and manipulate the GUI, in this case we are building a simple window with a label inside. Last but not least, we make sure that the JVM will exit when the window is closed. | + | We can start to create and manipulate the GUI. In this case we are building a simple window with a label inside. Last but not least, we make sure that the JVM will exit when the window is closed. |
| A very good example and showcase for that is the [[https://github.com/sibvisions/jvx.kitchensink|JVx Kitchensink]]. | A very good example and showcase for that is the [[https://github.com/sibvisions/jvx.kitchensink|JVx Kitchensink]]. | ||
| - | That’s it. That is the most simple way to start a [[https://sourceforge.net/projects/jvx/|JVx]] application. We can use all controls and we can use ''%%MemDataBook%%''s without any problem or limitation. And best of all, we can simply switch to another Technology by using another factory. | + | That’s it. That is the most simple way to start a [[https://sourceforge.net/projects/jvx/|JVx]] application. We can use all controls, and we can use ''%%MemDataBook%%''s without any problem or limitation. Best of all, we can simply switch to another technology by using another factory. |
| ===== Anatomy of a remote JVx application ===== | ===== Anatomy of a remote JVx application ===== | ||