TimelineIndex.java

/**
 * Copyright (c) 2002-2010 "Neo Technology,"
 * Network Engine for Objects in Lund AB [http://neotechnology.com]
 *
 * This file is part of Neo4j.
 *
 * Neo4j is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

package org.neo4j.index.timeline;

import org.neo4j.graphdb.Node;

/**
 * A utility for ordering nodes in a timeline. You add nodes to the timeline and
 * then you can query for nodes given a time period, w/ or w/o lower/upper
 * bounds, for example "Give me all nodes before this given timestamp" or
 * "Give me all nodes between these two timestamps".
 * 
 * Please note that the timestamps don't need to represent actual points in
 * time, any <code>long</code> that identifies the indexed {@link Node} and
 * defines its global order is fine.
 */
public interface TimelineIndex
{
    /**
     * Returns the last node in the timeline, that is the node with the highest
     * timestamp or {@code null} if there's no nodes in the timeline.
     * 
     * @return the last node in the timeline or {@code null} if timeline is
     *         empty.
     */
    Node getLastNode();

    /**
     * Returns the first node in the timeline, that is the node with the lowest
     * timestamp or {@code null} if there's no nodes in the timeline.
     * 
     * @return the first node in the timeline or {@code null} if timeline is
     *         empty.
     */
    Node getFirstNode();

    /**
     * Removes a node from the timeline. It will throw an exception if {@code
     * nodeToRemove} isn't added in this timeline.
     * 
     * @param nodeToRemove the node to remove from this timeline
     * @throws IllegalArgumentException if {@code null} node or node not
     *             connected to this timeline.
     */
    void removeNode( Node nodeToRemove );

    /**
     * Adds a node to this timeline with the given {@code timestamp}.
     * 
     * @param nodeToAdd the node to add to this timeline.
     * @param timestamp the timestamp to use
     * @throws IllegalArgumentException if already added to this timeline or
     *             {@code null} node.
     */
    void addNode( Node nodeToAdd, long timestamp );

    /**
     * Returns nodes which were added with the given {@code timestamp}.
     * 
     * @param timestamp the timestamp to get nodes for.
     * @return nodes which were added with the given {@code timestamp}.
     */
    Iterable<Node> getNodes( long timestamp );

    /**
     * Returns all added nodes in this timeline ordered by increasing timestamp.
     * 
     * @return all the nodes in the timeline ordered by increasing timestamp.
     */
    Iterable<Node> getAllNodes();

    /**
     * Returns all the nodes after (exclusive) {@code timestamp} ordered by
     * increasing timestamp.
     * 
     * @param timestamp the timestamp value, nodes with greater timestamp value
     *            will be returned.
     * @return all nodes after (exclusive) {@code timestamp} ordered by
     *         increasing timestamp.
     */
    Iterable<Node> getAllNodesAfter( long timestamp );

    /**
     * Returns all the nodes before (exclusive) {@code timestamp} ordered by
     * increasing timestamp.
     * 
     * @param timestamp the timestamp value, nodes with lesser timestamp value
     *            will be returned.
     * @return all nodes before (exclusive) {@code timestamp} ordered by
     *         increasing timestamp.
     */
    Iterable<Node> getAllNodesBefore( long timestamp );

    /**
     * Returns all the nodes after (exclusive) {@code afterTimestamp} and before
     * (exclusive) {@code beforeTimestamp} ordered by increasing timestamp.
     * 
     * @param startTimestamp the start timestamp, nodes with greater timestamp
     *            value will be returned.
     * @param endTimestamp the end timestamp, nodes with lesser timestamp value
     *            will be returned.
     * @return all nodes between (exclusive) the specified timestamps ordered by
     *         increasing timestamp.
     */
    Iterable<Node> getAllNodesBetween( long startTimestamp, long endTimestamp );

    /**
     * Convenience method which you can use {@link #getAllNodes()},
     * {@link #getAllNodesAfter(long)}, {@link #getAllNodesBefore(long)} and
     * {@link #getAllNodesBetween(long, long)} in a single method.
     * 
     * @param startTimestampOrNull the start timestamp, nodes with greater
     *            timestamp value will be returned. Will be ignored if {@code
     *            null}.
     * @param endTimestampOrNull the end timestamp, nodes with lesser timestamp
     *            value will be returned. Will be ignored if {@code null}.
     * @return all nodes in this timeline ordered by timestamp. A range can be
     *         given with the {@code startTimestampOrNull} and/or {@code
     *         endTimestampOrNull} (where {@code null} means no restriction).
     */
    Iterable<Node> getAllNodes( Long startTimestampOrNull,
            Long endTimestampOrNull );

    /**
     * Will return the timestamp for {@code node} if it has been added to this
     * timeline. If {@code node} hasn't been added to this timeline a runtime
     * exception will be thrown.
     * 
     * @param node the node to return the timestamp for.
     * @return the timestamp for {@code node}.
     */
    long getTimestampForNode( Node node );

    /**
     * Deletes this timeline. Nodes added to the timeline will not be deleted,
     * they are just disconnected from this timeline.
     */
    void delete();
}