001package Torello.JavaDoc; 002 003import com.sun.source.tree.Tree; 004 005/** 006 * Entity: Exhaustive list of all items that may be defined inside of a Java Type. 007 * 008 * <BR /><BR /> 009 * <EMBED CLASS='external-html' DATA-FILE-ID=ENTITY> 010 */ 011public enum Entity 012{ 013 /** Denotes Field(s) */ 014 FIELD( 015 Torello.JavaDoc.Field.class, 016 com.sun.source.tree.VariableTree.class, 017 "FD", 018 "==== FIELD SUMMARY ====", 019 "==== FIELD DETAIL ====" 020 ), 021 022 /** Denotes Method(s). */ 023 METHOD( 024 Torello.JavaDoc.Method.class, 025 com.sun.source.tree.MethodTree.class, 026 "MD", 027 "==== METHOD SUMMARY ====", 028 "==== METHOD DETAIL ====" 029 ), 030 031 /** Denotes Constructor(s). */ 032 CONSTRUCTOR( 033 Torello.JavaDoc.Constructor.class, 034 com.sun.source.tree.MethodTree.class, 035 "CO", 036 "==== CONSTRUCTOR SUMMARY ====", 037 "==== CONSTRUCTOR DETAIL ====" 038 ), 039 040 /** 041 * Used for the 'Elements' - which <I>must be located</I> inside an Annotation Definition - but 042 * <I>are not always required or mandatory</I>. Only an <CODE>@interface</CODE> 043 * ({@code Annotation}) may have "Annotation Elements". 044 * 045 * <BR /><BR /><B CLASS=JDDescLabel>Optional & Required:</B> 046 * 047 * <BR />Because there are two types of Annotation-Members (option & required - where 048 * <I>optional elements have a <CODE>default value</CODE> assigned!</I>), null is assigned to 049 * the {@code String}-Field {@link #jdSummaryMarker}. 050 * 051 * <BR /><BR />Java puts both types of Annotation-Members in the same details-section on a Java 052 * Doc Web-Page. Therefore there is only one Detail-Section HTML-Comment Marker, and that 053 * {@code public} & {@code final} {@code String}-field (@link #jdDetailMarker) is non-null, 054 * and provided by this constant. 055 */ 056 ANNOTATION_ELEM( 057 Torello.JavaDoc.AnnotationElem.class, 058 com.sun.source.tree.MethodTree.class, 059 "AE", 060 null, // There are **TWO** Annotation-Member Summary-Sections (and, therefore, two markers) 061 "==== ANNOTATION TYPE MEMBER DETAIL ====" 062 ), 063 064 /** 065 * Used for the Enumerated-Constants. These are the Java-Identifiers which may only be found 066 * inside a Java {@code 'enum'}. 067 */ 068 ENUM_CONSTANT( 069 Torello.JavaDoc.EnumConstant.class, 070 com.sun.source.tree.VariableTree.class, 071 "EC", 072 "==== ENUM CONSTANT SUMMARY ====", 073 "==== ENUM CONSTANT DETAIL ====" 074 ), 075 076 /** 077 * Denotes Static inner-class(es), inner-interface(s), inner-enums, etc. 078 */ 079 INNER_CLASS( 080 Torello.JavaDoc.NestedType.class, 081 com.sun.source.tree.ClassTree.class, 082 "NT", 083 "==== NESTED CLASS SUMMARY ====", 084 null // Nested-Types / Inner-Classes get their full-and-complete own pages. They do not 085 // have a "Details Section". (Therefore there is no HTML-Comment Marker for them!) 086 ); 087 088 089 // ******************************************************************************************** 090 // ******************************************************************************************** 091 // Reflection / Type java.lang.Class public constants 092 // ******************************************************************************************** 093 // ******************************************************************************************** 094 095 096 /** 097 * <EMBED CLASS='external-html' DATA-FILE-ID=ENTITYFIELD> 098 * 099 * <BR /><BR />The <CODE>Class<? extends {@link Declaration}></CODE> instance stored in 100 * this <B>'Type Mirror'</B> field is just the actual <B>{@code java.lang.class}</B> of one of 101 * the six CIET-Types. Specifically this field will always evaluate to one of the following 102 * values: 103 * 104 * <BR /><BR /><TABLE CLASS='JDBriefTable MONO-SPACE-TABLE'> 105 * <TR><TH>Constant</TH> <TH>Ugrader Reflection Class</TH></TR> 106 * <TR><TD>{@link METHOD}</TD> <TD>{@link Method}{@code .class}</TD></TR> 107 * <TR><TD>{@link FIELD}</TD> <TD>{@link Field}{@code .class}</TD></TR> 108 * <TR><TD>{@link CONSTRUCTOR}</TD> <TD>{@link Constructor}{@code .class}</TD></TR> 109 * <TR><TD>{@link ENUM_CONSTANT}</TD> <TD>{@link EnumConstant}{@code .class}</TD></TR> 110 * <TR><TD>{@link ANNOTATION_ELEM}</TD> <TD>{@link AnnotationElem}{@code .class}</TD></TR> 111 * <TR><TD>{@link INNER_CLASS}</TD> <TD>{@link NestedType}{@code .class}</TD></TR> 112 * </TABLE> 113 */ 114 public final Class<? extends Declaration> upgraderReflectionClass; 115 116 /** 117 * <EMBED CLASS='external-html' DATA-FILE-ID=ENTITYFIELD> 118 * 119 * <BR /><BR />The {@code Class<? extends Node>} instance stored in this <B>'Type Mirror'</B> 120 * field is the actual <B>{@code java.lang.Class}</B> of the {@code com.sun.source.tree} Node 121 * that is used to build this kind of {@code Entity}. Specifically, this field will always 122 * evaluate to one of the following <B>Java Class</B> values: 123 * 124 * <BR /><BR /><TABLE ID=JDTYPESTABLE3 CLASS='JDBriefTable MONO-SPACE-TABLE'> 125 * <TR><TH>Constant</TH> <TH>Sun/Oracle Reflection Class</TH></TR> 126 * <TR><TD>{@link METHOD}</TD> <TD>MethodTree.class</TD></TR> 127 * <TR><TD>{@link FIELD}</TD> <TD>VariableTree.class</TD></TR> 128 * <TR><TD>{@link CONSTRUCTOR}</TD> <TD>MethodTree.class</TD></TR> 129 * <TR><TD>{@link ENUM_CONSTANT}</TD> <TD>VariableTree.class</TD></TR> 130 * <TR><TD>{@link ANNOTATION_ELEM}</TD> <TD>MethodTree.class</TD></TR> 131 * <TR><TD>{@link INNER_CLASS}</TD> <TD>ClassTree.class</TD></TR> 132 * </TABLE> 133 */ 134 public final Class<? extends Tree> oracleReflectionClass; 135 136 /** Two character abbreviation-string for this {@code Entity}, usefull for CSS ID's */ 137 public final String abbrev; 138 139 /** 140 * For all constants in this {@code enum}, this field will contain an identical value to the 141 * value returned by method {@link #jdSummaryMarker()} - <B><I>except</I></B> for the constant 142 * named {@link #ANNOTATION_ELEM}. For the {@code ANNOTATION_ELEM} constant, this field will 143 * contain null. 144 * 145 * <BR /><BR />(This is because there are two types of Annotation-Elements - <I>optional</I> 146 * and <I>required</I> - and therefore two different markers for their respective Summary 147 * Sections on a Java-Doc Web-Page) 148 * 149 * <BR /><BR />The {@code String}-values contained in this field are listed in the following 150 * table: 151 * 152 * <BR /><BR /><TABLE ID=JDSUMMMARKTABLE CLASS='JDBriefTable MONO-SPACE-TABLE'> 153 * <TR><TH>Constant</TH> <TH>JavaDoc HTML-Comment Summary-Marker</TH></TR> 154 * <TR><TD>{@link METHOD}</TD> <TD>"==== METHOD SUMMARY ===="</TD></TR> 155 * <TR><TD>{@link FIELD}</TD> <TD>"==== FIELD SUMMARY ===="</TD></TR> 156 * <TR><TD>{@link CONSTRUCTOR}</TD> <TD>"==== CONSTRUCTOR SUMMARY ===="</TD></TR> 157 * <TR><TD>{@link ENUM_CONSTANT}</TD> <TD>"==== ENUM CONSTANT SUMMARY ===="</TD></TR> 158 * <TR><TD>{@link ANNOTATION_ELEM}</TD> <TD>null</TD></TR> 159 * <TR><TD>{@link INNER_CLASS}</TD> <TD>"==== NESTED CLASS SUMMARY ===="</TD></TR> 160 * </TABLE> 161 * 162 * @see #jdSummaryMarker() 163 */ 164 public final String jdSummaryMarker; 165 166 /** 167 * For all constants in this {@code enum}, this field will contain an identical value to the 168 * value returned by method {@link #jdDetailMarker()} - <B><I>except</I></B> for the constant 169 * named {@link #INNER_CLASS}. For the {@code INNER_CLASS} constant, this field will contain 170 * null. 171 * 172 * <BR /><BR />(This is because Nested-Types do not have "Details Sections" on a Java-Doc 173 * Generated Web-Page. Nested-Types get their own respective pages!) When the method 174 * {@link #jdDetailMarker()} is invoked on the {@link #INNER_CLASS} constant, that method will 175 * simply throw an exception. 176 * 177 * <BR /><BR />The {@code String}-values contained in this field are listed in the following 178 * table: 179 * 180 * <BR /><BR /><TABLE ID=JDDETMARKTABLE CLASS='JDBriefTable MONO-SPACE-TABLE'> 181 * <TR><TH>Constant</TH> <TH>JavaDoc HTML-Comment Detail-Marker</TH></TR> 182 * <TR><TD>{@link METHOD}</TD> <TD>"==== METHOD DETAIL ===="</TD></TR> 183 * <TR><TD>{@link FIELD}</TD> <TD>"==== FIELD DETAIL ===="</TD></TR> 184 * <TR><TD>{@link CONSTRUCTOR}</TD> <TD>"==== CONSTRUCTOR DETAIL ===="</TD></TR> 185 * <TR><TD>{@link ENUM_CONSTANT}</TD> <TD>"==== ENUM CONSTANT DETAIL ===="</TD></TR> 186 * <TR><TD>{@link ANNOTATION_ELEM}</TD> <TD>"==== ANNOTATION TYPE MEMBER DETAIL ====" 187 * </TD></TR> 188 * <TR><TD>{@link INNER_CLASS}</TD> <TD>null</TD></TR> 189 * </TABLE> 190 * 191 * @see #jdDetailMarker() 192 */ 193 public final String jdDetailMarker; 194 195 /** 196 * Inside the HTML of a Java-Doc Web-Page, each of the entities will have a summary section 197 * that is demarcated by an HTML Comment to signal the beginning of that summary-section. 198 * The contents of this HTML comment may be retrieved by calling this method. 199 * 200 * <BR /><BR />This {@code 'enum'} also has a {@code public} field {@code String}-constant 201 * with the same name as this method (a {@code public} & {@code final} field of type 202 * {@code String} named {@link #jdSummaryMarker}. This field contains an identical 203 * {@code String} as the return-values for this method, <B><I>except</I></B> for the constant 204 * named {@link #ANNOTATION_ELEM} (which is explained below). 205 * 206 * @return The HTML Commennt Marker that Java-Doc uses to indicate the beginning of the HTML 207 * <B><I>Summary Section</I></B> on a Java-Doc Generated Web-Page associated with 208 * {@code 'this'} entity. 209 * 210 * <BR /><BR />If this instance of {@code Entity} is the {@link #ANNOTATION_ELEM} instance, 211 * then this method will throw an {@code UpgradeException} 212 * 213 * <BR /><BR />The complete list of Summary-Section Begin Markers can be viewed in the 214 * table-provided <B><A HREF='#JDSUMMMARKTABLE'>HERE</A></B>. 215 * 216 * @throws UpgradeException If this method is invoked on the {@link ANNOTATION_ELEM} constant. 217 * 218 * @see #jdSummaryMarker 219 */ 220 public String jdSummaryMarker() 221 { 222 if (this == ANNOTATION_ELEM) throw new UpgradeException( 223 "You have asked Entity.ANNOTATION_ELEM for the HTML Comment Summary Marker, but " + 224 "this is not allowed because there are two kinds of Annotation Element Summaries. " + 225 "As such, there is no way to distinguish which Comment-Marker String is being " + 226 "requeted. An Annotation could have an 'Optional Annotation Element Summary', and " + 227 "a 'Required Annotation Element Summary.'" 228 229 ); 230 231 return jdSummaryMarker; 232 } 233 234 /** 235 * 236 * @return The HTML Commennt Marker that Java-Doc uses to indicate the beginning of the HTML 237 * <B><I>Detail Section</I></B> on a Java-Doc Generated Web-Page associated with {@code 'this'} 238 * entity. 239 * 240 * <BR /><BR />If this instance of {@code Entity} is the {@link #INNER_CLASS} instance, then 241 * this method will throw an {@code UpgradeException} 242 * 243 * <BR /><BR />The complete list of Detail-Section Begin Markers can be viewed in the 244 * table-provided <B><A HREF='#JDDETMARKTABLE'>HERE</A></B>. 245 * 246 * @throws UpgradeException If this method is invoked on the {@link INNER_CLASS} constant. 247 * Java-Doc Generated Web-Pages simply do not have Details-Sections. This is because Java-Doc 248 * will create a full and separate page for inner-classes / nested-types. 249 * 250 * @see #jdDetailMarker 251 */ 252 public String jdDetailMarker() 253 { 254 if (this == INNER_CLASS) throw new UpgradeException( 255 "Nested-Types simply do not have a Details-Section on a Java-Doc Web-Page (they " + 256 "get their own page!) Therefore there is no Detail-Section Start Comment-Marker " + 257 "to provide here." 258 ); 259 260 return jdDetailMarker; 261 } 262 263 /** 264 * Checks whether {@code 'this'} is an instance that represents an entity that may be called or 265 * invoked (and would, therefore, accept parameters as input). In Java, both methods and 266 * constructors may be invoked. 267 * 268 * @return <CODE>TRUE</CODE> if {@code 'this'} instance is either the {@link #METHOD} or the 269 * {@link #CONSTRUCTOR} constant. Returns <CODE>FALSE</CODE> otherwise. 270 */ 271 public boolean isCallable() 272 { return (this == METHOD) || (this == CONSTRUCTOR); } 273 274 // Private constructor 275 private Entity( 276 Class<? extends Declaration> upgraderReflectionClass, 277 Class<? extends Tree> oracleReflectionClass, 278 String abbrev, 279 String jdSummaryMarker, 280 String jdDetailMarker 281 ) 282 { 283 this.upgraderReflectionClass = upgraderReflectionClass; 284 this.oracleReflectionClass = oracleReflectionClass; 285 this.abbrev = abbrev; 286 this.jdSummaryMarker = jdSummaryMarker; 287 this.jdDetailMarker = jdDetailMarker; 288 } 289}