Java ACDP Tutorial

Querying

Structural changes to the database are not an issue in this chapter. Structural changes include removing a table from the database or inserting a new column into an existing table. How to structurally change the database is shown in Section Refactoring of Chapter Maintenance.

The remaining sections of this page are

Populating the Database

Which of EduPL, EduDB, and Database to use?

   Path path = Paths.get("dbDir/layout");
   
   // Open database by creating EduPL instance.
   try (EduPL pl = new EduPL(path, -1, false, 0)) {
      // do something with pl
   }
   
   // Open database as strongly typed database.
   try (EduDB db = new EduDB(path, -1, false, 0)) {
      // do something with db
   }
   
   // Open database as weakly typed database.
   try (Database db = Database.open(path, -1, false, null)) {
      // do something with db
   }

The database should only be opened as a weakly typed database if the use case can neither be implemented with the persistence layer nor by opening the database as a strongly typed database or if the use case is not domain-specific. (For example, a non-domain-specific use case is get the names of the tables of the database.)

EduPL

   // pl instance of EduPL
   Student student = pl.getStudent(74);
   System.out.println(student.getName() + "  " +
                      student.getContact().getEmail());

EduDB

   // EduDB is open
   Row row = STUDENT_TABLE.get(
                         STUDENT_TABLE.indexGet(74),
                                     NAME, CONTACT);
   String email = CONTACT_TABLE.getValue(
                           row.get(CONTACT), EMAIL);
   System.out.println(row.get(NAME) + "  " + email);

- Less convenient
- No enforcement of domain-specific constraints implemented in the persistence layer (not a problem in this example)
+ Built-in index can be used
+ Easy and strongly typed access to tables and columns

Database

   // db instance of Database
   Table studentTable = db.getTable("Student");
   Column<?> studentNumberColumn = studentTable.
                                   getColumn("Student Number");
   Column<?> nameColumn = studentTable.getColumn("Name");
   Column<?> contactColumn = studentTable.getColumn("Contact");
			
   Table contactTable = db.getTable("Contact");
   Column<?> emailColumn = contactTable.getColumn("Email");
			
   Row studentRow = studentTable.rows(studentNumberColumn,
                                     nameColumn, contactColumn).
        filter(row -> (int) row.get(studentNumberColumn) == 74).
        findAny().get();
			
   Row contactRow = contactTable.get((Ref) studentRow.get(
                                  contactColumn), emailColumn);
   System.out.println(studentRow.get(nameColumn) + "  " +
                                  contactRow.get(emailColumn));

Ad-hoc Queries

In the following, we define a query on our sample database to be an ad-hoc query if it cannot be done with the persistence layer. Therefore, we open the sample database as a strongly typed EduDB database as was shown in the previous section.

   for (Row row : COURSE_TABLE) {
      System.out.println(row.get(NAME));
   }

   for (Iterator<Row> it = COURSE_TABLE.iterator(NAME);
                                        it.hasNext();) {
      System.out.println(it.next().get(NAME));
   }

   COURSE_TABLE.rows(NAME).forEach(row ->
                     System.out.println(row.get(NAME)));

   List<String> result = STUDENT_TABLE.rows(NAME, COURSES).
          filter(r -> Arrays.stream(r.get(COURSES)).
               filter(ref -> COURSE_TABLE.getValue(ref,
                     CourseTable.ID).equals("CSHARP")).
                     findAny().isPresent()).
          map(r -> r.get(NAME)).collect(toList());

   Map<String, List<String>> result = new HashMap<>();
   for (Row tRow : TEACHER_TABLE) {
      List<Ref> l1 = Arrays.asList(tRow.get(
                              TeacherTable.COURSES));
      List<String> sList = new ArrayList<>();
      for (Row sRow : STUDENT_TABLE) {
         List<Ref> l2 = Arrays.asList(sRow.get(
                              StudentTable.COURSES));
         if (l1.stream().filter(l2::contains).
                             findAny().isPresent()) {
            sList.add(sRow.get(StudentTable.NAME));
         }
      }
      result.put(tRow.get(TeacherTable.NAME), sList);
   }

Data Changes

   // pl instance of EduPL
   pl.deleteTeacher("Jane Smith");

Here is how to change the email address of student 74 to n.lee@example.com and add the course LSSGBP to his list of courses:

   Student student = pl.getStudent(74);
   Contact contact = student.getContact();
   List<String> courses = student.getCourses();
   
   contact.setEmail("n.lee@example.com");
   courses.add("LSSGBP");
         
   pl.persistStudent(74, student.getName(), contact, courses);

   EduDB.CONTACT_TABLE.updateAllChangeValues(
           ContactTable.POSTAL_CODE,
           pc -> pc / 10000 == 8 ? 800000 + pc % 80000 : pc);

Transactions, Units, Read Zones

1. A possible destruction of the database's integrity is accepted. (This may be due to a write operation that catastrophically fails.)
2. A possible violation of domain-specific constraints is accepted. (This may be because a sequence of write operations could not be completed due to an unexpected exceptional situation.)
3. No other clients use the database at the same time.

For example, using a unit, the code snippet

   // pl instance of EduPL
   try (Unit u = pl.openUnit()) {
      pl.deleteCourse("CFR");
      u.commit();
   }

   // Don't forget u.commit() after the last write operation.
   try (Unit u = pl.openUnit()) {
      pl.deleteCourse("CDPC");
      pl.deleteCourse("HDJ");
      pl.deleteCourse("MBS");
   }

   // Don't forget u.commit() after the last write operation.
   try (Unit u = pl.openUnit()) {
      pl.deleteCourse("CDPC");
      pl.deleteCourse("HDJ");
      u.commit();
      pl.deleteCourse("MBS");
   }

Of course, the integrity of the database is maintained even if a call to u.commit() is missing. However, one must be aware that if database changes are rolled back, other things can get into disarray: In the example above, the index of the Course table will miss the entry for the MBS course, although that course still resides in the database. This is because the removal of the MBS course from the index has not been undone.

It is a good idea to treat any rollback situation as a bug.

Two database write operations that are started in two different threads are never executed concurrently, regardless of whether they run inside or outside a unit. Write operations are therefore synchronized. On the other hand, read operations are not synchronized. They can fail if a write operation is currently running in a different thread. To synchronize read operations, use a read zone. Read operations within a read zone are never executed concurrently with a write operation, but they are executed concurrently with read operations inside open read zones in different threads.

In Section Visiting the Rows of a Table from above we displayed the name of all courses in the Course table. Let's do the same thing but this time inside a read zone:

   try (ReadZone rz = db.openReadZone()) {
      COURSE_TABLE.rows(NAME).forEach(row ->
                     System.out.println(row.get(NAME)));
   }