nl.topicus.jdbc.shaded.io.opencensus.stats.Measure Maven / Gradle / Ivy

/*
 * Copyright 2017, OpenCensus Authors
 *
 * Licensed 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 nl.topicus.jdbc.shaded.io.opencensus.stats;

import static nl.topicus.jdbc.shaded.com.google.common.base.Preconditions.checkArgument;

import nl.topicus.jdbc.shaded.com.google.auto.value.AutoValue;
import nl.topicus.jdbc.shaded.com.google.common.annotations.VisibleForTesting;
import nl.topicus.jdbc.shaded.io.opencensus.common.Function;
import nl.topicus.jdbc.shaded.io.opencensus.internal.StringUtil;
import nl.topicus.jdbc.shaded.javax.annotation.concurrent.Immutable;

/** The definition of the {@link Measurement} that is taken by OpenCensus library. */
@Immutable
public abstract class Measure {

  @VisibleForTesting static final int NAME_MAX_LENGTH = 255;

  /** Applies the given match function to the underlying data type. */
  public abstract  T match(
      Function p0,
      Function p1,
      Function defaultFunction);

  /**
   * Name of measure, as a {@code String}. Should be a ASCII string with a length no greater than
   * 255 characters.
   *
   * Suggested format for name: {@code /}.
   */
  public abstract String getName();

  /** Detailed description of the measure, used in documentation. */
  public abstract String getDescription();

  /**
   * The units in which {@link Measure} values are measured.
   *
   * 
The suggested grammar for a unit is as follows:
   *
   * 

   *   Expression = Component { "." Component } {"/" Component };
   *   
Component = [ PREFIX ] UNIT [ Annotation ] | Annotation | "1";
   *   
Annotation = "{" NAME "}" ;
   * 
   *
   * For example, string “MBy{transmitted}/ms” stands for megabytes per milliseconds, and the
   * annotation transmitted inside {} is just a comment of the unit.
   */
  // TODO(songya): determine whether we want to check the grammar on string unit.
  public abstract String getUnit();

  // Prevents this class from being subclassed anywhere else.
  private Measure() {}

  /** {@link Measure} with {@code Double} typed values. */
  @Immutable
  @AutoValue
  public abstract static class MeasureDouble extends Measure {

    MeasureDouble() {}

    /**
     * Constructs a new {@link MeasureDouble}.
     *
     * @param name name of {@code Measure}. Suggested format: {@code /}.
     * @param description description of {@code Measure}.
     * @param unit unit of {@code Measure}.
     * @return a {@code MeasureDouble}.
     */
    public static MeasureDouble create(String name, String description, String unit) {
      checkArgument(
          StringUtil.isPrintableString(name) && name.length() <= NAME_MAX_LENGTH,
          "Name should be a ASCII string with a length no greater than "
              + NAME_MAX_LENGTH
              + " characters.");
      return new AutoValue_Measure_MeasureDouble(name, description, unit);
    }

    @Override
    public  T match(
        Function p0,
        Function p1,
        Function defaultFunction) {
      return p0.apply(this);
    }

    @Override
    public abstract String getName();

    @Override
    public abstract String getDescription();

    @Override
    public abstract String getUnit();
  }

  /** {@link Measure} with {@code Long} typed values. */
  @Immutable
  @AutoValue
  public abstract static class MeasureLong extends Measure {

    MeasureLong() {}

    /**
     * Constructs a new {@link MeasureLong}.
     *
     * @param name name of {@code Measure}. Suggested format: {@code /}.
     * @param description description of {@code Measure}.
     * @param unit unit of {@code Measure}.
     * @return a {@code MeasureLong}.
     */
    public static MeasureLong create(String name, String description, String unit) {
      checkArgument(
          StringUtil.isPrintableString(name) && name.length() <= NAME_MAX_LENGTH,
          "Name should be a ASCII string with a length no greater than "
              + NAME_MAX_LENGTH
              + " characters.");
      return new AutoValue_Measure_MeasureLong(name, description, unit);
    }

    @Override
    public  T match(
        Function p0,
        Function p1,
        Function defaultFunction) {
      return p1.apply(this);
    }

    @Override
    public abstract String getName();

    @Override
    public abstract String getDescription();

    @Override
    public abstract String getUnit();
  }
}