Java ACDP Tutorial

Design

The remaining sections of this page are

A Sample World

The black diamond () indicates a composition. Since the contact details are rather complex, by dedicating them their own entity, we avoid the repetition of contact related attributes in the Student and Teacher entities, including any code for checking the validity of values, for example whether a given value is a valid phone number.

Coding Table Classes

For each table class we need to define the columns of the table as well as the characteristic sequence of columns, also known as the table definition:

1. Create a Column instance with the CL column factory class for each column of the table and assign each column instance to a separate variable.
2. Define a constructor and invoke the initialize method of the super class with the column instances declared in the first step.

   import static acdp.design.ST.Nulls.NO_NULL;
   import static acdp.design.ST.Nulls.NULLABLE;
   import static acdp.design.ST.OutrowStringLength.SMALL;
   
   final class CourseTable extends CustomTable {
      static final Column<String> ID = CL.ofString(NO_NULL, SMALL);
      static final Column<String> NAME = CL.ofString(NO_NULL, SMALL);
      static final Column<Ref> TEACHER = CL.ofRef();
   
      CourseTable() {
         initialize(ID, NAME, TEACHER);
      }
   }
   
   final class StudentTable extends CustomTable {
      static final Column<Integer> STUDENT_NUMBER = CL.ofInteger(NO_NULL);
      static final Column<String> NAME = CL.ofString(NO_NULL, SMALL);
      static final Column<Ref> CONTACT = CL.ofRef();
      static final Column<Ref[]> COURSES = CL.ofArrayOfRef(30);
      
      StudentTable() {
         initialize(STUDENT_NUMBER, NAME, CONTACT, COURSES);
      }
   }
   
   final class TeacherTable extends CustomTable {
      static final Column<String> NAME = CL.ofString(NO_NULL, SMALL);
      static final Column<Float> SALARY = CL.ofFloat(NULLABLE);
      static final Column<Ref> CONTACT = CL.ofRef();
      static final Column<Ref[]> COURSES = CL.ofArrayOfRef(45);
   
      TeacherTable() {
         initialize(NAME, SALARY, CONTACT, COURSES);
      }
   }
   
   final class ContactTable extends CustomTable {
      static final Column<String> PHONE_NUMBER = CL.ofString(
                                     Charset.forName("US-ASCII"), NULLABLE, 12);
      static final Column<String> EMAIL = CL.ofString(NO_NULL, SMALL);
      static final Column<String> STREET = CL.ofString(NO_NULL, SMALL);
      static final Column<String> CITY = CL.ofString(NO_NULL, SMALL);
      static final Column<String> STATE = CL.ofString(NO_NULL, SMALL);
      static final Column<Integer> POSTAL_CODE = CL.ofInteger(NO_NULL);
      static final Column<String> COUNTRY = CL.ofString(NULLABLE, SMALL);
      
      ContactTable() {
         initialize(PHONE_NUMBER, EMAIL, STREET, CITY, STATE, POSTAL_CODE, COUNTRY);
      }
   }

1. The column variable declarations include the static modifier. This is possible because we do not intend to reuse any of the table classes in our database or some other database. (See the description of the CustomTable class for details.)
2. Always include the final modifier in the declaration of a column variable. Here, we included the final modifier in the declaration of the table classes too. A more elaborated table class may be derived from a more general (abstract) table super class.
3. Note that we have not yet assigned names to the tables and columns. We have also not yet specified the target tables of the reference column types that appear in the table classes Courses, Student and Teacher. This will be done later in Chapter Creation when we prepare the table classes for processing by ACDP's Setup Tool.
4. The CL column factory class provides factory methods for columns with a type corresponding to a built-in Java type, including arrays. The NO_NULL or NULLABLE argument creates a column type that prohibits or allows the null value to be stored in the column. The null value is always allowed as a value in a column of an array, a reference or an array of references column type.
5. Invoking CL.ofString() returns a column with a nullable string column type of a length comparable to the length of an ordinary Java String instance.
6. A column of a string column type created with the SMALL argument allows for strings with a length of 255 characters at most.
7. The PHONE_NUMBER column in the Contact table is created by an invocation of CL.ofString(Charset.forName("US-ASCII"), NULLABLE, 12). This allows for a phone number with a length of 12 characters at most. The really special thing about this column type, however, is its so called inrow storage scheme which allows the particularly efficient storage of values.
8. A student can attend at most 30 courses and a teacher instructs at most 45 courses.

Coding the Database Class

   final class EduDB extends CustomDatabase {
      static final CourseTable COURSE_TABLE = new CourseTable();
      static final StudentTable STUDENT_TABLE = new StudentTable();
      static final TeacherTable TEACHER_TABLE = new TeacherTable();
      static final ContactTable CONTACT_TABLE = new ContactTable();
   
      EduDB(Path mainFile, int opMode, boolean writeProtect,
                                                   int consistencyNumber) {
         open(mainFile, opMode, writeProtect, null, consistencyNumber,
                 COURSE_TABLE, STUDENT_TABLE, TEACHER_TABLE, CONTACT_TABLE);
      }
   }

1. The table variable declarations include the static modifier. This is possible because we do not intend to reuse any of the table classes in our or some other database. (See the description of the CustomDatabase class for details.)
2. Always include the final modifier in the declaration of a table variable. Here, we included the final modifier in the declaration of the database class too. A more elaborated database class may be derived from a more general (abstract) database super class.
3. Note that we have not yet assigned a name to the database. This will be done later in Chapter Creation when we prepare the database class for processing by ACDP's Setup Tool.
4. The arguments of the open method are explained in Chapter Opening.

Coding a Custom Column Type

All non-array column types are derived from the SimpleType class. A class that extends the SimpleType class must implement the toBytes(T) and the fromBytes(byte[], int, int) methods which convert a value of type T, for example BigInteger, into a byte array and vice versa.

Moreover, implementers of a custom column type must implement a public and static factory method annotated with the TypeFromDesc annotation which creates an instance of the column type from its so called type descriptor. The type descriptor is a String that uniquely identifies the column type. It contains enough information so that an instance of the column type can be created from it.

   public final class BigIntegerType extends SimpleType<BigInteger> {
      private static final String TD_PREFIX = "BigInteger";
   
      @TypeFromDesc
      public static final BigIntegerType createType(String typeDesc) throws
                                                           CreationException {
         final TypeDesc td = new TypeDesc(typeDesc);
         if (!td.prefix.equals(TD_PREFIX) || td.scheme != Scheme.INROW ||
                                                               !td.variable) {
            throw new CreationException("Illegal type descriptor");
         }
         return new BigIntegerType(td.limit, Nulls.get(td.nullable));
      }
   
      BigIntegerType(int limit, Nulls nulls) throws IllegalArgumentException {
         super(BigInteger.class, Scheme.INROW, nulls.value(), limit, true);
      }

      @Override
      protected final String typeDescPrefix() {
         return TD_PREFIX;
      }
   
      @Override
      protected final byte[] toBytes(BigInteger val) throws NullPointerException {
         return val.toByteArray();
      }

      @Override
      public final BigInteger fromBytes(byte[] bytes, int offset,
                                     int len) throws IndexOutOfBoundsException {
         return new BigInteger(Arrays.copyOfRange(bytes, offset, offset + len));
      }
   }

1. The limit parameter of the constructor lets us create columns wich accept integer values of an arbitrary size. Recall that Java's int and long types are 4 and 8 bytes in size, respectively.
2. The nulls parameter of the constructor specifies whether the column type allows the null value.
3. The second and fifth arguments of the super constructor invocation tell us that the BigInteger column type uses the efficient inrow storage scheme and expects the byte array returned by the toBytes method to be of a variable length.
4. The type descriptor starts with a prefix which by default starts with the uppercase letter L followed by the qualified name of the column type's class name. Overriding the typeDescPrefix() method lets you specify your own prefix. Such a custom prefix must start with an uppercase letter because the type descriptor of a custom column type must start with an uppercase letter.
5. Note that the createType(String) factory method throws a CreationException if the argument is not a valid type descriptor for the BigInteger column type.

   static final Column<Float> SALARY = CL.ofFloat(NULLABLE);

   static final Column<BigInteger> SALARY = CL.create(
                          new BigIntegerType(20, NULLABLE));

Coding a Cipher Factory

Here is a ready-to-play-with cipher factory class which unrealistically discloses the secret key in the source code:

   final class CipherFactory implements ICipherFactory {
      private final IvParameterSpec iv = new IvParameterSpec(new byte[] {
                                 114, -8, 22, -67, -71, 30, 118, -103,
                                 51, -45, -110, -65, 16, -127, -73, 103 });

      private final Key key = new SecretKeySpec(new byte[] { 114, -8, 23,
                                   -67, -71, 30, 118, -103, 51, -45, -110,
                                   -65, 16, -127, -73, 103 }, "AES");
      @Override
      public final Cipher createCipher() throws NoSuchAlgorithmException,
                                                  NoSuchPaddingException {
         // Example with padding: AES/CBC/PKCS5Padding
         return Cipher.getInstance("AES/CTR/NoPadding");
      }

      @Override
      public final void initCipher(Cipher cipher, boolean encrypt) throws
                  InvalidKeyException, InvalidAlgorithmParameterException {
         cipher.init(encrypt ? Cipher.ENCRYPT_MODE : Cipher.DECRYPT_MODE,
                                                                   key, iv);
      }
   }