api/src/main/java/javax/jdo/JDOEnhancer.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package javax.jdo;

import java.lang.instrument.ClassFileTransformer;
import java.util.Properties;
import javax.jdo.metadata.JDOMetadata;

/**
 * Interface for a JDO Enhancer.
 *
 * @since 3.0
 */
public interface JDOEnhancer extends ClassFileTransformer {
  /**
   * Return non-configurable properties of this JDOEnhancer. Properties with keys "VendorName" and
   * "VersionNumber" are required. Other keys are optional.
   *
   * @return the non-configurable properties of this JDOEnhancer.
   */
  Properties getProperties();

  /**
   * Whether to provide verbose output
   *
   * @param flag Verbose?
   * @return The enhancer
   */
  JDOEnhancer setVerbose(boolean flag);

  /**
   * Mutator to set the location where enhanced classes are written. Mutator to set the location
   * where enhanced classes are written. If this method is not called, classes will be enhanced in
   * place, overwriting the existing classes. If overwriting classes in a jar file, the existing
   * files in the jar file will be written unchanged except for the enhanced classes. The directory
   * name can be absolute or relative.
   *
   * @param dirName Name of the directory
   * @return The enhancer
   */
  JDOEnhancer setOutputDirectory(String dirName);

  /**
   * Mutator to set the class loader to use for loading classes.
   *
   * @param loader ClassLoader to use
   * @return The enhancer
   */
  JDOEnhancer setClassLoader(ClassLoader loader);

  /**
   * Add a persistence-unit to the items to be enhanced.
   *
   * @param persistenceUnit Name of the persistence unit
   * @return The enhancer
   */
  JDOEnhancer addPersistenceUnit(String persistenceUnit);

  /**
   * Add an in-memory class to the items to be enhanced. The class name should be of the form
   * "mydomain.MyClass".
   *
   * @param className Name of the class
   * @param bytes The bytes of the class
   * @return The enhancer
   */
  JDOEnhancer addClass(String className, byte[] bytes);

  /**
   * Add class(es) to the items to be enhanced. The class names can be absolute file names, relative
   * file names, or names of CLASSPATH resources.
   *
   * @param classNames Names of the classes
   * @return The enhancer
   */
  JDOEnhancer addClasses(String... classNames);

  /**
   * Add metadata file(s) to the items to be enhanced. The metadata file names can be absolute file
   * names, relative file names, or names of CLASSPATH resources. They should be JDO XML metadata
   * files.
   *
   * @param metadataFiles Names of the files
   * @return The enhancer
   */
  JDOEnhancer addFiles(String... metadataFiles);

  /**
   * Add a jar file to the items to be enhanced. The jar file name can be absolute, or relative or a
   * CLASSPATH resource.
   *
   * @param jarFileName Name of the jar file
   * @return The enhancer
   */
  JDOEnhancer addJar(String jarFileName);

  /**
   * Method to enhance the items specified using addJar, addFiles, addClasses, addClass,
   * addPersistenceUnit.
   *
   * @return Number of classes enhanced
   * @throws JDOEnhanceException if an error occurs during enhancement. If multiple errors occur
   *     then the nested exceptions provides this detail.
   */
  int enhance();

  /**
   * Method to validate the items specified using addJar, addFiles, addClasses, addClass,
   * addPersistenceUnit.
   *
   * @return Number of classes validated
   * @throws JDOEnhanceException if an error occurs during validation. If multiple errors occur then
   *     the nested exceptions provides this detail.
   */
  int validate();

  /**
   * Method to retrieve the (enhanced) bytes of the specified class. Only applies to the classes
   * enhanced in the most recent enhance() call. If no enhance has yet been performed will throw a
   * JDOEnhanceException. If the specified class hasn't been enhanced then will throw a
   * JDOEnhanceException.
   *
   * @param className Name of the class (of the form "mydomain.MyClass")
   * @return Enhanced bytes
   */
  byte[] getEnhancedBytes(String className);

  /**
   * Method to register metadata with the enhancement process managed by this <code>JDOEnhancer
   * </code>. Metadata can be created using the method {@link #newMetadata}. If there is already
   * metadata registered for a class contained in this metadata object then a JDOUserException will
   * be thrown.
   *
   * @param metadata The Metadata to register.
   * @since 3.0
   */
  void registerMetadata(JDOMetadata metadata);

  /**
   * Method to return a new metadata object that can be subsequently modified and registered with
   * the enhancement process using the method {@link #registerMetadata}.
   *
   * @return The metadata
   * @since 3.0
   */
  JDOMetadata newMetadata();
}