-
Notifications
You must be signed in to change notification settings - Fork 0
Programming Notes
All programmers have their Funny Little Ways. I am no exception. This section is intended to explain some of the background decisions which resulted in OHR. It will make grim reading for some, but I am unrepentant, though I am able to learn and am happy to take on board any constructive criticism.
Although I enjoy programming, I am actually more interested in programming techniques, but sadly this has failed to make me a better programmer. So when I produce something like OHR, it's as much about the journey (the programming) as the destination (the end product). Things I thought about before, while and after implementing this little program were OSGi, JSON, JSONPath, data binding, DBMS, JavaFX, CSS and SMACCS, responsive apps, well-behaved cross-platform apps and SVG. I'll discuss these in the following sections.
OpenHAB is implemented using OSGi. I did some experimentation a few years back with OSGi and particularly Declarative Services, and I'm actually very interested in these subjects. However, since that experimentation, I have spent three or four years implementing and maintaining websites (mostly PHP-based), and I would have had to spend a long time working my way back in. So I decided to go with POJOs. I don't think this is much of a problem, however, unless someone wants to convert OHR into something embedded in OpenHAB.
My personal preference and experience favour XML, but a lot of OpenHAB is now JSON-based, in particular the not surprisingly named JSON database that I wanted to extract data from, so JSON was always going to be at the core of OHR. Rather than having a mixture of JSON and XML, I decided to implement those things for which I would normally have used XML (e.g. configuration files, etc.) in JSON also.
A little known fact is that I actually submitted the first version of OpenHAB's JSONPath transformation, though there is no trace of my code left in it these days. Having decided to use JSON, it was a short conceptual step to using trying to use JSONPath to select the data elements to be extracted from the JSON database. Thus, OHR has a configuration file called jsonpath.conf.json which can be used to define which attributes are extracted for which OpenHAB bindings. However, I am not sure that this is actually useful, so it might find its way onto the deprecated list.
I started programming OHR thinking that the JSON database was just a collection of JSON data files to be parsed using JSONPath. About half-way through, it occurred to me that these files were presumably serialised (or marshalled) using some data binding mechanism. To be honest, I have not pursued this train of thought, so I do not know if OpenHAB uses data binding as such. However, if this were the case, it would obviously have made much more sense to read in the JSON database by deserialising (aka unmarshalling) it with the same library that OpenHAB uses.
The data from the JSON database is read into OHR using Jackson Databind and is stored in the program using Java Collections (mainly Map and List). Given my time over again, I might have considered storing the data in an in-memory database. How this might work with any data binding mechanism would have had to be examined carefully, though.
This is my first real JavaFX program, unless you count some experiments I did a few years back using JavaFX in some OSGi test programs. I have written applications in Swing in the past, and – in my opinion – JavaFX is a dream in comparison. For me, one of the strong points of JavaFX is the ability to separate the UI structure and rendering (view) from the program logic and data (control and model). More about this in the two following sections.
The other big plus point of JavaFX is that it is not Swing. With Swing it was very difficult, if not impossible, to write programs that did not look like they were Swing. So, Java UIs looked consistently awful on all platforms, though perhaps slightly less so on Windows and Linux. This did nothing to enhance the position of Java and Java applications on the desktop or – famously – in iOS. JavaFX allows much more latitude in developing cross-platform applications that look like they belong on any of the platforms on which they are run.
One of the techniques that have been developed for websites over the past few years is called responsive web design. This refers to the ability of a user interface to respond to the constraints of the screen on which it is displayed: thus, a single design would appear in a different form on a desktop, a tablet, or a mobile phone. On websites, responsive design is implemented using CSS and JavaScript. I wanted to experiment with this in OHR using CSS and JavaFX. OHR is perhaps not the best program to try this out with, however, since it seems pretty unlikely that anyone will ever use OHR on a mobile phone; and the interface is so simple that it would hardly look different anyway. But these thoughts explain what happens next.
Having decided to use CSS for rendering OHR's UI, it seemed appropriate to consider how to optimise its use and methodologies for consistent design. In the web development space, SASS is used to provide consistency, structure and more power to CSS development. SASS is a superset of CSS (rather like a macro language, in fact), that is translated by a preprocessor into pure CSS, which can then be used to render web pages. JavaFX uses CSS too to render FXML forms, though the CSS elements used by JavaFX differ considerably from those used elsewhere. So SASS libraries developed for web pages are unlikely to be of any use in a JavaFX app.
We are talking serious overkill here, but I wanted to find out where the issues might be in using SASS with JavaFX. My interim conclusion is that it can be done and might be of more general application, but more experimentation would be needed.
Having decided to use SASS, it was – at least for a web developer – a relatively small jump to using the SMACCS methodology. This is patently doable, but for this application it is way over the top and no sensible conclusions are possible. The use of SMACCS is reflected in the baroque folder structure used for SASS and CSS.
I think it is fair to say that all of this was entirely experimental and does little to enhance the quality of OHR. On the other hand, it has no negative effect on the UI either, and I think it is fair to say that the experiment in itself, given the narrow scope of the program, has been successful.
One of my special interests is in developing cross-application apps in Java that behave on each platform as if they were native apps and respect all the platform's conventions regarding look and feel. Please note that, for me, these are not one thing ("L&F") but at least two. Look has traditionally received the most attention, and programmer neuroses about themes (light, dark) and skins are rife, with the result that many solutions have been developed. Almost as a side effect, products like JavaFX have made it easier to approximate the look of the host platform, and CSS enables us to make the fine adjustments necessary for each platform. Note that this means there will probably be a different CSS values for each platform. Hopefully, using SASS will make it easy to manage the variants.
Issues of cross-platform feel, however, are often ignored. So what is feel? In my view, the issue of feel is epitomised by the question of where menus are placed. But other important questions include menu structure (sub-menu and item naming and ordering); UI patterns (e.g. preferences/settings, help, file/folder choosers); the use of shortcuts; and where a program may put files. The latter is a well-known issue for anyone who has used a Unix or Linux program on a different platform and had their home directory cluttered with its debris.
I have tried to provide a structure for dealing with some of these issues in OHR. OHR does not really use shortcuts or menus, but I hope that the Host abstraction and the use of SASS will enable people who are familiar with and well-disposed towards Unix/Linux and Windows to write extensions so that OHR will run in harmony on those platforms. It should not be much work. At the time of writing, I have only customised OHR for MacOS, as I am not really familiar with – or even well-disposed towards :-) – Unix/Linux and Windows on the desktop. Unix/Linux servers are a different matter.
OHR also generates SVG diagrams suitable for embedding in Dokuwiki to show the relationships of products within a given binding. This required some tinkering with the CSS used by Dokuwiki to provide a consistent UI experience. Please note that currently only the default "Dokuwiki" theme is supported. The SVG diagrams will be displayed by other themes, but their CSS will not be adapted. Relatively late in the development process, I discovered that Dokuwiki uses LESS, which is an alternative to SASS. This is not really a problem because the two uses do not overlap. But there is a LESS file included in the distribution that is intended to be added to the Dokuwiki configuration.
The first iteration of OHR only worked from the command line. Now, there are two alternative ways of starting OHR (command line and JavaFX). They both work by gathering program parameters and passing them into the singleton Configuration, from where they are retrieved and processed by the app's back end.
I am not sure whether the command line interface currently works, though a sh file is provided which used to...