binding2/mdsal-binding2-generator-api/src/main/java/org/opendaylight/mdsal/binding/javav2/model/api/AnnotationType.java

   1 /*
   2  * Copyright (c) 2017 Cisco Systems, Inc. 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
   9 package org.opendaylight.mdsal.binding.javav2.model.api;
  10
  11 import com.google.common.annotations.Beta;
  12 import com.google.common.collect.ImmutableList;
  13 import java.util.List;
  14 import java.util.NoSuchElementException;
  15
  16 /**
  17  * The Annotation Type interface is designed to hold information about
  18  * annotation for any type that could be annotated in Java. <br>
  19  * For sake of simplicity the Annotation Type is not designed to model exact
  20  * behaviour of annotation mechanism, but just to hold information needed to
  21  * model annotation over java Type definition.
  22  * By using in collections, implementations are expected
  23  * to implement {@link #hashCode()} and {@link #equals(Object)} methods.
  24  *
  25  */
  26 @Beta
  27 public interface AnnotationType extends Type, Comparable<AnnotationType> {
  28
  29     /**
  30      * Returns the List of Annotations. <br>
  31      * Each Annotation Type MAY have defined multiple Annotations.
  32      *
  33      * @return the List of Annotations.
  34      */
  35     List<AnnotationType> getAnnotations();
  36
  37     /**
  38      * Returns Parameter Definition assigned for given parameter name. <br>
  39      * If Annotation does not contain parameter with specified param name, the
  40      * method MAY return <code>null</code> value.
  41      *
  42      * @param paramName
  43      *            Parameter Name
  44      * @return Parameter Definition assigned for given parameter name.
  45      */
  46     Parameter getParameter(final String paramName);
  47
  48     /**
  49      * Returns List of all parameters assigned to Annotation Type.
  50      *
  51      * @return List of all parameters assigned to Annotation Type.
  52      */
  53     List<Parameter> getParameters();
  54
  55     /**
  56      * Returns List of parameter names.
  57      *
  58      * @return List of parameter names.
  59      */
  60     List<String> getParameterNames();
  61
  62     /**
  63      * Returns <code>true</code> if annotation contains parameters.
  64      *
  65      * @return <code>true</code> if annotation contains parameters.
  66      */
  67     default boolean containsParameters() {
  68         return !getParameters().isEmpty();
  69     }
  70
  71     @Override
  72     boolean equals(Object o);
  73
  74     @Override
  75     int hashCode();
  76
  77     @Override
  78     int compareTo(AnnotationType o);
  79
  80     /**
  81      * Annotation Type parameter interface. For simplicity the Parameter
  82      * contains values and value types as Strings. Every annotation which
  83      * contains parameters could contain either single parameter or array of
  84      * parameters. To model this purposes the by contract if the parameter
  85      * contains single parameter the {@link #getValues()} method will return
  86      * empty List and {@link #getSingleValue()} MUST always return non-
  87      * <code>null</code> parameter. If the Parameter holds List of values the
  88      * singular {@link #getSingleValue()} parameter MAY return <code>null</code>
  89      * value.
  90      */
  91
  92     @Beta
  93     interface Parameter {
  94
  95         /**
  96          * Returns the Name of the parameter.
  97          *
  98          * @return the Name of the parameter.
  99          */
 100         String getName();
 101
 102         /**
 103          * Returns value in String format if Parameter contains singular value,
 104          * otherwise should return first value only. Implementation should throw
 105          * exception if there is no value to return.
 106          *
 107          * @return value in String format.
 108          * @throws NoSuchElementException If such value not found
 109          */
 110         String getSingleValue();
 111
 112         /**
 113          * Returns List of Parameter assigned values in order in which they were
 114          * assigned for given parameter name. <br>
 115          * If there are multiple values assigned for given parameter name the
 116          * method MUST NOT return empty List.
 117          * As we consider getSingleValue() as a primary method, default
 118          * implementation of getValues() is provided here.
 119          *
 120          * @return List of Parameter assigned values in order in which they were
 121          *         assigned for given parameter name.
 122          */
 123         default List<String> getValues() {
 124             return ImmutableList.of(getSingleValue());
 125         }
 126     }
 127 }