/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.ambari.metrics.timeline;

import java.io.IOException;
import java.util.Collection;
import java.util.EnumSet;
import java.util.Set;
import java.util.SortedSet;

import org.apache.hadoop.classification.InterfaceAudience;
import org.apache.hadoop.classification.InterfaceStability;
import org.apache.hadoop.yarn.api.records.timeline.TimelineEntities;
import org.apache.hadoop.yarn.api.records.timeline.TimelineEntity;
import org.apache.hadoop.yarn.api.records.timeline.TimelineEvents;

/**
 * This interface is for retrieving timeline information.
 */
@InterfaceAudience.Private
@InterfaceStability.Unstable
public interface TimelineReader {

  /**
   * Possible fields to retrieve for {@link #getEntities} and {@link #getEntity}
   * .
   */
  enum Field {
    EVENTS,
    RELATED_ENTITIES,
    PRIMARY_FILTERS,
    OTHER_INFO,
    LAST_EVENT_ONLY
  }

  /**
   * Default limit for {@link #getEntities} and {@link #getEntityTimelines}.
   */
  final long DEFAULT_LIMIT = 100;

  /**
   * This method retrieves a list of entity information, {@link TimelineEntity},
   * sorted by the starting timestamp for the entity, descending. The starting
   * timestamp of an entity is a timestamp specified by the client. If it is not
   * explicitly specified, it will be chosen by the store to be the earliest
   * timestamp of the events received in the first put for the entity.
   * 
   * @param entityType
   *          The type of entities to return (required).
   * @param limit
   *          A limit on the number of entities to return. If null, defaults to
   *          {@link #DEFAULT_LIMIT}.
   * @param windowStart
   *          The earliest start timestamp to retrieve (exclusive). If null,
   *          defaults to retrieving all entities until the limit is reached.
   * @param windowEnd
   *          The latest start timestamp to retrieve (inclusive). If null,
   *          defaults to {@link Long#MAX_VALUE}
   * @param fromId
   *          If fromId is not null, retrieve entities earlier than and
   *          including the specified ID. If no start time is found for the
   *          specified ID, an empty list of entities will be returned. The
   *          windowEnd parameter will take precedence if the start time of this
   *          entity falls later than windowEnd.
   * @param fromTs
   *          If fromTs is not null, ignore entities that were inserted into the
   *          store after the given timestamp. The entity's insert timestamp
   *          used for this comparison is the store's system time when the first
   *          put for the entity was received (not the entity's start time).
   * @param primaryFilter
   *          Retrieves only entities that have the specified primary filter. If
   *          null, retrieves all entities. This is an indexed retrieval, and no
   *          entities that do not match the filter are scanned.
   * @param secondaryFilters
   *          Retrieves only entities that have exact matches for all the
   *          specified filters in their primary filters or other info. This is
   *          not an indexed retrieval, so all entities are scanned but only
   *          those matching the filters are returned.
   * @param fieldsToRetrieve
   *          Specifies which fields of the entity object to retrieve (see
   *          {@link Field}). If the set of fields contains
   *          {@link Field#LAST_EVENT_ONLY} and not {@link Field#EVENTS}, the
   *          most recent event for each entity is retrieved. If null, retrieves
   *          all fields.
   * @return An {@link TimelineEntities} object.
   * @throws IOException
   */
  TimelineEntities getEntities(String entityType,
      Long limit, Long windowStart, Long windowEnd, String fromId, Long fromTs,
      NameValuePair primaryFilter, Collection<NameValuePair> secondaryFilters,
      EnumSet<Field> fieldsToRetrieve) throws IOException;

  /**
   * This method retrieves the entity information for a given entity.
   * 
   * @param entityId
   *          The entity whose information will be retrieved.
   * @param entityType
   *          The type of the entity.
   * @param fieldsToRetrieve
   *          Specifies which fields of the entity object to retrieve (see
   *          {@link Field}). If the set of fields contains
   *          {@link Field#LAST_EVENT_ONLY} and not {@link Field#EVENTS}, the
   *          most recent event for each entity is retrieved. If null, retrieves
   *          all fields.
   * @return An {@link TimelineEntity} object.
   * @throws IOException
   */
  TimelineEntity getEntity(String entityId, String entityType, EnumSet<Field>
      fieldsToRetrieve) throws IOException;

  /**
   * This method retrieves the events for a list of entities all of the same
   * entity type. The events for each entity are sorted in order of their
   * timestamps, descending.
   * 
   * @param entityType
   *          The type of entities to retrieve events for.
   * @param entityIds
   *          The entity IDs to retrieve events for.
   * @param limit
   *          A limit on the number of events to return for each entity. If
   *          null, defaults to {@link #DEFAULT_LIMIT} events per entity.
   * @param windowStart
   *          If not null, retrieves only events later than the given time
   *          (exclusive)
   * @param windowEnd
   *          If not null, retrieves only events earlier than the given time
   *          (inclusive)
   * @param eventTypes
   *          Restricts the events returned to the given types. If null, events
   *          of all types will be returned.
   * @return An {@link TimelineEvents} object.
   * @throws IOException
   */
  TimelineEvents getEntityTimelines(String entityType,
      SortedSet<String> entityIds, Long limit, Long windowStart,
      Long windowEnd, Set<String> eventTypes) throws IOException;
}