Ptolemy II Package Design

Ptolemy II uses the Java package system to group classes.

  • Packages are (roughly) small enough that the UML static structure diagram for the package fits on one page. Larger packages are possible when there is a compelling reason to keep classes together, or when the classes have such a regular structure that their architecture is easily grasped.
  • Bidirectional dependencies between packages should be avoided. If two packages are dependent upon each other, it makes it hard to determine which package to compile first. Below are the possibilities
  • A subpackage is a package that is beneath a parent package in the directory hierarchy. For example ptolemy.kernel.util is a subpackage of ptolemy.kernel. The makefiles are structured so that we run make in the subdirectories first so in general, it is best if subpackages do not depend on the parent package (the reverse is OK).
  • The test suite for a package should only use packages that are already depended upon by the package under test. This rule cannot always be followed, but if it is followed, it makes it much easier to reuse a package since the tests will not require extra packages.
  • compile time dependencies
  • A class explicitly imports a class from another package
  • A class explicitly uses a class from another package by using the fully qualified dot separated name
  • run time dependencies
  • A class uses reflection at runtime.
    ptolemy.data.expr.MatlabUtilities is an example of how we use reflection to use the ptolemy.matlab classes at runtime so that we can compile ptolemy.data.expr and not necessary have ptolemy.matlab present
  • A class parses MoML at runtime that invokes other classes.
  • test time dependencies
  • It is better to write Unit tests before writing System tests.
  • Unit tests will usually get you better coverage and test the code more thourougly.
  • System tests are useful, but they are more like browsing the code than actually reading it. For example, think of a System test as something like running through a library, looking at the title of the books and and opening up an occasional book to a random page. Unit tests are more like opening up each book and reading it.
  • A good unit test will only use other packages compile time dependencies of the package under test.
    This is important if someone else wants to use the package and not include all of Ptolemy