db-jdo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From an...@apache.org
Subject svn commit: r722805 - in /db/jdo/trunk/api2/src/java/javax/jdo: Bundle.properties Constants.java JDOEnhanceException.java JDOEnhancer.java JDOHelper.java
Date Wed, 03 Dec 2008 08:18:48 GMT
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.



Mime
View raw message