yang/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/CanonicalValueValidator.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 org.eclipse.jdt.annotation.NonNullByDefault;
  12 import org.opendaylight.yangtools.concepts.Either;
  13 import org.opendaylight.yangtools.concepts.Immutable;
  14
  15 /**
  16  * {@link CanonicalValue} validator interface. Implementations of this interface can perform further validation of
  17  * representation state such that it conforms to a YANG type derived from a type with a {@link CanonicalValue}
  18  * representation.
  19  *
  20  * <p>
  21  * Note: this interface should not be directly implemented. Use {@link AbstractCanonicalValueValidator} instead.
  22  *
  23  * @param <T> canonical value type
  24  * @param <V> validated canonical value type
  25  * @author Robert Varga
  26  */
  27 @Beta
  28 @NonNullByDefault
  29 public interface CanonicalValueValidator<T extends CanonicalValue<T>, V extends T> extends Immutable {
  30     /**
  31      * Returns the instantiated representation class. The representation class is a {@link CanonicalValue} which
  32      * understands the semantics of modeled data and has some internal representation of it. All {@link CanonicalValue}s
  33      * which share the same representation class are considered equal if their internal state would result in the
  34      * same canonical string representation as defined by the YANG data model.
  35      *
  36      * @return Representation {@link CanonicalValue} class.
  37      */
  38     Class<T> getRepresentationClass();
  39
  40     /**
  41      * Return the class which captures the fact it was validated by this validator.
  42      *
  43      * @return Validated capture of the representation class.
  44      */
  45     Class<V> getValidatedRepresentationClass();
  46
  47     /**
  48      * Validate a {@link CanonicalValue} representation. Implementations should override this method if they can
  49      * provide a validation algorithm which does not rely on canonical strings but works on representation state only.
  50      *
  51      * @param value Representation value
  52      * @return Validated representation or a {@link CanonicalValueViolation}
  53      * @throws NullPointerException if {@code value} is null
  54      */
  55     default Either<T, CanonicalValueViolation> validateRepresentation(final T value) {
  56         return validateRepresentation(value, value.toCanonicalString());
  57     }
  58
  59     /**
  60      * Validate a {@link CanonicalValue} representation. Implementations can chose whether they operate on
  61      * representation state or canonical string -- both are considered equivalent. Users should call this method if they
  62      * have a representation readily available.
  63      *
  64      * @param value Representation value
  65      * @param canonicalString Canonical string matching the representation value
  66      * @return Validated representation or a {@link CanonicalValueViolation}
  67      * @throws NullPointerException if {@code value} or {@code canonicalString} is null.
  68      */
  69     Either<T, CanonicalValueViolation> validateRepresentation(T value, String canonicalString);
  70 }