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