This document sketches the design of a second main component of tauZaman, an ongoing project in Java, which has its roots on another project, called MultiCal. Before going through the explanation of main figures of the design, a brief yet informative summary on components of the whole project must be given. Project can be theoretically (also practically) composed of two distinct components, namely, Temporal Abstract Data-Type (TADT) and Uniform Calendar Support (UCS) as in MultiCal. Generally but basically speaking, TADT consists of primitive operations on time-values independent from user interpretation. On the other hand UCS provides services, which allow multiple-interpretation of time-values (Calendric Systems, Calendars, etc.).
The main idea behind this separation comes from the very spirit of the original idea that leaded to MultiCal; Universal aspects of time are separated from the user dependent aspects. In that sense, TADT represents the universal aspects of time, whereas UCS represents user dependent aspects. Having cleared the issue of main components, of which there will be no radical change in this project in terms of underlying understanding, a list of design documents describing MultiCal (and a predecessor of it, timeADT) project can be found here.
Although underlying understanding is same, structures of components and interactions between them has significantly changed. This is both true for two main components given above. So, the whole project consists of 2 parts, and therefore, 2 separate design documents. In this particular design document, mainly user dependent parts, Calendars, Calendric Systems, Properties, Field Values and Temporal Elements, are touched. The design document for other part, which covers universal aspects of time is explained elsewhere.
The rest of this document is organized as follows; Under the Design heading, each of the parts will be analyzed and their designs will be revealed separately. Then, under the Highlights heading a section will contain other bits and pieces, such as, some specific decisions, that help to cover whole design picture. At the end, a conclusion will recap the issues so far and summarize the future progress.
A Calendar is a human abstraction of the physical time-line [1]. For example, Chinese Calendar, based on rotation of Moon around the Earth. Calendars are composed of two parts; one of them is universal interpretation of time according to a particular Calendar, which is also called intrinsic characteristics, the other one is different representations of this universally interpreted time, which is also called extrinsic characteristics. Number of the months in a year may be an example to first part, whereas, name of a particular month may be an example of the other. Calendars are also represented as collections of related Granularities, which are the unit of measure for temporal data [2]. For example; Month, Year, Day, are some of the granularities of Gregorian Calendar. Granularities and operations on them mainly form the intrinsic characteristics. Extrinsic characteristics of Calendars, will be explained later in 3.
1.2 Representation
There are two representations of a Calendar in the system;
A file, so called Calendar Specification, can be fetched and processed by the system. This file contains definitions of Granularities and their relations with each other in a particular Calendar. Theoretically, generally speaking, any file type can be a specification file, ascii, xml, etc. Although XML representation is the main concern, and therefore the focus point, the ability to process any other file type can be incorporated easily with this design (see more about this issue in Highlights). Any xml parsing technique could be used to implement parsing feature of XML representation of a Calendar, but a DOM model with javax.xml.parsers implementation was chosen.
The second one is the internal representation of a Calendar in the system. Since a dynamic Calendar is out of question (for now), static arrays are used to keep the information parsed from a specification file. In fact, for XML representation, an XPath implementation could also have been used to query a file, but this could also increase the response time of the system to a query (not too much though if we think about the size of a specification file) and will not apply to any other file type. Another important part of the internal representation consists of dynamic loading of Calendar implementations that come with specification files as URLs to java classes. What are these Calendar implementations? Irregular granularity relations and regular functions are the implementations that should be incorporated into the internal representation of Calendars. These are achieved by using a class, called ClassLoaderMethodCaller, which loads java classes dynamically and calls their methods. This topic will be analyzed further in Highlights.
An important point here is about primary keys on Calendars. Names given by third parties (the ones who form different Calendar Specifications and provide implementations), can not be used as PKs since they may have the same names. So, URLs of specification files are considered to compose PKs for Calendars (and for other components as a consensus through-out this design).
1.3 Place it fits in the system and Examples
In the system, semantically, a Calendar is always associated with one (or possibly more) Calendric System, however, Calendars can also live idle in the system without used by any Calendric System. This state can occur if a Calendric System, which is the only one using a particular Calendar is shallowly erased. Calendars are managed by a CalendarRepository, which also behaves as a Calendar cache. CalendarRepository provides services such as load, unload, refresh Calendars to a CalendricSystem requests. For example;
// assume cr is an instance of CalendarRepository class...
Calendar myHinduCalendar;
//tries to load a Calendar with URL
try{
myHinduCalendar = cr.loadCalendar( new URL("http://www.eecs.wsu.edu/calendars/hinduv1.xml") );
}
catch (DuplicateCalendarException dce){...};
catch (CalendarFormationException cfe){...};
...
//tries to unload a Calendar with URL
try{
cr.unloadCalendar(new URL("http://www.eecs.wsu.edu/calendars/hinduv2.xml") );
}
catch (NoSuchCalendarException nsce){...};
//refreshes all Calendars in the database
try{
cr.refresh();
}
catch (CalendarFormationException cfe){...};
Each Calendar forms its internal state by parsing a Calendar Specification file via a Parser API. An implementation for XML parsing using this API is CalendarParser. A Calendar keeps its Granularity relations, called Mappings, in specialized classes called, RegularMapping and IrregularMapping.
1.4 Exceptions
See a general design document on exceptions.
See exception design on Calendars.
2.1 Definition
A Calendric System is defined as a collection of Calendars where each Calendar is defined over non-overlapping periods of time, termed Epochs. [1].
2.2 Representation
As in Calendars, Calendric Systems have two representations in the system;
A file, so called CalendricSystem Specification, can be fetched and processed by the system. This file contains; Epochs on which Calendars are defined, and supportive components (explained under Properties and Field Values sections), which allow multiple-interpretation of time. Again, as in Calendars, an XML representation was the main concern in our system, although other file type processing are allowed through a general parsing API. An implementation of this API for XML representation files is CalendricSystemParser in the system.
The second one is the internal representation of a Calendric Systems in the system. Arguments made about data structures in Calendar are also same in Calendric System. And primary key of CalendricSystems is again composed of URLs of related specification files. Rationale for not having Calendric System names as primary keys is, for instance, a system can have two american calendric system, but having different implementations. As in Calendars, Calendric System will make use of ClassLoaderMethodCaller class for dynamic loading of irregular mappings between granularities of different Calendars.
2.3 Place it fits in the system and Examples
CalendricSystems are managed by a CalendricSystemManager, which loads, unloads CalendricSystems. For example;
//assume csm is an instance of CalendricSystemManager...
// adds a CalendricSystem associated with given URL...
try{
csm.addCalendricSystem(new URL("http://www.cs.arizona.edu/calendricsystems/americanv1.xml") );
}
catch(DuplicateCalendricSystemException dcse) {...};
...
// removes a CalendricSystem associated with given URL and its associated Calendars (if possible)...
try{
csm.deepRemoveCalendricSystem(new URL("http://www.cs.arizona.edu/calendricsystems/americanv2.xml") );
}
catch(NoSuchCalendricSystemException nscse) {...};
(Hashtables are utilized through-out the system, whenever we can identify keys and their related object handles. For example, a list of CalendricSystems are stored in Hashtables as URLs their keys.)
2.4 Exceptions
See a general design document on exceptions.
See exception design on CalendricSystems.
3.1 Definition
As stated in 1.1, Calendars have two types of characteristics. One of them, which is also named as extrinsic characteristics, Properties, define the user-dependent or varying qualities of a Calendar. For example; in Turkey, where Gregorian Calendar is used, one of the formats to represent a date is, day/month/year. In USA, again Gregorian Calendar is being used, however, representation of a date is not same, month/day/year. Also, the names of months are obviously different, due to different languages. A limited number, which was 15 in our system (see them), of such properties were identified.
3.2 Representation
There are two representations;
A file, so called Property Specification, can be fetched and processed by the system. A typical Property Specification file contains one or more of these defined 15 Properties, whose XML Representation are similar to Calendar and CalendricSystem representations. Also a general API is provided for parsing purposes. An implementation for XML parsing is placed in PropertyParser.
Second one is internal representation and consists of sub-structures that form a complete Property. These structures are; Format, which defines a format string for either timestamp output or temporal constant input. FieldInfo, which defines characteristics of a format string, such as field value tables to be used (see 4). ImportFormat, which allows recursive definition of Properties. Same as others URLs are considered to be unique identifiers for Properties.
3.3 Place it fits in the system and Examples
First of all, Properties are managed by PropertyManager and each CalendricSystem has one instance of PropertyManager to manage its Calendars' properties. What does "managing Properties" mean? In one request, user may want to use one date format in one language (ex. day/month/year in Kurdish) and in the other he/she may want to use another in another language (ex. month/day/year in English). Handling property activation and deactivation issues are called, managing Properties. This is achieved by PropertyStackService class, which can activate, deactivate, reset different Properties in the system. It basically makes use of a java.util.Hashtable and an array of java.util.Stacks for each type of Property.
Let's see some examples of managing Properties;
// assume pm is an instance of PropertyManager...
// you can either activate a set of Properties or just one of them given URL pointing to a
// Property Specification file...
String [] instantInputFormatProperty = {"InstantInputFormat"};
try{
pm.propertyActivate(new URL("http://www.eecs.wsu.edu/properties/propertyTable1.xml"), instantInputFormatProperty);
}
catch(PropertyFormationException pfe){...};
...
// deactivate Properties with a given name, in this CalendricSystem...
try{
pm.propertyDeactivate("instantInputFormat");
}
catch(NoSuchPropertyException nspe){...};
3.4 Exceptions
See a general design document on exceptions.
See exception design on Properties.
4.1 Definition
As stated in 3.1, output format of a date can be changed from one user to another. For instance, language is one of these user-dependent characteristics. In Properties, fields such as month, year, week are related to either to some tables or to some functions. These tables and functions compose what is called field value support. For example, a date format specified in a Property, month/day/year, might be set up such that month field is associated with a english month names table, which has indexes and corresponding English names of months (1 to January, 2 to February, and so on...). Sometimes static tables such as english month names is not enough. For example, an Arabic Numeral table would have had indexes and corresponding strings. But representing this information as tables won't be efficient since it would take a lot space. Instead it is represented as functions. So, field value support consists of two major sources; Field Value Tables and Functions.
4.2 Representation
Field Value Tables (FVTables) are represented as specification files and Field Value Functions (FVFunctions) are represented as code in methods of classes. Other than this distinction there is no difference between them in the sense that they both provide two same services; one of them is called stringToIndex, which looks up the index of an input string. And the other one is opposite of this, indexToString, which looks up the string corresponding of an input index. Due to this similarity a base class called FVSupport (Field Value Support) is formed to keep these similar behaviors. And FVTable and FVFunction are derived.
4.2.1 FVTable
As in Calendar, CalendricSystem and Property, FVTables have two representations in the system;
A file, so called Field Value Table Specification, can be fetched and processed by the system. An XML Representation is defined and an implementation of general Parsing API is provided with FVTableParser class.
Second one is internal representation and Hashtables are utilized again with the consensus that URLs are Primary Keys.
4.2.1 FVFunction
As in Calendar, CalendricSystem and Property, FVTables have two representations in the system;
A class file, which contains code for field value function can be fetched and processed by the system. To load and call the methods of such a class with a given URL is provided by ClassLoaderMethodCaller class.
Second one is internal representation and provides an API in order to be able to call dynamically loaded classes' methods via ClassLoaderMethodCaller class.
4.3 Place it fits in the system and Examples
Both FVTables and FVFunctions are managed by FVManager class and each CalendricSystem has one FVManager instance. For example;
// assume that fvm is an instance of FVManager...
FVTable fvt = fvm.getFVSupport("EnglishMonthNames");
// find corresponding string of index 0
String aMonthName = fvt.indexToString(0);
4.4 Exceptions
See a general design document on exceptions.
See exception design on Field Values.
5.1 Definition
In fact, some of temporal elements fall into the class, which is specified at the Introduction section as "not the topic of this design". Nevertheless, a small definition would make easier to explain the other elements that fall into class, which is specified as "the concern of this design".
There are three important temporal notions; moments in time as Instant, periods in time as Period and durations in time as Interval. These can also be expanded, such as DeterminateInstants and IndeterminateInstants to capture the intuitive concepts of time more precisely. What is important for our documentation is that, these pieces are the entrance points to above components, Calendar, CalendricSystem, etc. Between them two components play a very important role; Input and Output.
Input, for example, converts a given input temporal constant such as, 12/01/2003, to its corresponding timestamp with a given CalendricSystem. Output performs the reverse of this process. It's better to see whole picture as a sequence diagram (for Input only).
5.2 Exceptions
See a general design document on exceptions.
See exception design on Temporal Data Types.
So what are the significant changes from previous designs?
Names of some of the components were changed for good, including field value array, array of field values, fields, field value table, functions, mapping, package names, etc. See the design decision document on various name changes.
Local and Global Granularity issues are no more handled by look-up tables and simplified for CalendricSystem Specification file writers. See the design decision document on this issue.
Component Specification files are represented as XML files, easy to handle and process. However, other file types can still be used by adding parsers conformant to specific parser API.
Extensibility is increased by using XML specification files and system became distributive in the real meaning by loading classes dynamically. Support classes (as a jar file) are needed to write a Calendar implementation independently, however, a future java RMI feature can prevail this disadvantage. For now, however, RMI seemed to be rather awkward and irrelevant with the aim of our system. (Response time)
By separating array of field values (Field and Fields in our system) from Calendars will make easier to move a system working concurrently.
Documentation with javadoc.
This document described one set of significant components of tauZaman system (Other set of parts were described elsewhere.). It is not intended to cover all details of each component, however, detail design can be found in tauZaman API Specification. Future progress includes revision of the design, implementation and at last testing.
[1] Soo, M.D. and R. Snodgrass. "Multiple Calendar Support for Conventional Database Systems.", Technical Report 92-7.Computer Science Department, University of Arizona. Feb.1992.
[2] Dyreson, C. E.; Evans, W. S.; Lin, H.; and Snodgrass, R. T. 1998. Efficiently supporting temporal granularities. http://citeseer.nj.nec.com/dyreson99efficiently.html.