Overview

Introduction

Model objects are Java objects which represent all units of information/communication to be passed to the various applications of our system. They are populated by calling the model database access layer reader classes, which will return the appropriate model object(s) to applications. Applications will also be able to write to the database by passing in model objects into the model database access layer writer classes.

Model Objects are based on XSD schema files which on the build phase get converted into JAXB model object base classes. These schema files are located in src/main/resources directory. The base classes get generated ( or unmarshalled in JAXB terminology ) into class files which are placed in the target/generated-sources/xjc/edu/berkeley/path/model_objects/jaxb folder. However all Model Objects published in the API are extended from these auto-generated base classes.

Packaging

Model Objects are organized into the following packages:

• Shared - This is where Model Objects which are shared across multiple sub-packages reside (ie. Point Object)
• Network - This is where the classes representing Network topology reside (ie. Network, Node, Link and Route)
• Scenario - This is where the classes representing Scenario Configuration reside (ie. Sets)
• Output Data Performance - Classes outputted by simulation, estimation, prediction
• Performance - Classes for PIF probe and PEMS data
• Exec Params - Classes for run parameters of various applications
• Project - Classes for project handling
• Util - Utility functionality, like serialization of objects, polyline encoding/decoding.

Technical Requirements for Model Objects

1. Extended objects must contain getters and setters for base class attributes. For example in the network base class there are getters and setters for network name, however we are not making the base classes visible so we should create getters and setters which override these methods in the extended class. This will also help to keep changes more confined in the model object layer if there are underlying schema changes.

2. General validation. There should be an isValid function which should contain an agreed upon list of logic to ensure incorrectly defined model objects don't get saved into the database. This should be called in the model database access layer writers before trying to write to the database.

3. Add any other attributes or methods which have generic uses across multiple applications. For instance there is a populate method within the network class which populates the entire network by assigning node references in place of ids to appropriate begin and end nodes for links. As well this method populates all input and output links by adding the appropriate link reference in place of ids for all nodes.

4. Model objects must have comments for each method which adhere to a JavaDoc standard. As well all attributes added to the extended model objects should be marked as protected and ignored from the JavaDocs by placing the following text in front of them: /** @y.exclude */

5. Model objects must be populated in the database readers using factories. One Factory object will exist for each sub-package which essentially contains a method per model object which creates and returns a new model object of a particular type (see the network factory for example). The factory is necessary so the applications can create application specific extended model objects by extending the appropriate factory and overriding the methods to instead instantiate their application specific class.

6. Model objects which encapsulate other model objects should override setter and getter methods to return the encapsulated extended model objects not the base objects. For example the network model object is able to return lists of extended node and link model objects, not just the base JAXB generated classes.

7. Stored Procedures calls should be used in place of queries in the model database access layer. This is especially true for the writers since developers do not have write permission within the Oracle Via Database.