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 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 }