diff --git a/app/data/authors.yaml b/app/data/authors.yaml index 334d39a..a41d060 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 the Discord Java Community. \ No newline at end of file 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/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 new file mode 100644 index 0000000..651a2ea --- /dev/null +++ b/app/pages/learn/01_tutorial/03_getting-to-know-the-language/04_classes_objects/01_enums.md @@ -0,0 +1,215 @@ +--- +id: lang.classes.enums +title: Enums +slug: learn/classes-objects/enums +type: tutorial-group +group: classes-and-objects +layout: learn/tutorial-group.html +subheader_select: tutorials +main_css_id: learn +toc: +- What are enums? {intro} +- Accessing, evaluating, and comparing enums {accessing} +- Adding members to enums {members} +- 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 +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 called enum constants which are seperated by `,`. +No instances of the enum can be created outside of enum constants. + +```java +public enum DayOfWeek { + // enum constant are listed here: + MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY +} +``` + +All enums implicitly extend [`java.lang.Enum`](javadoc:Enum) and cannot have any subclasses. + +  +## 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. +```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."); + case TUESDAY, WEDNESDAY, THURSDAY -> + System.out.println("We are somewhere in the middle of the week."); + case FRIDAY -> + System.out.println("The weekend is near."); + case SATURDAY, SUNDAY -> + System.out.println("Weekend"); + 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. +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; + +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 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. +```java +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 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 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 +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(); +} +``` + +  +## Precautions + +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. + +  +## 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). Another special class is the Record class introduced in Java 19. Visit our [Records tutorial](id:lang.records) to learn more. + +To learn more about enums, visit the [`java.lang.Enum`](javadoc:Enum) javadoc. \ No newline at end of file