001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.DatabaseInstant
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.access;
023:
024: import java.io.Serializable;
025:
026: /**
027: *
028: *
029: * A DatabaseInstant is a quantity which the database associates
030: * with events to collate them.
031: *
032: * This interface is used in the column SYS.SYSSYNCINSTANTS.INSTANT.
033: * <P>
034: * Assume a database associates a DatabaseInstant to an event E1. We call this
035: * I(E1). Also assume the same Database associates a DatabaseInstant to a second
036: * event E2. We call this I(E2). By definition
037: *
038: * <OL>
039: * <LI> If I(E1) < I(E2) event E1 occurred before event E2
040: * <LI> If I(E2) = I(E2) event E1 is the same event as E2
041: * <LI> If I(E1) > I(E2) event E1 occurred after event E2
042: * </OL>
043: *
044: * <P>It is not meaningful to compare a DatabaseInstant from one database with a
045: * DatabaseInstant from another. The result of such a comparison is
046: * undefined. Because a database may construct, store and compare huge numbers
047: * of DatabaseInstants, this interface does not require an implementation to
048: * notice when a caller compares a DatabaseInstants from different databases.
049: * <P>
050: * Any implementation of this interface must implement value equality, thus
051: * implementing equals() and hashCode() methods.
052: */
053: public interface DatabaseInstant extends Serializable {
054:
055: /**
056: Return true if this DatabaseInstant is before another
057: DatabaseInstant from the same database.
058:
059: @param other a DatabaseInstant from the same database as
060: this.
061:
062: @return the comparison result. If 'other' is from another database
063: the result is undefined.
064: */
065: public boolean lessThan(DatabaseInstant other);
066:
067: /**
068: Return true if this DatabaseInstant equals
069: DatabaseInstant from the same database.
070:
071: @param other a DatabaseInstant from the same database as
072: this.
073:
074: @return the comparison result. If 'other' is from another database
075: the result is undefined.
076: */
077: public boolean equals(Object other);
078:
079: /**
080: * Return the next higher DatabaseInstant. There is no requirement that
081: * a transaction with the next instant exist in the database. It is required that
082: * this.lessThan( this.next()), and that no instant can be between this and this.next().
083: *
084: * If the DatabaseInstant is implemented using a integer then next() should return
085: * a new DatabaseInstant formed by adding one to the integer.
086: *
087: * @return the next possible DatabaseInstant
088: */
089: public DatabaseInstant next();
090:
091: /**
092: * Return the next lower DatabaseInstant. There is no requirement that
093: * a transaction with the next instant exist in the database. It is required that
094: * this.prior().lessThan( this), and that no instant can be between this and this.prior().
095: *
096: * If the DatabaseInstant is implemented using a integer then prior() should return
097: * a new DatabaseInstant formed by subtracting one from the integer.
098: *
099: * @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: }
|