You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-commits@db.apache.org by an...@apache.org on 2008/12/03 09:18:48 UTC
svn commit: r722805 - in /db/jdo/trunk/api2/src/java/javax/jdo:
Bundle.properties Constants.java JDOEnhanceException.java JDOEnhancer.java
JDOHelper.java
Author: andyj
Date: Wed Dec 3 00:18:48 2008
New Revision: 722805
URL: http://svn.apache.org/viewvc?rev=722805&view=rev
Log:
JDO-591 : API for JDO enhancement
Added:
db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhanceException.java
db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhancer.java
Modified:
db/jdo/trunk/api2/src/java/javax/jdo/Bundle.properties
db/jdo/trunk/api2/src/java/javax/jdo/Constants.java
db/jdo/trunk/api2/src/java/javax/jdo/JDOHelper.java
Modified: db/jdo/trunk/api2/src/java/javax/jdo/Bundle.properties
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api2/src/java/javax/jdo/Bundle.properties?rev=722805&r1=722804&r2=722805&view=diff
==============================================================================
--- db/jdo/trunk/api2/src/java/javax/jdo/Bundle.properties (original)
+++ db/jdo/trunk/api2/src/java/javax/jdo/Bundle.properties Wed Dec 3 00:18:48 2008
@@ -120,3 +120,7 @@
EXC_JavaxPersistencePersistenceAbsentOrNoPUFound=\
Class javax.persistence.Persistence or one of its dependencies was not found, \
or the given persistence unit name "{0}" was not found.
+
+EXC_GetEnhancerNoValidEnhancerAvailable=\
+There were no valid JDOEnhancer implementations identified in the CLASSPATH. \
+The file META-INF/services/javax.jdo.JDOEnhancer should name the implementation class.
Modified: db/jdo/trunk/api2/src/java/javax/jdo/Constants.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api2/src/java/javax/jdo/Constants.java?rev=722805&r1=722804&r2=722805&view=diff
==============================================================================
--- db/jdo/trunk/api2/src/java/javax/jdo/Constants.java (original)
+++ db/jdo/trunk/api2/src/java/javax/jdo/Constants.java Wed Dec 3 00:18:48 2008
@@ -36,6 +36,15 @@
= "META-INF/services/javax.jdo.PersistenceManagerFactory";
/**
+ * The name of the standard service configuration resource text file containing
+ * the name of an enhancer of {@link JDOEnhancer}.
+ * Constant value is <code>META-INF/services/javax.jdo.JDOEnhancer</code>.
+ * @since 2.3
+ */
+ static String SERVICE_LOOKUP_ENHANCER_RESOURCE_NAME
+ = "META-INF/services/javax.jdo.JDOEnhancer";
+
+ /**
* The name of the standard JDO configuration resource file(s).
* Constant value is <code>META-INF/jdoconfig.xml</code>.
*
Added: db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhanceException.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhanceException.java?rev=722805&view=auto
==============================================================================
--- db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhanceException.java (added)
+++ db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhanceException.java Wed Dec 3 00:18:48 2008
@@ -0,0 +1,64 @@
+/*
+ * 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
+ *
+ * http://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;
+
+/**
+ * Exception thrown when an error occurs during enhancement.
+ * @since 2.3
+ */
+public class JDOEnhanceException extends JDOException
+{
+ /**
+ * Constructs a new <code>JDOEnhanceException</code> without a
+ * detail message.
+ */
+ public JDOEnhanceException()
+ {
+ }
+
+ /**
+ * Constructs a new <code>JDOEnhanceException</code> with the
+ * specified detail message.
+ * @param msg the detail message.
+ */
+ public JDOEnhanceException(String msg)
+ {
+ super(msg);
+ }
+
+ /**
+ * Constructs a new <code>JDOEnhanceException</code> with the
+ * specified detail message and nested <code>Throwable</code>s.
+ * @param msg the detail message.
+ * @param nested the nested <code>Throwable[]</code>.
+ */
+ public JDOEnhanceException(String msg, Throwable[] nested)
+ {
+ super(msg, nested);
+ }
+
+ /**
+ * Constructs a new <code>JDOEnhanceException</code> with the
+ * specified detail message and nested <code>Throwable</code>s.
+ * @param msg the detail message.
+ * @param nested the nested <code>Throwable</code>.
+ */
+ public JDOEnhanceException(String msg, Throwable nested)
+ {
+ super(msg, nested);
+ }
+}
Added: db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhancer.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhancer.java?rev=722805&view=auto
==============================================================================
--- db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhancer.java (added)
+++ db/jdo/trunk/api2/src/java/javax/jdo/JDOEnhancer.java Wed Dec 3 00:18:48 2008
@@ -0,0 +1,124 @@
+/*
+ * 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
+ *
+ * http://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;
+
+/**
+ * Interface for a JDO Enhancer.
+ * @since 2.3
+ */
+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.
+ */
+ void enhance();
+
+ /**
+ * Method to validate the items specified using addJar, addFiles, addClasses, addClass,
+ * addPersistenceUnit.
+ */
+ void 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);
+}
\ No newline at end of file
Modified: db/jdo/trunk/api2/src/java/javax/jdo/JDOHelper.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api2/src/java/javax/jdo/JDOHelper.java?rev=722805&r1=722804&r2=722805&view=diff
==============================================================================
--- db/jdo/trunk/api2/src/java/javax/jdo/JDOHelper.java (original)
+++ db/jdo/trunk/api2/src/java/javax/jdo/JDOHelper.java Wed Dec 3 00:18:48 2008
@@ -1820,6 +1820,66 @@
return getPersistenceManagerFactory (props, loader);
}
+ /**
+ * Get a <code>JDOEnhancer</code> using the available enhancer(s) specified in
+ * "META-INF/services/JDOEnhancer" using the context class loader.
+ * @return the <code>JDOEnhancer</code>.
+ * @throws JDOFatalUserException if no available enhancer
+ * @since 2.3
+ */
+ public static JDOEnhancer getEnhancer() {
+ return getEnhancer(getContextClassLoader());
+ }
+
+ /**
+ * Get a <code>JDOEnhancer</code> using the available enhancer(s) specified in
+ * "META-INF/services/JDOEnhancer"
+ * @param loader the loader to use for loading the JDOEnhancer class (if any)
+ * @return the <code>JDOEnhancer</code>.
+ * @throws JDOFatalUserException if no available enhancer
+ * @since 2.3
+ */
+ public static JDOEnhancer getEnhancer(ClassLoader loader) {
+ ClassLoader ctrLoader = loader;
+ if (ctrLoader == null) {
+ ctrLoader = Thread.currentThread().getContextClassLoader();
+ }
+
+ /*
+ * If you have a jar file that provides the jdo enhancer implementation,
+ * a file naming the implementation goes into the file
+ * packaged into the jar file, called "META-INF/services/javax.jdo.JDOEnhancer".
+ * The contents of the file is a string that is the enhancer class name.
+ * For each file in the class loader named "META-INF/services/javax.jdo.JDOEnhancer",
+ * this method will invoke the default constructor of the implementation class.
+ * Return the enhancer if a valid class name is extracted from resources and
+ * the invocation returns an instance.
+ * Otherwise add the exception thrown to an exception list.
+ */
+ ArrayList exceptions = new ArrayList();
+ try {
+ Enumeration urls = getResources(loader, SERVICE_LOOKUP_ENHANCER_RESOURCE_NAME);
+ if (urls != null) {
+ while (urls.hasMoreElements()) {
+ try {
+ String enhancerClassName = getClassNameFromURL((URL)urls.nextElement());
+ Class enhancerClass = forName(enhancerClassName, true, ctrLoader);
+ JDOEnhancer enhancer = (JDOEnhancer)enhancerClass.newInstance();
+ return enhancer;
+ } catch (Throwable ex) {
+ // remember exceptions from failed enhancer invocations
+ exceptions.add(ex);
+ }
+ }
+ }
+ } catch (Throwable ex) {
+ exceptions.add(ex);
+ }
+
+ throw new JDOFatalUserException(msg.msg("EXC_GetEnhancerNoValidEnhancerAvailable"),
+ (Throwable[])exceptions.toArray(new Throwable[exceptions.size()]));
+ }
+
/** Get the context class loader associated with the current thread.
* This is done in a doPrivileged block because it is a secure method.
* @return the current thread's context class loader.