OLD | NEW |
(Empty) | |
| 1 package com.google.protobuf.compiler; |
| 2 |
| 3 import com.google.protobuf.Descriptors.FileDescriptor; |
| 4 |
| 5 import java.io.Writer; |
| 6 import java.util.List; |
| 7 |
| 8 /** |
| 9 * Interface to be implemented by a code generator. |
| 10 *· |
| 11 * @see Plugin |
| 12 *· |
| 13 * @author t.broyer@ltgt.net Thomas Broyer |
| 14 * <br>Based on the initial work of: |
| 15 * @author kenton@google.com Kenton Varda |
| 16 */ |
| 17 public interface CodeGenerator { |
| 18 |
| 19 /** |
| 20 * Context for a given file generation. |
| 21 * <p> |
| 22 * Gives access to the full list of files to be generated (when used as a |
| 23 * protoc plugin, these are the files listed on the command-line) and methods |
| 24 * to output the generated files (or code snippets to be inserted into |
| 25 * existing files). |
| 26 *· |
| 27 * @author t.broyer@ltgt.net Thomas Broyer |
| 28 * <br>Based on the initial work of: |
| 29 * @author kenton@google.com Kenton Varda |
| 30 */ |
| 31 public interface Context { |
| 32 /** |
| 33 * Returns the files for which the generator needs to generate code. |
| 34 * <p> |
| 35 * Most generators do not need to call {@code getParsedFiles()}. |
| 36 * <p> |
| 37 * The generator's {@link |
| 38 * CodeGenerator#generate(FileDescriptor, String, Context)} method will be |
| 39 * called once for each file in the list. |
| 40 * <p> |
| 41 * The list ordering is guaranteed to be stable between the calls to {@link |
| 42 * CodeGenerator#generate(FileDescriptor, String, Context)} so a generator |
| 43 * can, for instance, determine whether it is processing the first file. |
| 44 * This is useful when you want to generate a single file for a given |
| 45 * context (generating the file in every {@link |
| 46 * CodeGenerator#generate(FileDescriptor, String, Context)} call would lead |
| 47 * to a "duplicate file" error. |
| 48 */ |
| 49 List<FileDescriptor> getParsedFiles(); |
| 50 ···· |
| 51 /** |
| 52 * Generates a new file with the given content. |
| 53 */ |
| 54 void addFile(String filename, String content); |
| 55 ·· |
| 56 /** |
| 57 * Inserts the given content into an existing file. |
| 58 */ |
| 59 void insertIntoFile(String filename, String insertionPoint, |
| 60 String content); |
| 61 ·· |
| 62 /** |
| 63 * Returns a {@link Writer} to generate a new file. |
| 64 * <p> |
| 65 * The filename given should be relative to the root of the source tree. |
| 66 * E.g. the C++ generator, when generating code for "foo/bar.proto", will |
| 67 * generate the files "foo/bar.pb.h" and "foo/bar.pb.cc"; note that "foo/" |
| 68 * is included in these filenames. The filename is not allowed to contain |
| 69 * "." or ".." components. |
| 70 * <p> |
| 71 * It is the caller's responsibility to commit the file by calling the |
| 72 * {@link Writer#close()} method on the returned {@link Writer}. |
| 73 */ |
| 74 Writer open(String filename); |
| 75 ·· |
| 76 /** |
| 77 * Returns a {@link Writer} to insert into an existing file. |
| 78 * <p> |
| 79 * The filename given should be relative to the root of the source tree. |
| 80 * E.g. the C++ generator, when generating code for "foo/bar.proto", will |
| 81 * generate the files "foo/bar.pb.h" and "foo/bar.pb.cc"; note that "foo/" |
| 82 * is included in these filenames. The filename is not allowed to contain |
| 83 * "." or ".." components. |
| 84 * <p> |
| 85 * It is the caller's responsibility to commit the file by calling the |
| 86 * {@link Writer#close()} method on the returned {@link Writer}. |
| 87 */ |
| 88 Writer openForInsert(String filename, String insertionPoint); |
| 89 } |
| 90 |
| 91 /** |
| 92 * Throw by a code generator in case of error. |
| 93 * |
| 94 * @author t.broyer@ltgt.net Thomas Broyer |
| 95 * <br>Based on the initial work of: |
| 96 * @author kenton@google.com Kenton Varda |
| 97 */ |
| 98 public static class GeneratorException extends Exception { |
| 99 private static final long serialVersionUID = -4317369502082361194L; |
| 100 |
| 101 public GeneratorException(FileDescriptor fileToGenerate, String message) { |
| 102 this(fileToGenerate.getName() + ": " + message); |
| 103 } |
| 104 |
| 105 public GeneratorException(FileDescriptor fileToGenerate, String message, |
| 106 Throwable cause) { |
| 107 this(fileToGenerate.getName() + ": " + message, cause); |
| 108 } |
| 109 |
| 110 public GeneratorException(String message) { |
| 111 super(message); |
| 112 } |
| 113 |
| 114 public GeneratorException(String message, Throwable cause) { |
| 115 super(message, cause); |
| 116 } |
| 117 ···· |
| 118 public GeneratorException(Throwable cause) { |
| 119 super(cause); |
| 120 } |
| 121 } |
| 122 ·· |
| 123 /** |
| 124 * Generates code for the given proto file, generating one or more files in |
| 125 * the given context. |
| 126 */ |
| 127 void generate(FileDescriptor fileToGenerate, String parameter, |
| 128 Context context) throws GeneratorException; |
| 129 } |
OLD | NEW |