README.md 5.73 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
Homework assignment no. 3, CSV
====================================

**Publication date:**  May 22, 2021

**Submission deadline:** June 6, 2021

General information
-------------------
In this assignment you will create a CSV parsing library.
jcechace's avatar
jcechace committed
11
Unlike many advanced libraries which allow parsing and mapping CSV data directly to Java objects (POJOs),
12
our library will rely on collections, and the only supported data type will be ``String``.
jcechace's avatar
jcechace committed
13
Even so, this will be a useful library as data conversion can be easily deferred and sometimes 
14
15
16
17
18
19
20
21
22
all you need is a simple dynamic solution. 

Given a CSV data set
```csv
atomicNumber, symbol, name, standardState, groupBlock, yearDiscovered
1, H , Hydrogen,gas,nonmetal,1766
2, He , Helium,gas,noble gas,1868
```

jcechace's avatar
jcechace committed
23
Our library will support two types of parsing depending on whether we want to use the first line as a header.
24
25

For plain (headerless) data sets, each line will be converted into ``List<String>`` and thus the entire data set
jcechace's avatar
jcechace committed
26
can be converted into ``List<List<String>``. With the example above, our parser will yield
27
28
29
30
31
32
33
34
```
[
    [atomicNumber, symbol, name, standardState, groupBlock, yearDiscovered],
    [1, H , Hydrogen,gas,nonmetal,1766],
    [2, He , Helium,gas,noble gas,1868],
]
```

jcechace's avatar
jcechace committed
35
36
37
For data sets with a header, each line will be converted into ``Map<String, String>`` with 
column names used as keys. Thus the entire data set can be converted into ``List<Map<String, String>>``.
With the example above, our parser will yield
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
```
[
    {
        atomicNumber: 1, 
        symbol: H, 
        name: Hydrogen, 
        standardState: gas, 
        groupBlock: nonmetal, 
        yearDiscovered: 1766
    }.
    {
        atomicNumber: 2,
        symbol: He, 
        name: Helium, 
        standardState: gas, 
        groupBlock: noble gas,
        yearDiscovered: 1868
    }
]
```

### Evaluation
jcechace's avatar
jcechace committed
60
Beside functional correctness, this assignment is focused on object-oriented design and understanding how IO works in Java.
61
This means that the way you structure your program will be an important part of its evaluation.
jcechace's avatar
jcechace committed
62
On the other hand, the given set of tests is not trying to provide an elaborate test coverage and **incorrect behaviour in corner-cases should not have a large impact on the evaluation**.
63
64
65
66
67

*Note that all this is at your seminar teacher's discretion.*

The maximum number of points for this assignment is **15**.

jcechace's avatar
jcechace committed
68
- **11 points** for passing the tests (attached tests do not guarantee 100% correctness).
69
70
71
72
73
- **4 points** for correct and clean implementation (evaluated by your class teacher).

### Preconditions
To successfully implement this assignment you need to know the following

jcechace's avatar
jcechace committed
74
1. Understanding of OOP in Java
75
2. Working with collections
jcechace's avatar
jcechace committed
76
77
3. Basic knowledge of generic types
4. Understanding of IO in Java (packages ``java.io`` and ``java.nio``)
78
79

### Project structure
jcechace's avatar
jcechace committed
80
The structure of the project provided as a base for your implementation should meet the following criteria.
81

jcechace's avatar
jcechace committed
82
1. Package ```cz.muni.fi.pb162.hw03.csv``` contains classes and interfaces provided as a part of the assignment.
83
84
85
86
87
  - **Do not modify or add any classes or subpackages into this package.**
2. Package  ```cz.muni.fi.pb162.hw03.csv.impl``` should contain your implementation.
  - **Anything outside this package will be ignored during evaluation.**

### Names in this document
jcechace's avatar
jcechace committed
88
Unless fully classified name is provided, all class names are relative to the package ```cz.muni.fi.pb162.hw03.csv``` or ```cz.muni.fi.pb162.hw03.csv.impl``` for classes implemented as a part of your solution.
89
90
91
92
93
94
95
96
97


### Compiling the project
The project can be compiled and packaged in the same way you already know

```bash
$ mvn clean install
```

jcechace's avatar
jcechace committed
98
99
The only difference is that unlike with seminar project, this time checks for missing documentation and style violation will produce an error.
You can disable this behavior by running this command temporarily.
100
101
102
103
104

```bash
$ mvn clean install -Dcheckstyle.fail=false
```

jcechace's avatar
jcechace committed
105
You can consult your seminar teacher on setting the ```checkstyle.fail``` property in your IDE (or just google it).
106
107

### Submitting the assignment
jcechace's avatar
jcechace committed
108
The procedure to submit your solution may differ based on your seminar group. However, in general, it should be OK to submit ```target/homework03-2021-1.0-SNAPSHOT-sources.jar``` to the homework vault.
109
110

## Implementation notes
jcechace's avatar
jcechace committed
111
Generally speaking, there are no mandatory requirements on the structure of your code other than what is enforced by provided interfaces
112

jcechace's avatar
jcechace committed
113
114
* Provided tests should give you a good idea about the intended use of this library
* Think about how IO streams are structured in Java, ``CsvReader`` is essentially another layer.
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
* Read JavaDoc carefully

Example library usage 

```java
public static void main(String[] args) throws IOException {
    Path path = Paths.get("test.csv");
    CsvParser parser = CsvToolkit.parser();

    // Direct usage
    List<List<String>> data = parser.readAll(path);
    List<Map<String, String>> dataHeaded = parser.readAllWithHeader(path);

    System.out.println("Direct (eager)");
    System.out.println(data);
    System.out.println(dataHeaded);
    System.out.println();

    // Reader Usage: Consumer
    System.out.println("Reader: Consumer");
    try (var reader = parser.open(path)) {
        reader.forEach(System.out::println);
    }

    try (var reader = parser.openWithHeader(path)) {
        reader.forEach(System.out::println);
    }
    System.out.println();

    // Reader Usage: iterative
    System.out.println("Reader: Iterative");
    try (var reader = parser.open(path)) {
        List<String> line;
        while ((line = reader.read()) != null) {
            System.out.println(line);
        }
    }

    try (var reader = parser.openWithHeader(path)) {
        Map<String, String> line;
        while ((line = reader.read()) != null) {
            System.out.println(line);
        }
    }
}
```