docs: add README

Reviewed-on: AdvancedProgramming1404/WS-05-exceptions-and-file-handling#1

.gitignore

@@ -36,4 +36,6 @@ build/
 .vscode/
 
 ### Mac OS ###
-.DS_Store
+.DS_Store
+
+examples*.txt

README.md

@@ -0,0 +1,82 @@
+# Java Exceptions and File Handling Workshop
+
+## Introduction
+This workshop is designed to help students become familiar with **exception handling** and **basic file operations in Java**.  
+It provides small demo programs and guided exercises that demonstrate how common runtime exceptions occur and how they should be handled in real applications.
+
+The workshop also includes a **file handling guide**, showing how Java can interact with files on the system and how to work with JSON data.
+
+
+---
+
+## Workshop Structure
+
+The workshop consists of two main sections:
+
+### 1. Exception Handling
+This section contains demonstration code that intentionally produces different types of runtime exceptions. Students are expected to analyze the code and apply proper **exception handling techniques**.
+
+The examples include scenarios such as:
+
+- `NullPointerException`
+- `IllegalArgumentException`
+- `ArithmeticException`
+- `NumberFormatException`
+- `IllegalStateException`
+
+### 2. File Handling Guide
+The second section of the workshop introduces common **file system operations in Java**.  
+Unlike the exception section, this part is mainly **instructional** and does not contain required exercises.
+
+Topics covered include:
+
+- **AddressingModes**  
+  Understanding relative and absolute file paths.
+
+- **CreatingFiles**  
+  How to create files programmatically using Java.
+
+- **DeletingFiles**  
+  Removing files from the file system safely.
+
+- **ReadingFiles**  
+  Reading data from text files using Java IO classes.
+
+- **WritingFiles**  
+  Writing content to files.
+
+- **ParsingJson**  
+  Basic techniques for working with JSON files in Java.
+
+These examples are intended to serve as **reference material** for future projects.
+
+---
+
+## Tasks
+
+Students may optionally complete the following tasks:
+
+1. Review the provided exception demo code.
+2. Identify where runtime exceptions occur.
+3. Modify the `FileService` methods by:
+    - Uncommenting the provided code
+    - Adding appropriate exception handling
+4. Test the program to ensure that errors are handled gracefully.
+
+### Important Notice
+Completing and submitting this workshop is **NOT mandatory** and **does not carry any points or grading**.
+
+It is provided purely as a **learning exercise** to help students better understand Java exception handling and file operations.
+
+---
+
+## Learning Goals
+
+By working through this workshop, students should be able to:
+
+- Understand common Java runtime exceptions
+- Apply `try-catch` blocks correctly
+- Handle file-related exceptions
+- Perform basic file operations in Java
+- Understand how Java programs interact with JSON files
+```

data.json

@@ -0,0 +1,89 @@
+{
+  "genres": [
+    {
+      "id": 1,
+      "name": "Crime"
+    },
+    {
+      "id": 2,
+      "name": "Drama"
+    },
+    {
+      "id": 3,
+      "name": "Action"
+    },
+    {
+      "id": 4,
+      "name": "Biography"
+    },
+    {
+      "id": 5,
+      "name": "History"
+    },
+    {
+      "id": 6,
+      "name": "Adventure"
+    },
+    {
+      "id": 7,
+      "name": "Fantasy"
+    },
+    {
+      "id": 8,
+      "name": "Western"
+    },
+    {
+      "id": 9,
+      "name": "Comedy"
+    },
+    {
+      "id": 10,
+      "name": "Sci-Fi"
+    },
+    {
+      "id": 11,
+      "name": "Mystery"
+    },
+    {
+      "id": 12,
+      "name": "Thriller"
+    },
+    {
+      "id": 13,
+      "name": "Family"
+    },
+    {
+      "id": 14,
+      "name": "War"
+    },
+    {
+      "id": 15,
+      "name": "Animation"
+    },
+    {
+      "id": 16,
+      "name": "Romance"
+    },
+    {
+      "id": 17,
+      "name": "Horror"
+    },
+    {
+      "id": 18,
+      "name": "Music"
+    },
+    {
+      "id": 19,
+      "name": "Film-Noir"
+    },
+    {
+      "id": 20,
+      "name": "Musical"
+    },
+    {
+      "id": 21,
+      "name": "Sport"
+    }
+  ],
+  "total": 21
+}

pom.xml

@@ -14,4 +14,12 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     </properties>
 
+    <dependencies>
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>2.11.0</version>
+        </dependency>
+    </dependencies>
+
 </project>

quotes.txt

@@ -0,0 +1,3 @@
+I'm not superstitious, but I am a little stitious.
+I am running away from my responsibilities. And it feels good.
+I DECLARE BANKRUPTCY!

src/main/java/org/Exceptions/FileService.java

@@ -1,9 +1,5 @@
-package org.exceptions;
+package org.Exceptions;
 
-import java.io.BufferedReader;
-import java.io.BufferedWriter;
-import java.io.FileReader;
-import java.io.FileWriter;
 import java.text.SimpleDateFormat;
 import java.util.Date;
 import java.util.Scanner;
@@ -49,18 +45,26 @@ public class FileService {
 
 
     public static String writeFile(UserEntity user) {
+        //TODO: Uncomment the lines below.
+        //TODO: Use your knowledge of exception handling to make the code work as expected
 
+        /* Uncomment this section
+        //TODO: handle the exception
         FileWriter fw = new FileWriter("userInformation.txt", true);
         BufferedWriter bw = new BufferedWriter(fw);
 
         bw.write(user.toString());
         bw.close();
+         */
         return "user information written to file";
     }
 
 
     public static void readFile() {
+        //TODO: Uncomment the lines below.
+        //TODO: Use your knowledge of exception handling to make the code work as expected
 
+        /* Uncomment this section
         FileReader file = new FileReader("userInformation.txt");
 
         BufferedReader fileInput = new BufferedReader(file);
@@ -69,6 +73,7 @@ public class FileService {
             System.out.println(fileInput.readLine());
 
         fileInput.close();
+         */
     }
 
 
@@ -77,8 +82,9 @@ public class FileService {
 
         Date dob = null;
 
-        dob = formatter.parse(date);
+        //TODO: Uncomment this line.
-
+        //TODO: Use your knowledge of exception handling to make the code work as expected
+        //dob = formatter.parse(date);
 
         return dob;
     }

src/main/java/org/Exceptions/Main.java

@@ -1,4 +1,4 @@
-package org;
+package org.Exceptions;
 
 public class Main {
     public static void main(String[] args) {

src/main/java/org/Exceptions/RuntimeExceptionDemo.java

@@ -1,4 +1,4 @@
-package org.exceptions;
+package org.Exceptions;
 
 import java.util.regex.Pattern;
 

src/main/java/org/Exceptions/UserEntity.java

@@ -1,4 +1,4 @@
-package org.exceptions;
+package org.Exceptions;
 
 import java.util.Date;
 

src/main/java/org/FileExamples/AddresesingModes/FileAddressing.java

@@ -0,0 +1,28 @@
+package org.FileExamples.AddresesingModes;
+
+import java.io.InputStream;
+import java.nio.file.Path;
+import java.util.Scanner;
+
+public class FileAddressing {
+    static void main() {
+        //relative
+        Path relativePath = Path.of("data.txt");
+        //absolute
+        Path absolutePath = Path.of("C:\\Users\\Lenovo\\data.txt");
+
+
+        //using class path / resources
+        InputStream input = FileAddressing.class
+                .getClassLoader()
+                .getResourceAsStream("data.txt");
+
+        Scanner scanner = new Scanner(input);
+
+        while (scanner.hasNextLine()) {
+            System.out.println(scanner.nextLine());
+        }
+
+        scanner.close();
+    }
+}

src/main/java/org/FileExamples/CreatingFiles/CreateFileExample01.java

@@ -0,0 +1,25 @@
+package org.FileExamples.CreatingFiles;
+
+import java.io.File;
+import java.io.IOException;
+
+public class CreateFileExample01 {
+    static void main() {
+        File file = new File("texts/examples.txt");
+        try
+        {
+            if(file.createNewFile())
+            {
+                System.out.println("File created");
+            }
+            else
+            {
+                System.out.println("File already exists");
+            }
+        }
+        catch(IOException e)
+        {
+            System.err.println(e.getMessage());
+        }
+    }
+}

src/main/java/org/FileExamples/CreatingFiles/CreateFileExample02.java

@@ -0,0 +1,16 @@
+package org.FileExamples.CreatingFiles;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+public class CreateFileExample02 {
+    public static void main(String[] args)  {
+        Path path = Path.of("exmaples.txt");
+        try {
+            Files.createFile(path);
+        } catch (IOException e) {
+            System.err.println(e.getMessage());
+        }
+    }
+}

src/main/java/org/FileExamples/DeletingFiles/DeleteFileExample01.java

@@ -0,0 +1,15 @@
+package org.FileExamples.DeletingFiles;
+
+import java.io.File;
+
+public class DeleteFileExample01 {
+    static void main() {
+        File file = new File("example.txt");
+
+        if (file.delete()) {
+            System.out.println("Deleted file: " + file.getName());
+        } else {
+            System.out.println("Failed to delete the file.");
+        }
+    }
+}

src/main/java/org/FileExamples/DeletingFiles/DeleteFileExample02.java

@@ -0,0 +1,20 @@
+package org.FileExamples.DeletingFiles;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+public class DeleteFileExample02 {
+    static void main() {
+        try
+        {
+            Path path = Path.of("example.txt");
+            Files.deleteIfExists(path);
+            System.out.println("File deleted if it existed.");
+        }
+        catch (IOException e)
+        {
+            throw new RuntimeException(e);
+        }
+    }
+}

src/main/java/org/FileExamples/ParsingJson/Genre.java

@@ -0,0 +1,37 @@
+package org.FileExamples.ParsingJson;
+
+
+public class Genre
+{
+    private Long id;
+    private String name;
+
+    public Genre(Long id, String name) {
+        this.id = id;
+        this.name = name;
+    }
+
+    public Genre() {
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public void setId(Long id) {
+        this.id = id;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    @Override
+    public String toString() {
+        return id + ". " + name;
+    }
+}

src/main/java/org/FileExamples/ParsingJson/ParsingJsonExample01.java

@@ -0,0 +1,37 @@
+package org.FileExamples.ParsingJson;
+
+import com.google.gson.*;
+import com.google.gson.reflect.TypeToken;
+
+import java.io.IOException;
+import java.lang.reflect.Type;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.List;
+
+public class ParsingJsonExample01 {
+    static void main() {
+
+        try {
+            Path path = Path.of("data.json");
+            String texts = new String(Files.readAllBytes(path));
+
+            JsonObject rootObject = JsonParser.parseString(texts).getAsJsonObject();
+            JsonArray genresArray = rootObject.getAsJsonArray("genres");
+
+            Gson gson = new Gson();
+            Type type = new TypeToken<List<Genre>>(){}.getType();
+
+            List<Genre> genres = gson.fromJson(genresArray, type);
+
+            for(Genre genre: genres)
+            {
+                System.out.println(genre.getId() + ". "  + genre.getName());
+            }
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+    }
+}

src/main/java/org/FileExamples/ReadingFiles/ReadFileExample01.java

@@ -0,0 +1,22 @@
+package org.FileExamples.ReadingFiles;
+
+import java.io.File;
+import java.io.FileNotFoundException;
+import java.util.Scanner;
+
+public class ReadFileExample01 {
+    static void main() {
+        File file = new File("quotes.txt");
+        try {
+            Scanner reader = new Scanner(file);
+
+            while(reader.hasNext())
+            {
+                String line = reader.nextLine();
+                System.out.println(line);
+            }
+        } catch (FileNotFoundException e) {
+
+        }
+    }
+}

src/main/java/org/FileExamples/ReadingFiles/ReadFileExample02.java

@@ -0,0 +1,22 @@
+package org.FileExamples.ReadingFiles;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+public class ReadFileExample02 {
+    static void main() {
+        Path path = Path.of("quotes.txt");
+        try {
+            List<String> lines = Files.readAllLines(path);
+
+            for(String line : lines)
+            {
+                System.out.println(line);
+            }
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+    }
+}

src/main/java/org/FileExamples/WritingFiles/WriteFileExample01.java

@@ -0,0 +1,37 @@
+package org.FileExamples.WritingFiles;
+
+import java.io.FileWriter;
+import java.io.IOException;
+
+public class WriteFileExample01 {
+    static void main() {
+
+        try
+        {
+            FileWriter fileWriter = new FileWriter("examples2.txt");
+            fileWriter.write("I'm not superstitious, but I am a little stitious.\n");
+            fileWriter.write("I am running away from my responsibilities. And it feels good.\n");
+
+            fileWriter.close();
+            System.out.println("Done.");
+        }
+        catch (IOException e)
+        {
+            System.err.println(e.getMessage());
+        }
+
+        try
+        {
+            FileWriter fileWriter = new FileWriter("examples2.txt", true);
+            fileWriter.write("I DECLARE BANKRUPTCY!");
+
+            fileWriter.close();
+            System.out.println("Done.");
+        }
+        catch (IOException e)
+        {
+            System.err.println(e.getMessage());
+        }
+
+    }
+}

src/main/java/org/FileExamples/WritingFiles/WriteFileExample02.java

@@ -0,0 +1,26 @@
+package org.FileExamples.WritingFiles;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.OpenOption;
+import java.nio.file.Path;
+import java.nio.file.StandardOpenOption;
+import java.util.ArrayList;
+import java.util.List;
+
+public class WriteFileExample02 {
+    static void main() {
+        List<String> lines = List.of(
+          "Line 1",
+          "Line 2"
+        );
+
+        Path path = Path.of("examples2.txt");
+        try {
+            Files.write(path, lines);
+        } catch (IOException e) {
+            System.err.println(e.getMessage());
+        }
+    }
+}

src/main/resources/data.txt

@@ -0,0 +1 @@
+this is a data file.