KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > access > DatabaseInstant


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.access.DatabaseInstant
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.store.access;
23
24 import java.io.Serializable JavaDoc;
25 /**
26  *
27  *
28  * A DatabaseInstant is a quantity which the database associates
29  * with events to collate them.
30  *
31  * This interface is used in the column SYS.SYSSYNCINSTANTS.INSTANT.
32  * <P>
33  * Assume a database associates a DatabaseInstant to an event E1. We call this
34  * I(E1). Also assume the same Database associates a DatabaseInstant to a second
35  * event E2. We call this I(E2). By definition
36  *
37  * <OL>
38  * <LI> If I(E1) < I(E2) event E1 occurred before event E2
39  * <LI> If I(E2) = I(E2) event E1 is the same event as E2
40  * <LI> If I(E1) > I(E2) event E1 occurred after event E2
41  * </OL>
42  *
43  * <P>It is not meaningful to compare a DatabaseInstant from one database with a
44  * DatabaseInstant from another. The result of such a comparison is
45  * undefined. Because a database may construct, store and compare huge numbers
46  * of DatabaseInstants, this interface does not require an implementation to
47  * notice when a caller compares a DatabaseInstants from different databases.
48  * <P>
49  * Any implementation of this interface must implement value equality, thus
50  * implementing equals() and hashCode() methods.
51  */
52 public interface DatabaseInstant
53 extends Serializable JavaDoc
54 {
55
56     /**
57       Return true if this DatabaseInstant is before another
58       DatabaseInstant from the same database.
59
60       @param other a DatabaseInstant from the same database as
61       this.
62       
63       @return the comparison result. If 'other' is from another database
64       the result is undefined.
65     */
66     public boolean lessThan(DatabaseInstant other);
67
68     /**
69       Return true if this DatabaseInstant equals
70       DatabaseInstant from the same database.
71
72       @param other a DatabaseInstant from the same database as
73       this.
74       
75       @return the comparison result. If 'other' is from another database
76       the result is undefined.
77     */
78     public boolean equals(Object JavaDoc other);
79
80     /**
81      * Return the next higher DatabaseInstant. There is no requirement that
82      * a transaction with the next instant exist in the database. It is required that
83      * this.lessThan( this.next()), and that no instant can be between this and this.next().
84      *
85      * If the DatabaseInstant is implemented using a integer then next() should return
86      * a new DatabaseInstant formed by adding one to the integer.
87      *
88      * @return the next possible DatabaseInstant
89      */
90     public DatabaseInstant next();
91
92     /**
93      * Return the next lower DatabaseInstant. There is no requirement that
94      * a transaction with the next instant exist in the database. It is required that
95      * this.prior().lessThan( this), and that no instant can be between this and this.prior().
96      *
97      * If the DatabaseInstant is implemented using a integer then prior() should return
98      * a new DatabaseInstant formed by subtracting one from the integer.
99      *
100      * @return the prior possible DatabaseInstant
101      */
102     public DatabaseInstant prior();
103
104     /**
105      * Convert the database instant to a string. This is mainly used for debugging.
106      *
107      * @return a string representation of the instant.
108      */
109     public String JavaDoc toString();
110 }
111
Popular Tags