From 9f7d36de1a9483602274052264e11ab4c53cd273 Mon Sep 17 00:00:00 2001 From: danthe1st Date: Thu, 28 Sep 2023 11:16:26 +0200 Subject: [PATCH 01/12] enums --- app/data/authors.yaml | 8 + .../04_classes_objects/01_enums.md | 149 ++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md diff --git a/app/data/authors.yaml b/app/data/authors.yaml index 334d39a..5e4f94b 100644 --- a/app/data/authors.yaml +++ b/app/data/authors.yaml @@ -74,3 +74,11 @@ nine textbooks on software programming. Most recently, she is a contributing author to The Definitive Guide to Modern Java Clients with JavaFX 17. Gail has presented at various Java conferences and JUGS including Devoxx, DevNexus, JCrete, and Oracle Code/JavaOne worldwide. + +- name: Daniel Schmid + github: danthe1st + twitter: dan_the_1st + photo_url: https://danthe1st.github.io/img/Daniel.jpg + website: https://danthe1st.github.io/ + description: | + Daniel is a Java Developer from Austria who is also managing an online Java User Group. \ No newline at end of file diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md new file mode 100644 index 0000000..c291d97 --- /dev/null +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -0,0 +1,149 @@ +--- +id: lang.classes-objects.enums +title: Enumerations +slug: learn/classes-objects/enums +type: tutorial-group +group: classes_objects +layout: learn/tutorial-group.html +subheader_select: tutorials +main_css_id: learn +description: "Working with enumerations." +last_update: 2023-09-28 +author: ["DanielSchmid"] +--- +## What are enums? +Enums are classes where all instances are known to the compiler. +They are used for creating types that can only have few possible values. + +Enums can be created similar to classes but use the `enum` keyword instead of `class`. +In the body, there is a list of instances of the enum named enum constants which are seperated by `,`. +No instances of the enum can be created outside of enum constants. + +```java +public enum DayOfWeek { + MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY +} +``` + +All enums implicitely extend `java.lang.Enum` and cannot have any subclasses. + +## Accessing and comparing enums +The values of an enum can be used as constants. +In order to check whether two instances of an enum are the same, the `==` operator can be used. +```java +DayOfWeek weekStart = DayOfWeek.MONDAY; + +if (weekStart == DayOfWeek.MONDAY) { + System.out.println("The week starts on Monday."); +} +``` + +It is also possible to use `switch` for performing actions depending on the value of the enum. + +```java +DayOfWeek someDay = DayOfWeek.FRIDAY; + +switch (someDay) { + case MONDAY: + System.out.println("The week just started."); + break; + case TUESDAY: + case WEDNESDAY: + case THURSDAY: + System.out.println("We are somewhere in the middle of the week."); + break; + case FRIDAY: + System.out.println("The weekend is near."); + break; + case SATURDAY: + case SUNDAY: + System.out.println("Weekend"); + break; + default: + throw new AssertionError("Should not happen"); +} +``` + +With [Switch Expressions](id:lang.classes-objects.switch-expression), +the compiler can check whether all values of the enum are handled. +```java +DayOfWeek someDay = DayOfWeek.FRIDAY; + +String text = switch (someDay) { + case MONDAY -> "The week just started."; + case TUESDAY, WEDNESDAY, THURSDAY -> "We are somewhere in the middle of the week."; + case FRIDAY -> "The weekend is near."; + case SATURDAY, SUNDAY -> "Weekend"; +}; + +System.out.println(text); +``` + +## Adding members to enums + +Just like classes, enums can have constructors, methods and fields. +In order to add these, it is necessary to add a `;` after the list of enum constants. +Arguments to the constructor are passed in parenthesis after the declaration of the enum constant. + +```java +public enum DayOfWeek { + MONDAY("MON"), TUESDAY("TUE"), WEDNESDAY("WED"), THURSDAY("THU"), FRIDAY("FRI"), SATURDAY("SAT"), SUNDAY("SUN"); + + private final String abbreviation; + + DayOfWeek(String abbreviation) { + this.abbreviation = abbreviation; + } + + public String getAbbreviation() { + return abbreviation; + } +} +``` + +## Special methods +All enums have a few methods that are added implicitely. + +For example, the method `name()` is present in all enum instances and can be used to get the name of the enum constant. +Similarly, a method named `ordinal()` returns the position of the enum constant in the declaration. +```java +System.out.println(DayOfWeek.MONDAY.name());//MONDAY +System.out.println(DayOfWeek.MONDAY.ordinal());//0 because MONDAY is the first constant in the DayOfWeek enum +``` + +Aside from instance methods, there are also static methods added to all enums. +The method `values()` returns an array containing all instances of the enum and the method `valueOf(String)` can be used to get a specific instance by its name. +``` +DayOfWeek[] days = DayOfWeek.values();//all days of the week +DayOfWeek monday = DayOfWeek.valueOf("MONDAY"); +``` + +## Using enums for singletons +Since enums can only have a specific number of instances, it is possible to create a singleton by creating an enum with only a single enum constant. +```java +public enum SomeSingleton { + INSTANCE; + //fields, methods, etc. +} +``` + +## Abstract methods in enums +Even though enums cannot be extended, they can still have `abstract` methods. In that case, an implementation must be present in each enum constant. +```java +enum MyEnum { + A() { + @Override + void doSomething() { + System.out.println("a"); + } + }, + B() { + @Override + void doSomething() { + System.out.println("b"); + } + }; + + abstract void doSomething(); +} +``` \ No newline at end of file From b0c4575df3e6899cea6c75f7e4c771de64c1cbac Mon Sep 17 00:00:00 2001 From: danthe1st Date: Thu, 28 Sep 2023 12:26:05 +0200 Subject: [PATCH 02/12] fix java codeblock in enums --- .../04_classes_objects/01_enums.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index c291d97..e708535 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -113,7 +113,7 @@ System.out.println(DayOfWeek.MONDAY.ordinal());//0 because MONDAY is the first c Aside from instance methods, there are also static methods added to all enums. The method `values()` returns an array containing all instances of the enum and the method `valueOf(String)` can be used to get a specific instance by its name. -``` +```java DayOfWeek[] days = DayOfWeek.values();//all days of the week DayOfWeek monday = DayOfWeek.valueOf("MONDAY"); ``` From 7df851693078f0053e52c3393fb2763863e328da Mon Sep 17 00:00:00 2001 From: danthe1st Date: Thu, 28 Sep 2023 12:43:44 +0200 Subject: [PATCH 03/12] link to java.lang.Enum --- app/data/javadoc.json | 1 + .../04_classes_objects/01_enums.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/app/data/javadoc.json b/app/data/javadoc.json index 338e73a..df3c007 100644 --- a/app/data/javadoc.json +++ b/app/data/javadoc.json @@ -1097,6 +1097,7 @@ "Deque.push(E)": "java.base/java/util/Deque.html#push(E)", "Deque.removeFirst()": "java.base/java/util/Deque.html#removeFirst()", + "Enum": "java.base/java/lang/Enum.html", "Enumeration": "java.base/java/util/Enumeration.html", "HashSet": "java.base/java/util/HashSet.html", diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index e708535..5b98d8d 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -25,7 +25,7 @@ public enum DayOfWeek { } ``` -All enums implicitely extend `java.lang.Enum` and cannot have any subclasses. +All enums implicitely extend [`java.lang.Enum`](javadoc:Enum) and cannot have any subclasses. ## Accessing and comparing enums The values of an enum can be used as constants. From 9030ba7feffcfbdff82771f2a56b1acf1d55a640 Mon Sep 17 00:00:00 2001 From: danthe1st Date: Thu, 28 Sep 2023 12:44:47 +0200 Subject: [PATCH 04/12] change title from Enums to Enumerations --- .../04_classes_objects/01_enums.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index 5b98d8d..faf60e4 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -1,6 +1,6 @@ --- id: lang.classes-objects.enums -title: Enumerations +title: Enums slug: learn/classes-objects/enums type: tutorial-group group: classes_objects From 3af900af6b97764219ffc0f16b6c921506abf6ee Mon Sep 17 00:00:00 2001 From: danthe1st Date: Thu, 28 Sep 2023 18:18:05 +0200 Subject: [PATCH 05/12] enums instead of enumerations in description --- .../04_classes_objects/01_enums.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index faf60e4..a83fb18 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -7,7 +7,7 @@ group: classes_objects layout: learn/tutorial-group.html subheader_select: tutorials main_css_id: learn -description: "Working with enumerations." +description: "Working with enums." last_update: 2023-09-28 author: ["DanielSchmid"] --- From 50010a7906465960d7f1ed3c0f11fd6c975f039f Mon Sep 17 00:00:00 2001 From: danthe1st Date: Fri, 29 Sep 2023 17:27:28 +0200 Subject: [PATCH 06/12] formatting, additional comments, TOC, etc. --- app/data/authors.yaml | 2 +- .../04_classes_objects/01_enums.md | 127 ++++++++++-------- 2 files changed, 74 insertions(+), 55 deletions(-) diff --git a/app/data/authors.yaml b/app/data/authors.yaml index 5e4f94b..a41d060 100644 --- a/app/data/authors.yaml +++ b/app/data/authors.yaml @@ -81,4 +81,4 @@ photo_url: https://danthe1st.github.io/img/Daniel.jpg website: https://danthe1st.github.io/ description: | - Daniel is a Java Developer from Austria who is also managing an online Java User Group. \ No newline at end of file + Daniel is a Java Developer from Austria who is also managing the Discord Java Community. \ No newline at end of file diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index a83fb18..baad48c 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -7,34 +7,46 @@ group: classes_objects layout: learn/tutorial-group.html subheader_select: tutorials main_css_id: learn +toc: +- What are enums? {intro} +- Accessing and comparing enums {accessing} +- Adding members to enums {members} +- Special methods {functionality} +- Using enums for singletons {singletons} +- Abstract methods in enums {abstract} description: "Working with enums." last_update: 2023-09-28 author: ["DanielSchmid"] --- +  ## What are enums? + Enums are classes where all instances are known to the compiler. They are used for creating types that can only have few possible values. Enums can be created similar to classes but use the `enum` keyword instead of `class`. -In the body, there is a list of instances of the enum named enum constants which are seperated by `,`. +In the body, there is a list of instances of the enum called enum constants which are seperated by `,`. No instances of the enum can be created outside of enum constants. ```java public enum DayOfWeek { - MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY + // enum constant are listed here: + MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY } ``` All enums implicitely extend [`java.lang.Enum`](javadoc:Enum) and cannot have any subclasses. +  ## Accessing and comparing enums + The values of an enum can be used as constants. In order to check whether two instances of an enum are the same, the `==` operator can be used. ```java DayOfWeek weekStart = DayOfWeek.MONDAY; if (weekStart == DayOfWeek.MONDAY) { - System.out.println("The week starts on Monday."); + System.out.println("The week starts on Monday."); } ``` @@ -44,23 +56,23 @@ It is also possible to use `switch` for performing actions depending on the valu DayOfWeek someDay = DayOfWeek.FRIDAY; switch (someDay) { - case MONDAY: - System.out.println("The week just started."); - break; - case TUESDAY: - case WEDNESDAY: - case THURSDAY: - System.out.println("We are somewhere in the middle of the week."); - break; - case FRIDAY: - System.out.println("The weekend is near."); - break; - case SATURDAY: - case SUNDAY: - System.out.println("Weekend"); - break; - default: - throw new AssertionError("Should not happen"); + case MONDAY: + System.out.println("The week just started."); + break; + case TUESDAY: + case WEDNESDAY: + case THURSDAY: + System.out.println("We are somewhere in the middle of the week."); + break; + case FRIDAY: + System.out.println("The weekend is near."); + break; + case SATURDAY: + case SUNDAY: + System.out.println("Weekend"); + break; + default: + throw new AssertionError("Should not happen"); } ``` @@ -70,15 +82,16 @@ the compiler can check whether all values of the enum are handled. DayOfWeek someDay = DayOfWeek.FRIDAY; String text = switch (someDay) { - case MONDAY -> "The week just started."; - case TUESDAY, WEDNESDAY, THURSDAY -> "We are somewhere in the middle of the week."; - case FRIDAY -> "The weekend is near."; - case SATURDAY, SUNDAY -> "Weekend"; + case MONDAY -> "The week just started."; + case TUESDAY, WEDNESDAY, THURSDAY -> "We are somewhere in the middle of the week."; + case FRIDAY -> "The weekend is near."; + case SATURDAY, SUNDAY -> "Weekend"; }; System.out.println(text); ``` +  ## Adding members to enums Just like classes, enums can have constructors, methods and fields. @@ -87,63 +100,69 @@ Arguments to the constructor are passed in parenthesis after the declaration of ```java public enum DayOfWeek { - MONDAY("MON"), TUESDAY("TUE"), WEDNESDAY("WED"), THURSDAY("THU"), FRIDAY("FRI"), SATURDAY("SAT"), SUNDAY("SUN"); - - private final String abbreviation; - - DayOfWeek(String abbreviation) { - this.abbreviation = abbreviation; - } - - public String getAbbreviation() { - return abbreviation; - } + MONDAY("MON"), TUESDAY("TUE"), WEDNESDAY("WED"), THURSDAY("THU"), FRIDAY("FRI"), SATURDAY("SAT"), SUNDAY("SUN"); + + private final String abbreviation; + + DayOfWeek(String abbreviation) { + this.abbreviation = abbreviation; + } + + public String getAbbreviation() { + return abbreviation; + } } ``` +  ## Special methods + All enums have a few methods that are added implicitely. For example, the method `name()` is present in all enum instances and can be used to get the name of the enum constant. Similarly, a method named `ordinal()` returns the position of the enum constant in the declaration. ```java -System.out.println(DayOfWeek.MONDAY.name());//MONDAY -System.out.println(DayOfWeek.MONDAY.ordinal());//0 because MONDAY is the first constant in the DayOfWeek enum +System.out.println(DayOfWeek.MONDAY.name()); // prints "MONDAY" +System.out.println(DayOfWeek.MONDAY.ordinal()); // prints "0" because MONDAY is the first constant in the DayOfWeek enum ``` Aside from instance methods, there are also static methods added to all enums. The method `values()` returns an array containing all instances of the enum and the method `valueOf(String)` can be used to get a specific instance by its name. ```java -DayOfWeek[] days = DayOfWeek.values();//all days of the week +DayOfWeek[] days = DayOfWeek.values(); // all days of the week DayOfWeek monday = DayOfWeek.valueOf("MONDAY"); ``` +  ## Using enums for singletons + Since enums can only have a specific number of instances, it is possible to create a singleton by creating an enum with only a single enum constant. ```java public enum SomeSingleton { - INSTANCE; - //fields, methods, etc. + INSTANCE; + //fields, methods, etc. } ``` +  ## Abstract methods in enums + Even though enums cannot be extended, they can still have `abstract` methods. In that case, an implementation must be present in each enum constant. ```java enum MyEnum { - A() { - @Override - void doSomething() { - System.out.println("a"); - } - }, - B() { - @Override - void doSomething() { - System.out.println("b"); - } - }; - - abstract void doSomething(); + A() { + @Override + void doSomething() { + System.out.println("a"); + } + }, + B() { + @Override + void doSomething() { + System.out.println("b"); + } + }; + + abstract void doSomething(); } ``` \ No newline at end of file From ec061ec0ada5dfd6239b9093c8036fe6fcef88f6 Mon Sep 17 00:00:00 2001 From: danthe1st Date: Fri, 29 Sep 2023 19:40:52 +0200 Subject: [PATCH 07/12] implement requested changes --- .../04_classes_objects/01_enums.md | 71 ++++++++++++++----- 1 file changed, 52 insertions(+), 19 deletions(-) diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index baad48c..b45dd1a 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -9,11 +9,12 @@ subheader_select: tutorials main_css_id: learn toc: - What are enums? {intro} -- Accessing and comparing enums {accessing} +- Accessing, evaluating, and comparing enums {accessing} - Adding members to enums {members} - Special methods {functionality} -- Using enums for singletons {singletons} +- Using enums as singletons {singletons} - Abstract methods in enums {abstract} +- Conclusion {conclusion} description: "Working with enums." last_update: 2023-09-28 author: ["DanielSchmid"] @@ -35,10 +36,10 @@ public enum DayOfWeek { } ``` -All enums implicitely extend [`java.lang.Enum`](javadoc:Enum) and cannot have any subclasses. +All enums implicitly extend [`java.lang.Enum`](javadoc:Enum) and cannot have any subclasses.   -## Accessing and comparing enums +## Accessing, evaluating, and comparing enums The values of an enum can be used as constants. In order to check whether two instances of an enum are the same, the `==` operator can be used. @@ -56,28 +57,22 @@ It is also possible to use `switch` for performing actions depending on the valu DayOfWeek someDay = DayOfWeek.FRIDAY; switch (someDay) { - case MONDAY: + case MONDAY -> System.out.println("The week just started."); - break; - case TUESDAY: - case WEDNESDAY: - case THURSDAY: + case TUESDAY, WEDNESDAY, THURSDAY -> System.out.println("We are somewhere in the middle of the week."); - break; - case FRIDAY: + case FRIDAY -> System.out.println("The weekend is near."); - break; - case SATURDAY: - case SUNDAY: + case SATURDAY, SUNDAY -> System.out.println("Weekend"); - break; - default: + default -> throw new AssertionError("Should not happen"); } ``` With [Switch Expressions](id:lang.classes-objects.switch-expression), the compiler can check whether all values of the enum are handled. +If any possible value is missing in a switch expression, there will be a compiler error. ```java DayOfWeek someDay = DayOfWeek.FRIDAY; @@ -117,7 +112,7 @@ public enum DayOfWeek {   ## Special methods -All enums have a few methods that are added implicitely. +All enums have a few methods that are added implicitly. For example, the method `name()` is present in all enum instances and can be used to get the name of the enum constant. Similarly, a method named `ordinal()` returns the position of the enum constant in the declaration. @@ -133,8 +128,32 @@ DayOfWeek[] days = DayOfWeek.values(); // all days of the week DayOfWeek monday = DayOfWeek.valueOf("MONDAY"); ``` +Furthermore, enums implement the interface [`Comparable`](javadoc:Comparable). +By default, enums are ordered according to their ordinal number +i.e. in the order of occurrence of the enum constant. +This allows for comparing instances of enums as well as sorting or searching. + +```java +public void compareDayOfWeek(DayOfWeek dayOfWeek){ + int comparison = dayOfWeek.compareTo(DayOfWeek.WEDNESDAY); + if ( comparison < 0) { + System.out.println("It's before the middle of the work week."); + } else if(comparison > 0){ + System.out.println("It's after the middle of the work week."); + } else { + System.out.println("It's the middle of the work week."); + } +} +``` + +```java +List days = new ArrayList<>(List.of(DayOfWeek.FRIDAY, DayOfWeek.TUESDAY, DayOfWeek.SATURDAY)); +Collections.sort(days); +``` + +   -## Using enums for singletons +## Using enums as singletons Since enums can only have a specific number of instances, it is possible to create a singleton by creating an enum with only a single enum constant. ```java @@ -165,4 +184,18 @@ enum MyEnum { abstract void doSomething(); } -``` \ No newline at end of file +``` + +  +## Conclusion + +All in all, enums provide a simple and safe way of limiting the instances of a type +while preserving most of the flexibilities of classes. + +However, care should be taken when using enums where the number (or names) of instances is subject to change. +Whenever enum constants are changed, there may be compilation errors, runtime errors or other inconsistencies +due to other code expecting the original version of the enum. +This is especially important in cases where the enum is also used by other people's code. + +Furthermore, it might be worth considering to use other options +in case of many instances since listing many instances at a single location in code can be inflexible. \ No newline at end of file From 16f258e7a87377702a5d59443a757dc1052486a0 Mon Sep 17 00:00:00 2001 From: danthe1st Date: Fri, 29 Sep 2023 21:27:28 +0200 Subject: [PATCH 08/12] rewrite conclusion --- .../04_classes_objects/01_enums.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index b45dd1a..640737f 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -16,7 +16,7 @@ toc: - Abstract methods in enums {abstract} - Conclusion {conclusion} description: "Working with enums." -last_update: 2023-09-28 +last_update: 2023-09-29 author: ["DanielSchmid"] ---   @@ -189,13 +189,18 @@ enum MyEnum {   ## Conclusion -All in all, enums provide a simple and safe way of limiting the instances of a type -while preserving most of the flexibilities of classes. +All in all, enums provide a simple and safe way of representing a fixed set of constants +while keeping most of the flexibilities of classes. However, care should be taken when using enums where the number (or names) of instances is subject to change. -Whenever enum constants are changed, there may be compilation errors, runtime errors or other inconsistencies -due to other code expecting the original version of the enum. +Whenever enum constants are changed, other code expecting the old version of the enum might not work as expected. +This may manifest in compilation errors (e.g. when referencing a removed enum constant), +runtime errors (e.g. if there is a `default` case even though the new enum constant should be handled separately) +or other inconsistencies (e.g. if the value of the enum was saved to a file which is then read and expecting that value to still exist). +When changing enum constants, it is recommended to review all code using the enum. This is especially important in cases where the enum is also used by other people's code. Furthermore, it might be worth considering to use other options -in case of many instances since listing many instances at a single location in code can be inflexible. \ No newline at end of file +in case of many instances since listing a lot of instances at a single location in code can be inflexible. +For example, it may be better to use a configuration file for listing all instances +and reading these configuration files in the program in cases like this. \ No newline at end of file From 5b88e1c809fd34d1eb71ce25b0b2140e13ac2809 Mon Sep 17 00:00:00 2001 From: Chad Arimura Date: Fri, 29 Sep 2023 13:08:47 -0700 Subject: [PATCH 09/12] classes-and-objects section --- .../00_classes-and-objects.md | 17 +++++++++++++++++ .../04_classes_objects/01_enums.md | 4 ++-- 2 files changed, 19 insertions(+), 2 deletions(-) create mode 100644 app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/00_classes-and-objects.md diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/00_classes-and-objects.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/00_classes-and-objects.md new file mode 100644 index 0000000..38f655b --- /dev/null +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/00_classes-and-objects.md @@ -0,0 +1,17 @@ +--- +id: lang.classes +title: "Classes and Objects" +slug: learn/classes-objects +slug_history: +- classes-objects +type: tutorial +category: language +category_order: 4 +group: classes-and-objects +layout: learn/tutorial-group-top.html +subheader_select: tutorials +main_css_id: learn +description: "Defining your own classes, declaring member variables, methods, and constructors." +--- + +This part of the tutorial covers the basics of class definition, object creation, nesting classes, enumerations, declaring member variables, methods, and constructors. \ No newline at end of file diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index 640737f..3a16729 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -1,9 +1,9 @@ --- -id: lang.classes-objects.enums +id: lang.classes.enums title: Enums slug: learn/classes-objects/enums type: tutorial-group -group: classes_objects +group: classes-and-objects layout: learn/tutorial-group.html subheader_select: tutorials main_css_id: learn From 99878195ea6105b1d782c6ca6d8501781e537342 Mon Sep 17 00:00:00 2001 From: Chad Arimura Date: Fri, 29 Sep 2023 13:34:30 -0700 Subject: [PATCH 10/12] how about this --- .../04_classes_objects/01_enums.md | 23 +++++++++++++------ 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index 3a16729..9007550 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -14,6 +14,7 @@ toc: - Special methods {functionality} - Using enums as singletons {singletons} - Abstract methods in enums {abstract} +- Precautions {precautions} - Conclusion {conclusion} description: "Working with enums." last_update: 2023-09-29 @@ -73,6 +74,9 @@ switch (someDay) { With [Switch Expressions](id:lang.classes-objects.switch-expression), the compiler can check whether all values of the enum are handled. If any possible value is missing in a switch expression, there will be a compiler error. +This is referred to as Exhaustiveness and can also be achieved with regular classes +through [Sealed Classes](https://openjdk.org/jeps/409). + ```java DayOfWeek someDay = DayOfWeek.FRIDAY; @@ -186,21 +190,26 @@ enum MyEnum { } ``` -  -## Conclusion +  +## Precautions -All in all, enums provide a simple and safe way of representing a fixed set of constants -while keeping most of the flexibilities of classes. - -However, care should be taken when using enums where the number (or names) of instances is subject to change. +Care should be taken when using enums where the number (or names) of instances is subject to change. Whenever enum constants are changed, other code expecting the old version of the enum might not work as expected. This may manifest in compilation errors (e.g. when referencing a removed enum constant), runtime errors (e.g. if there is a `default` case even though the new enum constant should be handled separately) or other inconsistencies (e.g. if the value of the enum was saved to a file which is then read and expecting that value to still exist). + When changing enum constants, it is recommended to review all code using the enum. This is especially important in cases where the enum is also used by other people's code. Furthermore, it might be worth considering to use other options in case of many instances since listing a lot of instances at a single location in code can be inflexible. For example, it may be better to use a configuration file for listing all instances -and reading these configuration files in the program in cases like this. \ No newline at end of file +and reading these configuration files in the program in cases like this. + +  +## Conclusion + +Enums provide a simple and safe way of representing a fixed set of constants while keeping most of the flexibilities of classes. They are another special type of class that can be used to write code that is elegant, readable, and maintainable, and work well with other newer modern features like [Switch Expressions](id:lang.classes-objects.switch-expression). + +To learn more, visit the javadoc [`java.lang.Enum`](javadoc:Enum). \ No newline at end of file From 269107432e455b69402007d65967ba13f416fbb0 Mon Sep 17 00:00:00 2001 From: danthe1st Date: Sat, 30 Sep 2023 15:12:29 +0200 Subject: [PATCH 11/12] small rewrite of conclusion --- .../04_classes_objects/01_enums.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index 9007550..09bc2d3 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -210,6 +210,6 @@ and reading these configuration files in the program in cases like this.   ## Conclusion -Enums provide a simple and safe way of representing a fixed set of constants while keeping most of the flexibilities of classes. They are another special type of class that can be used to write code that is elegant, readable, and maintainable, and work well with other newer modern features like [Switch Expressions](id:lang.classes-objects.switch-expression). +Enums provide a simple and safe way of representing a fixed set of constants while keeping most of the flexibilities of classes. They are a special type of class that can be used to write code that is elegant, readable, and maintainable, and work well with other newer modern features like [Switch Expressions](id:lang.classes-objects.switch-expression). -To learn more, visit the javadoc [`java.lang.Enum`](javadoc:Enum). \ No newline at end of file +To learn more, visit the javadoc of [`java.lang.Enum`](javadoc:Enum). \ No newline at end of file From 76b4fcda59c094c73c158b3abf27e074beeec648 Mon Sep 17 00:00:00 2001 From: Chad Arimura Date: Mon, 2 Oct 2023 08:35:59 -0700 Subject: [PATCH 12/12] adding reference to records and slight conclusion rewrite --- .../04_classes_objects/01_enums.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md index 09bc2d3..651a2ea 100644 --- a/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -210,6 +210,6 @@ and reading these configuration files in the program in cases like this.   ## Conclusion -Enums provide a simple and safe way of representing a fixed set of constants while keeping most of the flexibilities of classes. They are a special type of class that can be used to write code that is elegant, readable, and maintainable, and work well with other newer modern features like [Switch Expressions](id:lang.classes-objects.switch-expression). +Enums provide a simple and safe way of representing a fixed set of constants while keeping most of the flexibilities of classes. They are a special type of class that can be used to write code that is elegant, readable, and maintainable, and work well with other newer modern features like [Switch Expressions](id:lang.classes-objects.switch-expression). Another special class is the Record class introduced in Java 19. Visit our [Records tutorial](id:lang.records) to learn more. -To learn more, visit the javadoc of [`java.lang.Enum`](javadoc:Enum). \ No newline at end of file +To learn more about enums, visit the [`java.lang.Enum`](javadoc:Enum) javadoc. \ No newline at end of file