net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IMemberValuePair.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2008 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 /**
  14  * Represents a member-value pair of an annotation.
  15  * The {@link #getValue() value} is represented by an {@link Object}. To get the exact
  16  * type of this object, use its {@link #getValueKind() value kind}. If this value is an array,
  17  * {@link #getValue()} returns an instance of {@link Object}[] and the value kind returns
  18  * the kind of the elements in this array.
  19  * <p>
  20  * This interface is not intended to be implemented or extended by clients.
  21  * </p>
  22  *
  23  * @since 3.4
  24  */
  25 public interface IMemberValuePair {
  26         /**
  27          * Constant indicating that the value kind is an <code>int</code> represented by
  28          * an instance of {@link Integer}.
  29          */
  30         int K_INT = 1;
  31
  32         /**
  33          * Constant indicating that the value kind is a <code>byte</code> represented by
  34          * an instance of {@link Byte}.
  35          */
  36         int K_BYTE = 2;
  37
  38         /**
  39          * Constant indicating that the value kind is a <code>short</code> represented by
  40          * an instance of {@link Short}.
  41          */
  42         int K_SHORT = 3;
  43
  44         /**
  45          * Constant indicating that the value kind is a <code>char</code> represented by
  46          * an instance of {@link Character}.
  47          */
  48         int K_CHAR = 4;
  49
  50         /**
  51          * Constant indicating that the value kind is a <code>float</code> represented by
  52          * an instance of {@link Float}.
  53          */
  54         int K_FLOAT = 5;
  55
  56         /**
  57          * Constant indicating that the value kind is a <code>double</code> represented by
  58          * an instance of {@link Double}.
  59          */
  60         int K_DOUBLE = 6;
  61
  62         /**
  63          * Constant indicating that the value kind is a <code>long</code> represented by
  64          * an instance of {@link Long}.
  65          */
  66         int K_LONG = 7;
  67
  68         /**
  69          * Constant indicating that the value kind is a <code>boolean</code> represented by
  70          * an instance of {@link Boolean}.
  71          */
  72         int K_BOOLEAN = 8;
  73
  74         /**
  75          * Constant indicating that the value kind is a {@link String} represented by
  76          * the corresponding {@link String}.
  77          */
  78         int K_STRING = 9;
  79
  80         /**
  81          * Constant indicating that the value kind is an annotation represented by
  82          * an instance of {@link IAnnotation}.
  83          */
  84         int K_ANNOTATION = 10;
  85
  86         /**
  87          * Constant indicating that the value kind is a {@link Class} represented by
  88          * the name of the class (i.e. a {@link String}. If the member-value pair is coming from
  89          * a compilation unit, this is either a simple name (e.g. for <code>MyType.class</code>,
  90          * the name is "MyType"), or a qualified name  (e.g. for <code>x.y.MyType.MyNestedType.class</code>,
  91          * the name is "x.y.MyType.MyNestedType"). If the member-value pair is coming from a class file, this is
  92          * always a fully qualified name.
  93          * <p>
  94          * Note that one can use {@link IType#resolveType(String)} and e.g.
  95          * {@link IJavaProject#findType(String, String, org.eclipse.core.runtime.IProgressMonitor)}
  96          * to find the corresponding {@link IType}.
  97          * </p>
  98          */
  99         int K_CLASS = 11;
 100
 101         /**
 102          * Constant indicating that the value is a qualified name represented by a
 103          * {@link String}. The qualified name refers to an enum constant or another
 104          * compile-time constant if the code is correct (e.g. "MyEnum.FIRST").
 105          */
 106         int K_QUALIFIED_NAME = 12;
 107
 108         /**
 109          * Constant indicating that the value is a simple name represented by a
 110          * {@link String}. The simple name refers to an enum constant or another
 111          * compile-time constant if the code is correct (e.g. "FIRST" when there is
 112          * a static import for "MyEnum.FIRST").
 113          */
 114         int K_SIMPLE_NAME = 13;
 115
 116         /**
 117          * Constant indicating that the value kind is unknown at this stage. The value is unknown in the
 118          * following cases:
 119          * <ul>
 120          * <li>the value is an expression that would need to be further analyzed to determine its kind. For
 121          * example, in <code>@MyAnnot(1 + 2.3)</code> the kind of the expression "1 + 2.3" is
 122          * unknown</li>
 123          * <li>the value is an array of size 0, e.g. <code>@MyAnnot({})</code></li>
 124          * <li>the value is an array that contains at least one expression that would need to be further
 125          *      analyzed to determine its kind. For example, in <code>@MyAnnot({3.4, 1 + 2.3})</code>,
 126          *      the kind of the second element "1 + 2.3" is unknown.</li>
 127          * <li>the value is an array that contains heterogeneous values, e.g.
 128          *      <code>@MyAnnot(1, 2.3, "abc")</code></li>
 129          * </ul>
 130          * If the value kind is unknown, the returned value is always either <code>null</code>, or an
 131          * array containing {@link Object}s and/or <code>null</code>s for unknown elements.
 132          */
 133         int K_UNKNOWN = 14;
 134
 135         /**
 136          * Returns the member's name of this member-value pair.
 137          *
 138          * @return the member's name of this member-value pair.
 139          */
 140         String getMemberName();
 141
 142         /**
 143          * Returns the value of this member-value pair. The type of this value
 144          * is function of this member-value pair's {@link #getValueKind() value kind}. It is an
 145          * instance of {@link Object}[] if the value is an array.
 146          * <p>
 147          * If the value kind is {@link #K_UNKNOWN} and the value is not an array, then the
 148          * value is <code>null</code>.
 149          * If the value kind is {@link #K_UNKNOWN} and the value is an array, then the
 150          * value is an array containing {@link Object}s and/or <code>null</code>s for
 151          * unknown elements.
 152          * See {@link #K_UNKNOWN} for more details.
 153          * </p>
 154          * @return the value of this member-value pair.
 155          */
 156         Object getValue();
 157
 158         /**
 159          * Returns the value kind of this member-value pair. This indicates the instance of
 160          * the returned {@link #getValue() value}, or the instance of the elements if the value
 161          * is an array. The value kind is one of the following constants:
 162          * {@link #K_ANNOTATION}, {@link #K_BOOLEAN}, {@link #K_BYTE}, {@link #K_CHAR},
 163          * {@link #K_CLASS}, {@link #K_DOUBLE}, {@link #K_FLOAT}, {@link #K_INT}, {@link #K_LONG},
 164          * {@link #K_QUALIFIED_NAME}, {@link #K_SIMPLE_NAME}, {@link #K_SHORT}, {@link #K_STRING},
 165          * {@link #K_UNKNOWN}.
 166          *
 167          * @return the value kind of this member-value pair
 168          */
 169         int getValueKind();
 170
 171 }