/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
* or http://forgerock.org/license/CDDLv1.0.html.
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at legal-notices/CDDLv1_0.txt.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information:
* Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*
*
* Copyright 2013-2015 ForgeRock AS
*/
package org.opends.server.replication.server.changelog.api;
import java.io.Closeable;
import java.util.Objects;
import org.opends.server.replication.common.CSN;
/**
* Generic cursor interface into the changelog database. Once it is not used
* anymore, a cursor must be closed to release all the resources into the
* database.
* <p>
* The cursor provides a java.sql.ResultSet like API : it is positioned before
* the first requested record and needs to be moved forward by calling
* {@link DBCursor#next()}.
* <p>
* Usage:
* <pre>
* DBCursor cursor = ...;
* try {
* while (cursor.next()) {
* Record record = cursor.getRecord();
* // ... can call cursor.getRecord() again: it will return the same result
* }
* }
* finally {
* close(cursor);
* }
* }
* </pre>
*
* A cursor can be initialised from a key, using a {@code KeyMatchingStrategy} and
* a {@code PositionStrategy}, to determine the exact starting position.
* <p>
* Let's call Kp the highest key lower than K and Kn the lowest key higher
* than K : Kp < K < Kn
* <ul>
* <li>When using EQUAL_TO_KEY on key K :
* <ul>
* <li>with ON_MATCHING_KEY, cursor is positioned on key K (if K exists in log),
* otherwise it is empty</li>
* <li>with AFTER_MATCHING_KEY, cursor is positioned on key Kn (if K exists in log),
* otherwise it is empty</li>
* </ul>
* </li>
* <li>When using LESS_THAN_OR_EQUAL_TO_KEY on key K :
* <ul>
* <li>with ON_MATCHING_KEY, cursor is positioned on key K (if K exists in log)
* or else Kp (if Kp exists in log), otherwise it is empty</li>
* <li>with AFTER_MATCHING_KEY, cursor is positioned on key Kn (if Kp or K exist in log),
* otherwise it is empty</li>
* </ul>
* </li>
* <li>When using GREATER_THAN_OR_EQUAL_TO_KEY on key K :
* <ul>
* <li>with ON_MATCHING_KEY, cursor is positioned on key K (if K exists in log)
* or else Kn (if Kn exists in log), otherwise it is empty</li>
* <li>with AFTER_MATCHING_KEY, cursor is positioned on key Kn (if K or Kn exist in log),
* otherwise it is empty</li>
* </ul>
* </li>
* </ul>
*
* @param <T>
* type of the record being returned
* \@NotThreadSafe
*/
public interface DBCursor<T> extends Closeable
{
/**
* Represents a cursor key matching strategy, which allow to choose if only
* the exact key must be found or if any key equal or lower/higher should match.
*/
public enum KeyMatchingStrategy {
/** Matches if the key or a lower key is found. */
LESS_THAN_OR_EQUAL_TO_KEY,
/** Matches only if the exact key is found. */
EQUAL_TO_KEY,
/** Matches if the key or a greater key is found. */
GREATER_THAN_OR_EQUAL_TO_KEY
}
/**
* Represents a cursor positioning strategy, which allow to choose if the start point
* corresponds to the record at the provided key or the record just after the provided
* key.
*/
public enum PositionStrategy {
/** Start point is on the matching key. */
ON_MATCHING_KEY,
/** Start point is after the matching key. */
AFTER_MATCHING_KEY
}
/** Options to create a cursor. */
public static final class CursorOptions
{
private final KeyMatchingStrategy keyMatchingStrategy;
private final PositionStrategy positionStrategy;
private final CSN defaultCSN;
/**
* Creates options with provided strategies.
*
* @param keyMatchingStrategy
* The key matching strategy
* @param positionStrategy
* The position strategy
*/
public CursorOptions(KeyMatchingStrategy keyMatchingStrategy, PositionStrategy positionStrategy)
{
this(keyMatchingStrategy, positionStrategy, null);
}
/**
* Creates options with provided strategies and default CSN.
*
* @param keyMatchingStrategy
* The key matching strategy
* @param positionStrategy
* The position strategy
* @param defaultCSN
* When creating a replica DB Cursor, this is the default CSN to
* use for replicas which do not have an associated CSN
*/
public CursorOptions(KeyMatchingStrategy keyMatchingStrategy, PositionStrategy positionStrategy, CSN defaultCSN)
{
this.keyMatchingStrategy = keyMatchingStrategy;
this.positionStrategy = positionStrategy;
this.defaultCSN = defaultCSN;
}
/**
* Returns the key matching strategy.
*
* @return the key matching strategy
*/
public KeyMatchingStrategy getKeyMatchingStrategy()
{
return keyMatchingStrategy;
}
/**
* Returns the position strategy.
*
* @return the position strategy
*/
public PositionStrategy getPositionStrategy()
{
return positionStrategy;
}
/**
* Returns the default CSN.
*
* @return the default CSN
*/
public CSN getDefaultCSN()
{
return defaultCSN;
}
@Override
public boolean equals(Object obj)
{
if (this == obj) {
return true;
}
if (obj instanceof CursorOptions) {
CursorOptions other = (CursorOptions) obj;
return keyMatchingStrategy == other.keyMatchingStrategy
&& positionStrategy == other.positionStrategy
&& Objects.equals(defaultCSN, other.defaultCSN);
}
return false;
}
@Override
public int hashCode()
{
final int prime = 31;
int result = 1;
result = prime * result + ((keyMatchingStrategy == null) ? 0 : keyMatchingStrategy.hashCode());
result = prime * result + ((positionStrategy == null) ? 0 : positionStrategy.hashCode());
result = prime * result + ((defaultCSN == null) ? 0 : defaultCSN.hashCode());
return result;
}
@Override
public String toString()
{
return getClass().getSimpleName()
+ " [keyMatchingStrategy=" + keyMatchingStrategy
+ ", positionStrategy=" + positionStrategy
+ ", defaultCSN=" + defaultCSN + "]";
}
}
/**
* Getter for the current record.
*
* @return The current record.
*/
T getRecord();
/**
* Skip to the next record of the database.
*
* @return true if has next, false otherwise
* @throws ChangelogException
* When database exception raised.
*/
boolean next() throws ChangelogException;
/**
* Release the resources and locks used by this Iterator. This method must be
* called when the iterator is no longer used. Failure to do it could cause DB
* deadlock.
*/
@Override
void close();
}