2 * Copyright (c) 2018 Pantheon Technologies, s.r.o. and others. All rights reserved.
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
8 package org.opendaylight.yangtools.yang.common;
10 import com.google.common.annotations.Beta;
11 import java.io.Serial;
12 import org.eclipse.jdt.annotation.NonNullByDefault;
13 import org.eclipse.jdt.annotation.Nullable;
16 * Abstract base class for objects which are string-equivalent to canonical string representation specified
17 * in a YANG model. Note that each subclass of {@link DerivedString} defines its own {@link #hashCode()} and
18 * {@link #equals(Object)} contracts based on implementation particulars.
21 * Given the following YANG snippet:
25 * pattern "[1-9]?[0-9]";
30 * patter "[1-9][0-9]";
37 * it is obvious we could use a storage class with 'int' as the internal representation of all three types and define
38 * operations on top of it. In this case we would define:
40 * <li>{@code public class FooDerivedString extends DerivedString<FooDerivedString>}, which implements all abstract
41 * methods of {@link DerivedString} as final methods. It will notably not override {@link #validator()} and
42 * must not be final.</li>
43 * <li>{@code public final class FooDerivedStringSupport extends DerivedStringSupport<FooDerivedString>}, which
44 * forms the baseline validator and instantiation for {@code FooDerivedString}. It should be a singleton class
45 * with a getInstance() method.</li>
46 * <li>{@code public class BarDerivedString extends FooDerivedString}, which overrides {@link #validator()} to
47 * indicate its contents have been validated to conform to bar -- it does that by returning the singleton
48 * instance of {@code BarDerivedStringValidator}.</li>
49 * <li>{@code public final class BarDerivedStringValidator extends DerivedStringValidator<FooDerivedString,
50 * BarDerivedString}. This method needs to notably implement
51 * {@link CanonicalValueValidator#validateRepresentation(CanonicalValue)} to hand out BarDerivedString
52 * instances. This class needs to be a singleton with a getInstance() method, too.</li>
54 * Since {@code baz} is not defining any new restrictions, all instances of FooDerivedString are valid for it and we
55 * do not have to define any additional support.
58 * It is important for {@link DerivedString} subclasses not to be final because any YANG type can be further extended
59 * and adding a final class in that hierarchy would prevent a proper class from being defined.
61 * @param <T> derived string representation
62 * @author Robert Varga
66 public abstract class DerivedString<T extends DerivedString<T>> implements CanonicalValue<T> {
68 private static final long serialVersionUID = 1L;
71 public abstract int hashCode();
74 public abstract boolean equals(@Nullable Object obj);
77 public final String toString() {
78 return toCanonicalString();