common/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/CanonicalValue.java

   1 /*
   2  * Copyright (c) 2018 Pantheon Technologies, s.r.o. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.yangtools.yang.common;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.io.Serializable;
  12 import org.eclipse.jdt.annotation.NonNullByDefault;
  13 import org.opendaylight.yangtools.concepts.Immutable;
  14
  15 /**
  16  * A typed value in its internal Java representation. Implementations of this interface are required to:
  17  * <ul>
  18  * <li>be immutable</li>
  19  * <li>be {@link Serializable}</li>
  20  * <li>accurately define total ordering of values</li>
  21  * </ul>
  22  *
  23  * <p>
  24  * Aside from providing the ability to hold a canonical value, this interface and its implementations support carrying
  25  * additional information about how the value has been validated -- allowing efficient interchange of already-validated
  26  * values between users. {@link #validator()} provides the link to a {@link CanonicalValueValidator} which has declared
  27  * the value conform to it. Users can query the validator to establish whether the value needs to be further validated
  28  * to conform to their requirement.
  29  *
  30  * @param <T> Canonical value type
  31  * @author Robert Varga
  32  */
  33 @Beta
  34 @NonNullByDefault
  35 public interface CanonicalValue<T extends CanonicalValue<T>> extends Comparable<T>, Immutable, Serializable {
  36     /**
  37      * Return the canonical string representation of this value.
  38      *
  39      * @return Canonical string
  40      */
  41     String toCanonicalString();
  42
  43     /**
  44      * Return the {@link CanonicalValue} associated with this type. It can be used to create new instances of this
  45      * representation.
  46      *
  47      * @return A {@link CanonicalValue} instance.
  48      */
  49     CanonicalValueSupport<T> support();
  50
  51     /**
  52      * Return a {@link CanonicalValueValidator} associated with this value's validated type.
  53      *
  54      * @return A {@link CanonicalValueValidator} instance.
  55      */
  56     default CanonicalValueValidator<T, ? extends T> validator() {
  57         return support();
  58     }
  59 }