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