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 }