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