View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
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 }