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