WriterFactory.java revision 3233:b5d08bc0d224
1/* 2 * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package jdk.javadoc.internal.doclets.toolkit; 27 28import javax.lang.model.element.PackageElement; 29import javax.lang.model.element.TypeElement; 30import javax.lang.model.type.TypeMirror; 31 32import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; 33import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; 34 35/** 36 * The interface for a factory creates writers. 37 * 38 * <p><b>This is NOT part of any supported API. 39 * If you write code that depends on this, you do so at your own risk. 40 * This code and its internal interfaces are subject to change or 41 * deletion without notice.</b> 42 * 43 * @author Jamie Ho 44 */ 45 46public interface WriterFactory { 47 48 /** 49 * Return the writer for the constant summary. 50 * 51 * @return the writer for the constant summary. Return null if this 52 * writer is not supported by the doclet. 53 */ 54 public abstract ConstantsSummaryWriter getConstantsSummaryWriter() 55 throws Exception; 56 57 /** 58 * Return the writer for the package summary. 59 * 60 * @param packageElement the package being documented. 61 * @param prevPkg the previous package that was documented. 62 * @param nextPkg the next package being documented. 63 * @return the writer for the package summary. Return null if this 64 * writer is not supported by the doclet. 65 */ 66 public abstract PackageSummaryWriter getPackageSummaryWriter(PackageElement 67 packageElement, PackageElement prevPkg, PackageElement nextPkg) 68 throws Exception; 69 70 /** 71 * Return the writer for a class. 72 * 73 * @param typeElement the class being documented. 74 * @param prevClass the previous class that was documented. 75 * @param nextClass the next class being documented. 76 * @param classTree the class tree. 77 * @return the writer for the class. Return null if this 78 * writer is not supported by the doclet. 79 */ 80 public abstract ClassWriter getClassWriter(TypeElement typeElement, 81 TypeElement prevClass, TypeElement nextClass, ClassTree classTree) 82 throws Exception; 83 84 /** 85 * Return the writer for an annotation type. 86 * 87 * @param annotationType the type being documented. 88 * @param prevType the previous type that was documented. 89 * @param nextType the next type being documented. 90 * @return the writer for the annotation type. Return null if this 91 * writer is not supported by the doclet. 92 */ 93 public abstract AnnotationTypeWriter getAnnotationTypeWriter( 94 TypeElement annotationType, TypeMirror prevType, TypeMirror nextType) 95 throws Exception; 96 97 /** 98 * Return the method writer for a given class. 99 * 100 * @param classWriter the writer for the class being documented. 101 * @return the method writer for the give class. Return null if this 102 * writer is not supported by the doclet. 103 */ 104 public abstract MethodWriter getMethodWriter(ClassWriter classWriter) 105 throws Exception; 106 107 /** 108 * Return the annotation type field writer for a given annotation type. 109 * 110 * @param annotationTypeWriter the writer for the annotation type 111 * being documented. 112 * @return the member writer for the given annotation type. Return null if 113 * this writer is not supported by the doclet. 114 */ 115 public abstract AnnotationTypeFieldWriter 116 getAnnotationTypeFieldWriter( 117 AnnotationTypeWriter annotationTypeWriter) throws Exception; 118 119 /** 120 * Return the annotation type optional member writer for a given annotation 121 * type. 122 * 123 * @param annotationTypeWriter the writer for the annotation type 124 * being documented. 125 * @return the member writer for the given annotation type. Return null if 126 * this writer is not supported by the doclet. 127 */ 128 public abstract AnnotationTypeOptionalMemberWriter 129 getAnnotationTypeOptionalMemberWriter( 130 AnnotationTypeWriter annotationTypeWriter) throws Exception; 131 132 /** 133 * Return the annotation type required member writer for a given annotation type. 134 * 135 * @param annotationTypeWriter the writer for the annotation type 136 * being documented. 137 * @return the member writer for the given annotation type. Return null if 138 * this writer is not supported by the doclet. 139 */ 140 public abstract AnnotationTypeRequiredMemberWriter 141 getAnnotationTypeRequiredMemberWriter( 142 AnnotationTypeWriter annotationTypeWriter) throws Exception; 143 144 /** 145 * Return the enum constant writer for a given class. 146 * 147 * @param classWriter the writer for the class being documented. 148 * @return the enum constant writer for the give class. Return null if this 149 * writer is not supported by the doclet. 150 */ 151 public abstract EnumConstantWriter getEnumConstantWriter( 152 ClassWriter classWriter) throws Exception; 153 154 /** 155 * Return the field writer for a given class. 156 * 157 * @param classWriter the writer for the class being documented. 158 * @return the field writer for the give class. Return null if this 159 * writer is not supported by the doclet. 160 */ 161 public abstract FieldWriter getFieldWriter(ClassWriter classWriter) 162 throws Exception; 163 164 /** 165 * Return the property writer for a given class. 166 * 167 * @param classWriter the writer for the class being documented. 168 * @return the property writer for the give class. Return null if this 169 * writer is not supported by the doclet. 170 */ 171 public abstract PropertyWriter getPropertyWriter(ClassWriter classWriter) 172 throws Exception; 173 174 /** 175 * Return the constructor writer for a given class. 176 * 177 * @param classWriter the writer for the class being documented. 178 * @return the method writer for the give class. Return null if this 179 * writer is not supported by the doclet. 180 */ 181 public abstract ConstructorWriter getConstructorWriter( 182 ClassWriter classWriter) 183 throws Exception; 184 185 /** 186 * Return the specified member summary writer for a given class. 187 * 188 * @param classWriter the writer for the class being documented. 189 * @param memberType the {@link VisibleMemberMap} member type indicating 190 * the type of member summary that should be returned. 191 * @return the summary writer for the give class. Return null if this 192 * writer is not supported by the doclet. 193 * 194 * @see VisibleMemberMap 195 * @throws IllegalArgumentException if memberType is unknown. 196 */ 197 public abstract MemberSummaryWriter getMemberSummaryWriter( 198 ClassWriter classWriter, VisibleMemberMap.Kind memberType) 199 throws Exception; 200 201 /** 202 * Return the specified member summary writer for a given annotation type. 203 * 204 * @param annotationTypeWriter the writer for the annotation type being 205 * documented. 206 * @param memberType the {@link VisibleMemberMap} member type indicating 207 * the type of member summary that should be returned. 208 * @return the summary writer for the give class. Return null if this 209 * writer is not supported by the doclet. 210 * 211 * @see VisibleMemberMap 212 * @throws IllegalArgumentException if memberType is unknown. 213 */ 214 public abstract MemberSummaryWriter getMemberSummaryWriter( 215 AnnotationTypeWriter annotationTypeWriter, VisibleMemberMap.Kind memberType) 216 throws Exception; 217 218 /** 219 * Return the writer for the serialized form. 220 * 221 * @return the writer for the serialized form. 222 */ 223 public SerializedFormWriter getSerializedFormWriter() throws Exception; 224} 225