com.adobe.granite.timeline.Timeline Maven / Gradle / Ivy

/*************************************************************************
 *
 * ADOBE CONFIDENTIAL
 * __________________
 *
 *  Copyright 2013 Adobe Systems Incorporated
 *  All Rights Reserved.
 *
 * NOTICE:  All information contained herein is, and remains
 * the property of Adobe Systems Incorporated and its suppliers,
 * if any.  The intellectual and technical concepts contained
 * herein are proprietary to Adobe Systems Incorporated and its
 * suppliers and are protected by trade secret or copyright law.
 * Dissemination of this information or reproduction of this material
 * is strictly forbidden unless prior written permission is obtained
 * from Adobe Systems Incorporated.
 **************************************************************************/
package com.adobe.granite.timeline;

import org.apache.sling.api.resource.Resource;

import java.util.List;

/**
 * A Timeline provides a collection of {@link TimelineEvent}s specific to a {@link Resource}. The type of
 * events provided is dependent on the available {@link TimelineEventProvider}s registered in the system. By default the
 * following events are provided:  Versioning Events
 Workflow Events
 Annotation Events
 * 
 A Timeline can be retrieved by adapting a resource as follows: resource.adaptTo(Timeline.class).
 * Any resource can be adapted. Whether events are provided for a resource is decided by the event providers.
 */
public interface Timeline {

    /**
     * Returns the {@link Resource} for which this timeline was created.
     *
     * @return The {@link Resource}.
     */
    Resource getResource();

    /**
     * Returns a {@link List} of all {@link TimelineEvent}s available for the resource backing the timeline. If no
     * events are found, an empty collection is returned. The list is ordered chronologically (most recent last) as per
     * {@link com.adobe.granite.timeline.TimelineEvent#getTime()}. In order to trim the result (e.g. for pagination, use
     * getEvents().subList(start, end).
     *
     * @return A {@link List} of {@link TimelineEvent}s, or an empty collection if no events were found.
     */
    List getEvents();

    /**
     * Returns a subset of events (as provided by {@link #getEvents()}), filtered by the given types. The
     * types by which to filter are provided as an array of {@link TimelineEventType}s. The {@link TimelineAggregator}
     * service provides access to the available types (see {@link com.adobe.granite.timeline.TimelineAggregator#getTypes()}.
     * The list is ordered chronologically (most recent last) as per {@link com.adobe.granite.timeline.TimelineEvent#getTime()}.
     * In order to trim the result (e.g. for pagination, use getEvents(type).subList(start, end).
     *
     * @param types The array of {@link TimelineEventType}s by which to filter events.
     *
     * @return A {@link List} of {@link TimelineEvent}s filtered by type, or an empty list if no events or none of the
     *         given types were found.
     */
    List getEvents(TimelineEventType... types);
}