Current Version: Elaboration Iteration 1, Completed 11/14/2002
Inception, Completed 9/5/2002

Supplementary Specification

This is the supplementary specification for the StickSync project. This page is divided into the following sections:

  1. Introduction
  2. Functionality
  3. Usability
  4. Reliability
  5. Supportability
  6. Implementation Constraints
  7. Development Constraints
  8. Interfaces
  9. Domain Rules
  10. Licensing
  11. Information in Domains of Interest

Introduction

This document is the repository of all StickSync project requirements that are not captured in the use cases.

Return to top

Functionality

The system supports synchronizing sets of files whose total size exceeds the capacity of the PMSD, as long as the total size of the changed files does not exceed the capacity (with some margin for additional data).

The system needs a mechanism to determine the identity of the local computer.

The system must log all of its actions to a log file on the local computer.

Return to top

Usability

The system should have a graphical user interface. Power users are also comfortable with, and sometimes prefer, a command-line interface, so the system should also provide a command-line interface.

Help and documentation should be provided in the form of web pages.

Return to top

Reliability

Failure Avoidance

Copies of data structures used by the system and stored on disk should be locked when the system is running to prevent multiple instances of the system from corrupting the data structures.

Recoverability

If a PMSD that has been used by the system fails it should be easy for the user to synchronize the computers using another PMSD.

Return to top

Supportability

The system must be well-documented within the source code to ease future maintenance and to increase the likelihood that documentation will be maintained.

Future support for computers running Linux is desirable.

The system should support future internationalization of its user interface, including all messages and help.

Return to top

Implementation Constraints

The system shall run on Macintosh and Windows computers and shall support synchronization between any combination of two such computers (for example, two Macs or one Mac and one Windows computer).

The computers must have a Java runtime on them.

Return to top

Development Constraints

The project must be developed in Java. This is important both for cross-platform operation and because this project is to serve as an example for Com S 362, which requires use of the Java Programming LanguageTM.

System development must use tools that are available on both Windows and Macintosh systems.

Because the project is to serve as an example for Com S 362, the developers must use object-oriented analysis and design techniques and the Unified Process.

Return to top

Interfaces

The PMSD appears as a disk drive, and so can be treated as a normal file system.

Return to top

Domain Rules

This section should discuss constraints imposed by the Mac and PC file systems. Since they are outside to system boundary they are part of the problem domain.

The implementation requires that the PMSD contain at least a table giving the modification time for every synchronized file on both synchronization partners. This is represented in the domain model by the associations from PMSD to SyncPartnership to FilePairing, which contains attributes lastSyncTimeComputer1 and lastSyncTimeComputer2, representing the time stamp of the file on each computer at the conclusion of the last synchronization on that computer. These stored times are used to calculate the appropriate action for the System when synchronizing a file.

In addition to the last synchronization time on each computer for a given FilePairing, we also have the modification time of the version of the file on the local computer. These three time stamps are sufficient for deciding whether changes were made to a file on the local computer, the remote computer, both or neither. The table below gives the decision rules. A state diagram and discussion of how the rules were derived is available here. While the time stamps stored in the FilePairing are named lastSyncTimeComputer1 and lastSyncTimeComputer2 (since the PMSD will move around), we write the rules using lastSyncTimeLocal and lastSyncTimeRemote. These values are easily calculated based on the computer on which the System is running.

Rules for calculating synchronization action
Condition Action Justification
localFileTime is before lastSyncTimeLocal Report error local file is back-dated
localFileTime equals lastSyncTimeLocal, both are before lastSyncTimeRemote PMSD overwrites local Local not changed, remote changed
lastSyncTimeLocal is before localFileTime, and lastSyncTimeRemote is before or equal to lastSyncTimeLocal local overwrites PMSD Local changed, no known changes to remote
lastSyncTimeLocal is before localFileTime, and lastSyncTimeLocal is also before lastSyncTimeRemote merge changes Local changed, remote changed
lastSyncTimeLocal equals localFileTime, and lastSyncTimeRemote is before or equal to lastSyncTimeLocal none Local not changed, no known changes to remote

Do we need to extend this to handle directories? !!!

Return to top

Licensing

To support sharing of this example project for educational purposes, and because the developers believe that open source software is important for improving the overall quality of software, the project will be licensed under an open source license.

Though premature for a typical project, we have already chosen a license (the BSD license) for this project. Typically licensing decisions would be made closer to the release date for the project, but since we're putting all the project artifacts on the web from the beginning we decided to choose a license at inception.

Return to top

Information in Domains of Interest

Java

Information on Java is available at java.sun.com

PMSDs

Sony's Micro VaultTM is an example solid-state hard drive. Such a PMSD typically holds 128MB or so of space.

Compressions algorithms might be used to fit large files into the PMSD.

File Checksums

The MD5 algorithm (R. L. Rivest, RFC 1321: The MD5 Message-Digest Algorithm, Internet Activities Board, 1992), may be useful for quickly computing a checksum to see if a file has changed.

Return to top

Last modified Tuesday, September 16, 2003.

This web page is for the StickSync project, developed as an example for Com S 362 at Iowa State University. Please direct any comments or questions about this project to Gary T. Leavens at leavens@cs-DOT-iastate-DOT-edu or Curtis Clifton at cclifton@cs-DOT-iastate-DOT-edu (after replacing -DOT- with `.').