/*
 * 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.beam.sdk.transforms.display;

import org.apache.beam.sdk.options.PipelineOptions;
import org.apache.beam.sdk.transforms.PTransform;

/**
 * Marker interface for {@link PTransform PTransforms} and components to specify display data used
 * within UIs and diagnostic tools.
 *
 * <p>Display data is registered by overriding
 * {@link #populateDisplayData(DisplayData.Builder)} in a component which implements
 * {@code HasDisplayData}. Display data is available for {@link PipelineOptions} and
 * {@link PTransform} implementations.
 *
 * <pre><code>{@literal @Override}
 * public void populateDisplayData(DisplayData.Builder builder) {
 *  super.populateDisplayData(builder);
 *
 *  builder
 *     .include(subComponent)
 *     .add(DisplayData.item("minFilter", 42))
 *     .addIfNotDefault(DisplayData.item("useTransactions", this.txn), false)
 *     .add(DisplayData.item("topic", "projects/myproject/topics/mytopic")
 *       .withLabel("Pub/Sub Topic"))
 *     .add(DisplayData.item("serviceInstance", "myservice.com/fizzbang")
 *       .withLinkUrl("http://www.myservice.com/fizzbang"));
 * }
 * </code></pre>
 *
 * <p>Display data is optional and may be collected during pipeline construction. It should
 * only be used for informational purposes. Tools and components should not assume that display data
 * will always be collected, or that collected display data will always be displayed.
 *
 * @see #populateDisplayData(DisplayData.Builder)
 */
public interface HasDisplayData {
  /**
   * Register display data for the given transform or component.
   *
   * <p>{@code populateDisplayData(DisplayData.Builder)} is invoked by Pipeline runners to collect
   * display data via {@link DisplayData#from(HasDisplayData)}. Implementations may call
   * {@code super.populateDisplayData(builder)} in order to register display data in the current
   * namespace, but should otherwise use {@code subcomponent.populateDisplayData(builder)} to use
   * the namespace of the subcomponent.
   *
   * @param builder The builder to populate with display data.
   *
   * @see HasDisplayData
   */
  void populateDisplayData(DisplayData.Builder builder);
}