yang/yang-common/src/main/java/org/opendaylight/yangtools/yang/common/CanonicalValueSupport.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 static java.util.Objects.requireNonNull;
  11
  12 import com.google.common.annotations.Beta;
  13 import org.eclipse.jdt.annotation.NonNullByDefault;
  14 import org.opendaylight.yangtools.concepts.Variant;
  15
  16 /**
  17  * Support for a {@link CanonicalValue} subclasses. An implementation of this interface must be registered
  18  * in the system and be available from each CanonicalValue object.
  19  *
  20  * <p>
  21  * Note: never implement this interface directly, subclass {@link AbstractCanonicalValueSupport} instead.
  22  *
  23  * <p>
  24  * This interface allows a {@link CanonicalValue} to be instantiated from a String. The implementation is expected
  25  * to perform all checks implied by the corresponding YANG data model.
  26  *
  27  * @param <T> canonical value type
  28  * @author Robert Varga
  29  */
  30 @Beta
  31 @NonNullByDefault
  32 public interface CanonicalValueSupport<T extends CanonicalValue<T>> extends CanonicalValueValidator<T, T> {
  33     /**
  34      * Create a instance for a string representation. Implementations of this method are required to perform checks
  35      * equivalent to the YANG data model restrictions attached to the corresponding YANG type. Non-canonical format
  36      * strings must be accepted and result in objects equal to objects obtained from the corresponding canonical format.
  37      *
  38      * @param str String representation
  39      * @return A {@link CanonicalValue} instance or CanonicalValueViolation if {@code str} does not conform
  40      * @throws NullPointerException if {@code str} is null
  41      */
  42     Variant<T, CanonicalValueViolation> fromString(String str);
  43
  44     /**
  45      * Create a instance for the canonical string representation. Implementations of this method may perform
  46      * optimizations based on the assumption the string is canonical, but should still report errors when a mismatch
  47      * is detected.
  48      *
  49      * @param str String representation
  50      * @return A {@link CanonicalValue} instance or CanonicalValueViolation if {@code str} does not conform
  51      * @throws NullPointerException if {@code str} is null
  52      */
  53     default Variant<T, CanonicalValueViolation> fromCanonicalString(final String str) {
  54         return fromString(requireNonNull(str));
  55     }
  56
  57     /**
  58      * Unsafe cast to a factory type.
  59      *
  60      * @return This instance cast to specified type
  61      */
  62     @SuppressWarnings("unchecked")
  63     default <X extends CanonicalValue<X>> CanonicalValueSupport<X> unsafe() {
  64         return (CanonicalValueSupport<X>) this;
  65     }
  66 }