/**
 * 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.hadoop.yarn.server.timelineservice.storage;

import java.io.IOException;

import java.util.Set;
import org.apache.hadoop.classification.InterfaceAudience.Private;
import org.apache.hadoop.classification.InterfaceStability.Unstable;
import org.apache.hadoop.service.Service;
import org.apache.hadoop.yarn.api.records.timelineservice.TimelineEntity;
import org.apache.hadoop.yarn.server.timelineservice.reader.TimelineDataToRetrieve;
import org.apache.hadoop.yarn.server.timelineservice.reader.TimelineEntityFilters;
import org.apache.hadoop.yarn.server.timelineservice.reader.TimelineReaderContext;

/** ATSv2 reader interface. */
@Private
@Unstable
public interface TimelineReader extends Service {

  /**
   * Possible fields to retrieve for {@link #getEntities} and
   * {@link #getEntity}.
   */
  public enum Field {
    ALL,
    EVENTS,
    INFO,
    METRICS,
    CONFIGS,
    RELATES_TO,
    IS_RELATED_TO
  }

  /**
   * <p>The API to fetch the single entity given the identifier(depending on
   * the entity type) in the scope of the given context.</p>
   * @param context Context which defines the scope in which query has to be
   *    made. Use getters of {@link TimelineReaderContext} to fetch context
   *    fields. Context contains the following :<br>
   *    <ul>
   *    <li><b>entityType</b> - Entity type(mandatory).</li>
   *    <li><b>clusterId</b> - Identifies the cluster(mandatory).</li>
   *    <li><b>userId</b> - Identifies the user.</li>
   *    <li><b>flowName</b> - Context flow name.</li>
   *    <li><b>flowRunId</b> - Context flow run id.</li>
   *    <li><b>appId</b> - Context app id.</li>
   *    <li><b>entityId</b> - Entity id.</li>
   *    </ul>
   *    Fields in context which are mandatory depends on entity type. Entity
   *    type is always mandatory. In addition to entity type, below is the list
   *    of context fields which are mandatory, based on entity type.<br>
   *    <ul>
   *    <li>If entity type is YARN_FLOW_RUN (i.e. query to fetch a specific flow
   *    run), clusterId, userId, flowName and flowRunId are mandatory.</li>
   *    <li>If entity type is YARN_APPLICATION (i.e. query to fetch a specific
   *    app), query is within the scope of clusterId, userId, flowName,
   *    flowRunId and appId. But out of this, only clusterId and appId are
   *    mandatory. If only clusterId and appId are supplied, backend storage
   *    must fetch the flow context information i.e. userId, flowName and
   *    flowRunId first and based on that, fetch the app. If flow context
   *    information is also given, app can be directly fetched.
   *    </li>
   *    <li>For other entity types (i.e. query to fetch generic entity), query
   *    is within the scope of clusterId, userId, flowName, flowRunId, appId,
   *    entityType and entityId. But out of this, only clusterId, appId,
   *    entityType and entityId are mandatory. If flow context information is
   *    not supplied, backend storage must fetch the flow context information
   *    i.e. userId, flowName and flowRunId first and based on that, fetch the
   *    entity. If flow context information is also given, entity can be
   *    directly queried.
   *    </li>
   *    </ul>
   * @param dataToRetrieve Specifies which data to retrieve for the entity. Use
   *    getters of TimelineDataToRetrieve class to fetch dataToRetrieve
   *    fields. All the dataToRetrieve fields are optional. Refer to
   *    {@link TimelineDataToRetrieve} for details.
   * @return A <cite>TimelineEntity</cite> instance or null. The entity will
   *    contain the metadata plus the given fields to retrieve.<br>
   *    If entityType is YARN_FLOW_RUN, entity returned is of type
   *    <cite>FlowRunEntity</cite>.<br>
   *    For all other entity types, entity returned is of type
   *    <cite>TimelineEntity</cite>.
   * @throws IOException if there is an exception encountered while fetching
   *    entity from backend storage.
   */
  TimelineEntity getEntity(TimelineReaderContext context,
      TimelineDataToRetrieve dataToRetrieve) throws IOException;

  /**
   * <p>The API to search for a set of entities of the given entity type in
   * the scope of the given context which matches the given predicates. The
   * predicates include the created time window, limit to number of entities to
   * be returned, and the entities can be filtered by checking whether they
   * contain the given info/configs entries in the form of key/value pairs,
   * given metrics in the form of metricsIds and its relation with metric
   * values, given events in the form of the Ids, and whether they relate to/are
   * related to other entities. For those parameters which have multiple
   * entries, the qualified entity needs to meet all or them.</p>
   *
   * @param context Context which defines the scope in which query has to be
   *    made. Use getters of {@link TimelineReaderContext} to fetch context
   *    fields. Context contains the following :<br>
   *    <ul>
   *    <li><b>entityType</b> - Entity type(mandatory).</li>
   *    <li><b>clusterId</b> - Identifies the cluster(mandatory).</li>
   *    <li><b>userId</b> - Identifies the user.</li>
   *    <li><b>flowName</b> - Context flow name.</li>
   *    <li><b>flowRunId</b> - Context flow run id.</li>
   *    <li><b>appId</b> - Context app id.</li>
   *    </ul>
   *    Although entityIdPrefix and entityId are also part of context,
   *    it has no meaning for getEntities.<br>
   *    Fields in context which are mandatory depends on entity type. Entity
   *    type is always mandatory. In addition to entity type, below is the list
   *    of context fields which are mandatory, based on entity type.<br>
   *    <ul>
   *    <li>If entity type is YARN_FLOW_ACTIVITY (i.e. query to fetch flows),
   *    only clusterId is mandatory.
   *    </li>
   *    <li>If entity type is YARN_FLOW_RUN (i.e. query to fetch flow runs),
   *    clusterId, userId and flowName are mandatory.</li>
   *    <li>If entity type is YARN_APPLICATION (i.e. query to fetch apps), we
   *    can either get all apps within the context of flow name or within the
   *    context of flow run. If apps are queried within the scope of flow name,
   *    clusterId, userId and flowName are supplied. If they are queried within
   *    the scope of flow run, clusterId, userId, flowName and flowRunId are
   *    supplied.</li>
   *    <li>For other entity types (i.e. query to fetch generic entities), query
   *    is within the scope of clusterId, userId, flowName, flowRunId, appId and
   *    entityType. But out of this, only clusterId, appId and entityType are
   *    mandatory. If flow context information is not supplied, backend storage
   *    must fetch the flow context information i.e. userId, flowName and
   *    flowRunId first and based on that, fetch the entities. If flow context
   *    information is also given, entities can be directly queried.
   *    </li>
   *    </ul>
   * @param filters Specifies filters which restrict the number of entities
   *    to return. Use getters of TimelineEntityFilters class to fetch
   *    various filters. All the filters are optional. Refer to
   *    {@link TimelineEntityFilters} for details.
   * @param dataToRetrieve Specifies which data to retrieve for each entity. Use
   *    getters of TimelineDataToRetrieve class to fetch dataToRetrieve
   *    fields. All the dataToRetrieve fields are optional. Refer to
   *    {@link TimelineDataToRetrieve} for details.
   * @return A set of <cite>TimelineEntity</cite> instances of the given entity
   *    type in the given context scope which matches the given predicates
   *    ordered by enitityIdPrefix(for generic entities only).
   *    Each entity will only contain
   *    the metadata(id, type , idPrefix and created time) plus the given
   *    fields to retrieve.
   *    <br>
   *    If entityType is YARN_FLOW_ACTIVITY, entities returned are of type
   *    <cite>FlowActivityEntity</cite>.<br>
   *    If entityType is YARN_FLOW_RUN, entities returned are of type
   *    <cite>FlowRunEntity</cite>.<br>
   *    For all other entity types, entities returned are of type
   *    <cite>TimelineEntity</cite>.
   * @throws IOException if there is an exception encountered while fetching
   *    entity from backend storage.
   */
  Set<TimelineEntity> getEntities(
      TimelineReaderContext context,
      TimelineEntityFilters filters,
      TimelineDataToRetrieve dataToRetrieve) throws IOException;

  /**
   * The API to list all available entity types of the given context.
   *
   * @param context A context defines the scope of this query. The incoming
   * context should contain at least the cluster id and application id.
   *
   * @return A set of entity types available in the given context.
   *
   * @throws IOException if an exception occurred while listing from backend
   * storage.
   */
  Set<String> getEntityTypes(TimelineReaderContext context) throws IOException;
}