OOP2

Added docs

Author
Maarten 'Vngngdn' Vangeneugden
Date
Nov. 18, 2016, 1:05 p.m.
Hash
2c2a7656173d667ae273677b79c0d79e3ebaac40
Parent
e680d277849474ffb1b15dab80c79c124819276b
Modified files
Challenge/jsugar-readme.md
Challenge/ontwerpkeuzes.txt

Challenge/jsugar-readme.md

65 additions and 0 deletions.

View changes Hide changes
+
1
======
+
2
+
3
JSugar is a tiny framework, in an attempt to hide away the tons of
+
4
useless cruft that you get from working with Java's Swing.
+
5
+
6
Features
+
7
--------
+
8
+
9
Purely speaking, JSugar does not add anything new compared to when you're using
+
10
Swing. It does however, offer some considerable advantages over using Swing
+
11
directly:
+
12
+
13
* Easy creation of windows, that offer a series of convenient methods like
+
14
  createButton(), allowing for easy creation of small GUI programs.
+
15
* Built-in support for action triggering; Just say which method should be
+
16
  triggered where, and you're done.
+
17
* Easy learning curve, compared to manually handling Swing. Create a new Window,
+
18
  slap some components on it, add the methods it needs to call on trigger, and
+
19
  done.
+
20
* Relies mainly on primitive types, like integer arrays, and classes that are
+
21
  available in every recent OpenJDK version, like Strings.
+
22
* Completely [free/libre software](https://www.gnu.org/philosophy/free-sw.html).
+
23
* Very lightweight. It's just a bunch of source files that you can directly link
+
24
  to. Putting it in a seperate jar will cause more harm than good.
+
25
* Only RuntimeExceptions will be thrown, avoiding *exception infection* that
+
26
  you'll get from using self-defined exceptions in Java.
+
27
* Documentation available through JavaDoc. I do my very best to provide clear
+
28
  documentation, so you know how to use this without having to figure it out
+
29
  yourself.
+
30
* Components you add are returned to the caller, so if you do need some more
+
31
  advanced stuff, you can add it yourself.
+
32
+
33
Limitations
+
34
-----------
+
35
+
36
The convenience causes some limitations, but they're fairly minor, and if you're
+
37
using JSugar, it's very unlikely you'd be bothered by them anyway, but here they
+
38
are:
+
39
+
40
* You can't add your own panels to the window, but you'll most likely just want
+
41
  to add some components to the window itself.
+
42
* The panels default to double buffering (which you should do anyway) and the
+
43
  flow layout.
+
44
* The window is automatically updated whenever a new component is added. When
+
45
  using Swing 'natively', you could postpone updating, but why did you add a
+
46
  component then in the first place?
+
47
* *Trigger methods* can only have 1 parameter, or none at all. That 1 parameter
+
48
  must be of type java.awt.event.ActionEvent. This should be enough for >80% of
+
49
  use cases, and if you really need more flexibility, you can add your own
+
50
  action handlers manually.
+
51
* Pressing the X in the title bar of the window closes it. >95% of use cases do
+
52
  this anyway.
+
53
* Some silly stuff like adding icons to buttons, checkboxes, ... is not
+
54
  possible. You'll have to do that yourself. Yet for most use cases,you might
+
55
  just do the sane thing and add text.
+
56
* Certain components don't offer the ability to attach a trigger action to them.
+
57
  We're talking about components like labels. But then again, these kind of
+
58
  components shouldn't get much triggers anyway.
+
59
* Some components have deliberately been left out, because they don't offer many
+
60
  information/interaction for the user. An example for this, is the
+
61
  JProgressBar. Although in some rare cases it's a very useful thing, but it's
+
62
  mainly eye candy, and you may just show the data in a JLabel anyway.
+
63
  However, if I feel like doing so, and the rest of the library is stable, I may
+
64
  add such components.
+
65

Challenge/ontwerpkeuzes.txt

74 additions and 0 deletions.

View changes Hide changes
+
1
==============================
+
2
+
3
Toepassing types/classes
+
4
------------------------
+
5
Doorheen het programma heb ik getracht zoveel mogelijk gebruik te maken van
+
6
types/classes die
+
7
- Veelvoorkomend zijn in de Java STL (Zoals String, Set, List, ...)
+
8
- primitief zijn (ints, ...), omdat deze operatoren hebben en de code
+
9
  leesbaarder maken
+
10
+
11
Een goed voorbeeld hiervan zijn bv. de faciliteiten:
+
12
I.p.v. een aparte "Facility"-class te maken, heb ik de verschillende
+
13
faciliteiten voorgesteld door een simpele String. De voordelen van deze aanpak
+
14
zijn ook direct duidelijk:
+
15
- Betekenis is direct duidelijk; de faciliteit letterlijk in de code vernoemd
+
16
- Makkelijke interactie met GUI, die sowieso Strings vraagt voor bv. JLabel
+
17
- Uitbreidbaarheid wordt bekomen door simpelweg een nieuwe String te
+
18
  introduceren
+
19
+
20
View en GUI
+
21
-----------
+
22
Werken met GUI's is vaak tijdrovend en veroorzaakt snel errors, zeker met bv.
+
23
anonieme methods, exceptions, ...
+
24
Alhoewel mijn programma grotendeels in een MVC-stijl is geschreven, maken de
+
25
view-classes (RegistrationView, SearchView, ...) achterliggend gebruik van een
+
26
zelfgemaakt framework om makkelijk vensters te maken.
+
27
Dit kleine framework is een persoonlijk hobbyproject dat ik JSugar noem.
+
28
Het biedt een heleboel voordelen, vergeleken met elk GUI-venster zelf opstellen:
+
29
- Vaak gebruikte GUI-widgets (zoals een label, textfield) worden aangemaakt en
+
30
  toegevoegd door slechts 1 method op te roepen
+
31
- JSugar maakt gebruik van reflectie om op een leesbare en uitbreidbare manier
+
32
  knoppen te activeren:
+
33
  public JButton createButton(String text, String action, String methodName, Object triggerObject)
+
34
  'methodName' is een simpele String, en 'triggerObject' is het object waar deze
+
35
  method moet worden opgeroepen.
+
36
- Automatische uitlijning van widgets
+
37
Voor meer informatie kunt u JSugar-readme.md raadplegen.
+
38
+
39
java.util.Date
+
40
--------------
+
41
+
42
Doorheen het programma maak ik vaak gebruik van de Date-class uit de Java STL,
+
43
om de volgende redenen:
+
44
- Uitbreidbaarheid: Door overal eenzelfde type te gebruiken, is het gemakkelijk
+
45
  om nieuwe modules toe te voegen, zonder dat daarvoor abstractielagen etc.
+
46
  nodig zijn.
+
47
- Uniformiteit: Eenzelfde type uit de STL laat de ontwikkelaar toe om door het
+
48
  hele programma heen hetzelfde denkpatroon aan te houden; een
+
49
  Stringvoorstelling hier, een integer daar, ... veroorzaken problemen en bugs,
+
50
  die met deze class voorkomen worden.
+
51
+
52
Bedden
+
53
------
+
54
+
55
Ik heb voor bedden een aparte class aangemaakt, omdat deze een bepaalde state
+
56
bijhouden, nml. wanneer ze gereserveerd zijn.
+
57
+
58
+
59
Reservation
+
60
-----------
+
61
Voor de reservaties heb ik besloten om enkel die data bij te houden die inherent
+
62
gerelateerd is aan die reservatie:
+
63
- Enkel gereserveerde bedden i.p.v. gereserveerde kamers. Qua uitbreidbaarheid
+
64
  heeft dit tot gevolg dat men gemakkelijk kan uitbreiden naar reservaties,
+
65
  gespreid over verschillende kamers.
+
66
+
67
+
68
ReservationView
+
69
---------------
+
70
Merk op hoe in ReservationView de data van de Reservation direct in de GUI wordt
+
71
geplaatst.
+
72
Dit staat toe om zeer gemakkelijk deze class te hergebruiken voor zowel het
+
73
**aanmaken** als het **updaten** van de reservatie.
+
74