1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package javax.jdo;
18
19 import java.lang.instrument.ClassFileTransformer;
20 import java.util.Properties;
21
22 import javax.jdo.metadata.JDOMetadata;
23
24 /**
25 * Interface for a JDO Enhancer.
26 * @since 3.0
27 */
28 public interface JDOEnhancer extends ClassFileTransformer
29 {
30 /**
31 * Return non-configurable properties of this JDOEnhancer.
32 * Properties with keys "VendorName" and "VersionNumber" are required.
33 * Other keys are optional.
34 * @return the non-configurable properties of this JDOEnhancer.
35 */
36 Properties getProperties();
37
38 /**
39 * Whether to provide verbose output
40 * @param flag Verbose?
41 * @return The enhancer
42 */
43 JDOEnhancer setVerbose(boolean flag);
44
45 /**
46 * Mutator to set the location where enhanced classes are written.
47 * Mutator to set the location where enhanced classes are written.
48 * If this method is not called, classes will be enhanced in place,
49 * overwriting the existing classes. If overwriting classes in a jar file,
50 * the existing files in the jar file will be written unchanged except
51 * for the enhanced classes. The directory name can be absolute or relative.
52 * @param dirName Name of the directory
53 * @return The enhancer
54 */
55 JDOEnhancer setOutputDirectory(String dirName);
56
57 /**
58 * Mutator to set the class loader to use for loading classes.
59 * @param loader ClassLoader to use
60 * @return The enhancer
61 */
62 JDOEnhancer setClassLoader(ClassLoader loader);
63
64 /**
65 * Add a persistence-unit to the items to be enhanced.
66 * @param persistenceUnit Name of the persistence unit
67 * @return The enhancer
68 */
69 JDOEnhancer addPersistenceUnit(String persistenceUnit);
70
71 /**
72 * Add an in-memory class to the items to be enhanced.
73 * The class name should be of the form "mydomain.MyClass".
74 * @param className Name of the class
75 * @param bytes The bytes of the class
76 * @return The enhancer
77 */
78 JDOEnhancer addClass(String className, byte[] bytes);
79
80 /**
81 * Add class(es) to the items to be enhanced.
82 * The class names can be absolute file names, relative file names, or
83 * names of CLASSPATH resources.
84 * @param classNames Names of the classes
85 * @return The enhancer
86 */
87 JDOEnhancer addClasses(String... classNames);
88
89 /**
90 * Add metadata file(s) to the items to be enhanced.
91 * The metadata file names can be absolute file names, relative file names, or
92 * names of CLASSPATH resources. They should be JDO XML metadata files.
93 * @param metadataFiles Names of the files
94 * @return The enhancer
95 */
96 JDOEnhancer addFiles(String... metadataFiles);
97
98 /**
99 * Add a jar file to the items to be enhanced.
100 * The jar file name can be absolute, or relative or a CLASSPATH resource.
101 * @param jarFileName Name of the jar file
102 * @return The enhancer
103 */
104 JDOEnhancer addJar(String jarFileName);
105
106 /**
107 * Method to enhance the items specified using addJar, addFiles, addClasses, addClass,
108 * addPersistenceUnit.
109 * @return Number of classes enhanced
110 * @throws JDOEnhanceException if an error occurs during enhancement. If multiple
111 * errors occur then the nested exceptions provides this detail.
112 */
113 int enhance();
114
115 /**
116 * Method to validate the items specified using addJar, addFiles, addClasses, addClass,
117 * addPersistenceUnit.
118 * @return Number of classes validated
119 * @throws JDOEnhanceException if an error occurs during validation. If multiple
120 * errors occur then the nested exceptions provides this detail.
121 */
122 int validate();
123
124 /**
125 * Method to retrieve the (enhanced) bytes of the specified class.
126 * Only applies to the classes enhanced in the most recent enhance() call.
127 * If no enhance has yet been performed will throw a JDOEnhanceException.
128 * If the specified class hasn't been enhanced then will throw a JDOEnhanceException.
129 * @param className Name of the class (of the form "mydomain.MyClass")
130 * @return Enhanced bytes
131 */
132 byte[] getEnhancedBytes(String className);
133
134 /**
135 * Method to register metadata with the enhancement process managed by this
136 * <code>JDOEnhancer</code>.
137 * Metadata can be created using the method {@link #newMetadata}.
138 * If there is already metadata registered for a class contained in this metadata
139 * object then a JDOUserException will be thrown.
140 * @param metadata The Metadata to register.
141 * @since 3.0
142 */
143 void registerMetadata(JDOMetadata metadata);
144
145 /**
146 * Method to return a new metadata object that can be subsequently modified
147 * and registered with the enhancement process using the method {@link #registerMetadata}.
148 * @return The metadata
149 * @since 3.0
150 */
151 JDOMetadata newMetadata();
152 }