Java tutorial
/****************************************************************************** * Copyright (c) 2006, 2010 VMware Inc. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * and Apache License v2.0 which accompanies this distribution. * The Eclipse Public License is available at * http://www.eclipse.org/legal/epl-v10.html and the Apache License v2.0 * is available at http://www.opensource.org/licenses/apache2.0.php. * You may elect to redistribute this code under either of these licenses. * * Contributors: * VMware Inc. *****************************************************************************/ package org.eclipse.gemini.blueprint.test; import java.io.IOException; import java.security.AccessController; import java.security.PrivilegedAction; import java.util.ArrayList; import java.util.Collection; import java.util.Iterator; import java.util.LinkedHashMap; import java.util.LinkedHashSet; import java.util.List; import java.util.Map; import java.util.Set; import java.util.jar.Attributes; import java.util.jar.Manifest; import org.eclipse.gemini.blueprint.test.internal.util.DependencyVisitor; import org.eclipse.gemini.blueprint.test.internal.util.jar.JarCreator; import org.eclipse.gemini.blueprint.util.OsgiStringUtils; import org.objectweb.asm.ClassReader; import org.osgi.framework.Bundle; import org.osgi.framework.BundleContext; import org.osgi.framework.Constants; import org.springframework.core.io.DefaultResourceLoader; import org.springframework.core.io.InputStreamResource; import org.springframework.core.io.Resource; import org.springframework.util.Assert; import org.springframework.util.ClassUtils; import org.springframework.util.CollectionUtils; import org.springframework.util.ObjectUtils; import org.springframework.util.StringUtils; /** * Enhanced subclass of {@link AbstractDependencyManagerTests} that facilitates * OSGi testing by creating at runtime, on the fly, a jar using the indicated * manifest and resource patterns (by default all files found under the root * path). * * <p/>The test class can automatically determine the imports required by the * test, create the OSGi bundle manifest and pack the test and its resources in * a jar that can be installed inside an OSGi platform. * * <p/>Additionally, a valid OSGi manifest is automatically created for the * resulting test if the user does not provide one. The classes present in the * archive are analyzed and based on their byte-code, the required * <code>Import-Package</code> entries (for packages not found in the bundle) * are created. * * Please see the reference documentation for an in-depth explanation and usage * examples. * * <p/>Note that in more complex scenarios, dedicated packaging tools (such as * ant scripts or maven2) should be used. * * <p/>It is recommend to extend {@link AbstractConfigurableBundleCreatorTests} * rather then this class as the former offers sensible defaults. * * @author Costin Leau * */ public abstract class AbstractOnTheFlyBundleCreatorTests extends AbstractDependencyManagerTests { private static final String META_INF_JAR_LOCATION = "/META-INF/MANIFEST.MF"; JarCreator jarCreator; /** field used for caching jar content */ private Map jarEntries; /** discovered manifest */ private Manifest manifest; public AbstractOnTheFlyBundleCreatorTests() { initializeJarCreator(); } public AbstractOnTheFlyBundleCreatorTests(String testName) { super(testName); initializeJarCreator(); } private void initializeJarCreator() { AccessController.doPrivileged(new PrivilegedAction() { public Object run() { jarCreator = new JarCreator(); return null; } }); } /** * Returns the root path used for locating the resources that will be packed * in the test bundle (the root path does not become part of the jar). * * <p/>By default, the current threads context ClassLoader is used to locate * the root of the classpath. Because unit tests will either be run from Maven * or an IDE this will resolve a test classes directory of sorts. * * <p/>For example when invoked from Maven <code>"file:./target/test-classes"</code> * will be resolved and used. * * @return root path given as a String */ protected String getRootPath() { return Thread.currentThread().getContextClassLoader().getResource(".").toString(); } /** * Returns the patterns used for identifying the resources added to the jar. * The patterns are added to the root path when performing the search. By * default, the pattern is <code>**/*</code>. * * <p/>In large test environments, performance can be improved by limiting * the resource added to the bundle by selecting only certain packages or * classes. This results in a small test bundle which is faster to create, * deploy and install. * * @return the patterns identifying the resources added to the jar */ protected String[] getBundleContentPattern() { return new String[] { JarCreator.EVERYTHING_PATTERN }; } /** * Returns the location (in Spring resource style) of the manifest location * to be used. By default <code>null</code> is returned, indicating that * the manifest should be picked up from the bundle content (if it's * available) or be automatically created based on the test class imports. * * @return the manifest location * @see #getManifest() * @see #createDefaultManifest() */ protected String getManifestLocation() { return null; } /** * Returns the current test bundle manifest. The method tries to read the * manifest from the given location; in case the location is * <code>null</code> (default), it will search for * <code>META-INF/MANIFEST.MF</code> file in jar content (as specified * through the patterns) and, if it cannot find the file, * <em>automatically</em> create a <code>Manifest</code> object * containing default entries. * * <p/> Subclasses can override this method to enhance the returned * Manifest. * * @return Manifest used for this test suite. * * @see #createDefaultManifest() */ protected Manifest getManifest() { // return cached manifest if (manifest != null) return manifest; String manifestLocation = getManifestLocation(); if (StringUtils.hasText(manifestLocation)) { logger.info("Using Manifest from specified location=[" + getManifestLocation() + "]"); DefaultResourceLoader loader = new DefaultResourceLoader(); manifest = createManifestFrom(loader.getResource(manifestLocation)); } else { // set root path jarCreator.setRootPath(getRootPath()); // add the content pattern jarCreator.setContentPattern(getBundleContentPattern()); // see if the manifest already exists in the classpath // to resolve the patterns jarEntries = jarCreator.resolveContent(); for (Iterator iterator = jarEntries.entrySet().iterator(); iterator.hasNext();) { Map.Entry entry = (Map.Entry) iterator.next(); if (META_INF_JAR_LOCATION.equals(entry.getKey())) { logger.info("Using Manifest from the test bundle content=[/META-INF/MANIFEST.MF]"); manifest = createManifestFrom((Resource) entry.getValue()); } } // fallback to default manifest creation if (manifest == null) { logger.info("Automatically creating Manifest for the test bundle"); manifest = createDefaultManifest(); } } return manifest; } /** * Indicates if the automatic manifest creation should consider only the * test class (<code>true</code>) or all classes included in the test * bundle(<code>false</code>). The latter should be used when the test * bundle contains additional classes that help with the test case. * * <p/> By default, this method returns <code>true</code>, meaning that * only the test class will be searched for dependencies. * * @return true if only the test hierarchy is searched for dependencies or * false if all classes discovered in the test archive need to be * parsed. */ protected boolean createManifestOnlyFromTestClass() { return true; } private Manifest createManifestFrom(Resource resource) { Assert.notNull(resource, "unable to create manifest for empty resources"); try { return new Manifest(resource.getInputStream()); } catch (IOException ex) { throw (RuntimeException) new IllegalArgumentException("cannot create manifest from " + resource) .initCause(ex); } } /** * Creates the default manifest in case none if found on the disk. By * default, the imports are synthetised based on the test class bytecode. * * @return default manifest for the jar created on the fly */ protected Manifest createDefaultManifest() { Manifest manifest = new Manifest(); Attributes attrs = manifest.getMainAttributes(); // manifest versions attrs.put(Attributes.Name.MANIFEST_VERSION, "1.0"); attrs.putValue(Constants.BUNDLE_MANIFESTVERSION, "2"); String description = getName() + "-" + getClass().getName(); // name/description attrs.putValue(Constants.BUNDLE_NAME, "TestBundle-" + description); attrs.putValue(Constants.BUNDLE_SYMBOLICNAME, "TestBundle-" + description); attrs.putValue(Constants.BUNDLE_DESCRIPTION, "on-the-fly test bundle"); // activator attrs.putValue(Constants.BUNDLE_ACTIVATOR, JUnitTestActivator.class.getName()); // add Import-Package entry addImportPackage(manifest); if (logger.isDebugEnabled()) logger.debug("Created manifest:" + manifest.getMainAttributes().entrySet()); return manifest; } private void addImportPackage(Manifest manifest) { String[] rawImports = determineImports(); boolean trace = logger.isTraceEnabled(); if (trace) logger.trace("Discovered raw imports " + ObjectUtils.nullSafeToString(rawImports)); Collection specialImportsOut = eliminateSpecialPackages(rawImports); Collection imports = eliminatePackagesAvailableInTheJar(specialImportsOut); if (trace) logger.trace("Filtered imports are " + imports); manifest.getMainAttributes().putValue(Constants.IMPORT_PACKAGE, StringUtils.collectionToCommaDelimitedString(imports)); } /** * Eliminate 'special' packages (java.*, test framework internal and the * class declaring package) * * @param rawImports * @return */ private Collection eliminateSpecialPackages(String[] rawImports) { String currentPckg = ClassUtils.classPackageAsResourcePath(getClass()).replace('/', '.'); Set filteredImports = new LinkedHashSet(rawImports.length); Set eliminatedImports = new LinkedHashSet(4); for (int i = 0; i < rawImports.length; i++) { String pckg = rawImports[i]; if (!(pckg.startsWith("java.") || pckg.startsWith("org.eclipse.gemini.blueprint.test.internal") || pckg.equals(currentPckg))) filteredImports.add(pckg); else eliminatedImports.add(pckg); } if (!eliminatedImports.isEmpty() && logger.isTraceEnabled()) logger.trace("Eliminated special packages " + eliminatedImports); return filteredImports; } /** * Eliminates imports for packages already included in the bundle. Works * only if the jar content is known (variable 'jarEntries' set). * * @param imports * @return */ private Collection eliminatePackagesAvailableInTheJar(Collection imports) { // no jar entry present, bail out. if (jarEntries == null || jarEntries.isEmpty()) return imports; Set filteredImports = new LinkedHashSet(imports.size()); Collection eliminatedImports = new LinkedHashSet(2); Collection jarPackages = jarCreator.getContainedPackages(); for (Iterator iterator = imports.iterator(); iterator.hasNext();) { String pckg = (String) iterator.next(); if (jarPackages.contains(pckg)) eliminatedImports.add(pckg); else filteredImports.add(pckg); } if (!eliminatedImports.isEmpty() && logger.isTraceEnabled()) logger.trace("Eliminated packages already present in the bundle " + eliminatedImports); return filteredImports; } /** * Determine imports for the given bundle. Based on the user settings, this * method will consider only the the test hierarchy until the testing * framework is found or all classes available inside the test bundle. <p/> * Note that split packages are not supported. * * @return */ private String[] determineImports() { boolean useTestClassOnly = false; // no jar entry present, bail out. if (jarEntries == null || jarEntries.isEmpty()) { logger.debug("No test jar content detected, generating bundle imports from the test class"); useTestClassOnly = true; } else if (createManifestOnlyFromTestClass()) { logger.info("Using the test class for generating bundle imports"); useTestClassOnly = true; } else logger.info("Using all classes in the jar for the generation of bundle imports"); // className, class resource Map entries; if (useTestClassOnly) { entries = new LinkedHashMap(4); // get current class (test class that bootstraps the OSGi infrastructure) Class<?> clazz = getClass(); String clazzPackage = null; String endPackage = AbstractOnTheFlyBundleCreatorTests.class.getPackage().getName(); do { // consider inner classes as well List classes = new ArrayList(4); classes.add(clazz); CollectionUtils.mergeArrayIntoCollection(clazz.getDeclaredClasses(), classes); for (Iterator iterator = classes.iterator(); iterator.hasNext();) { Class<?> classToInspect = (Class) iterator.next(); Package pkg = classToInspect.getPackage(); if (pkg != null) { clazzPackage = pkg.getName(); String classFile = ClassUtils.getClassFileName(classToInspect); entries.put(classToInspect.getName().replace('.', '/').concat(ClassUtils.CLASS_FILE_SUFFIX), new InputStreamResource(classToInspect.getResourceAsStream(classFile))); } // handle default package else { logger.warn("Could not find package for class " + classToInspect + "; ignoring..."); } } clazz = clazz.getSuperclass(); } while (!endPackage.equals(clazzPackage)); } else entries = jarEntries; return determineImportsFor(entries); } private String[] determineImportsFor(Map entries) { // get contained packages to do matching on the test hierarchy Collection containedPackages = jarCreator.getContainedPackages(); Set cumulatedPackages = new LinkedHashSet(); // make sure the collection package is valid boolean validPackageCollection = !containedPackages.isEmpty(); boolean trace = logger.isTraceEnabled(); for (Iterator iterator = entries.entrySet().iterator(); iterator.hasNext();) { Map.Entry entry = (Map.Entry) iterator.next(); String resourceName = (String) entry.getKey(); // filter out the test hierarchy if (resourceName.endsWith(ClassUtils.CLASS_FILE_SUFFIX)) { if (trace) logger.trace("Analyze imports for test bundle resource " + resourceName); String classFileName = StringUtils.getFilename(resourceName); String className = classFileName.substring(0, classFileName.length() - ClassUtils.CLASS_FILE_SUFFIX.length()); String classPkg = resourceName.substring(0, resourceName.length() - classFileName.length()) .replace('/', '.'); if (classPkg.startsWith(".")) classPkg = classPkg.substring(1); if (classPkg.endsWith(".")) classPkg = classPkg.substring(0, classPkg.length() - 1); // if we don't have the package, add it if (validPackageCollection && StringUtils.hasText(classPkg) && !containedPackages.contains(classPkg)) { logger.trace( "Package [" + classPkg + "] is NOT part of the test archive; adding an import for it"); cumulatedPackages.add(classPkg); } // otherwise parse the class byte-code else { if (trace) logger.trace("Package [" + classPkg + "] is part of the test archive; parsing " + className + " bytecode to determine imports..."); cumulatedPackages.addAll(determineImportsForClass(className, (Resource) entry.getValue())); } } } return (String[]) cumulatedPackages.toArray(new String[cumulatedPackages.size()]); } /** * Determine imports for a class given as a String resource. This method * doesn't do any search for the enclosing/inner classes as it considers * that these should be handled at a higher level. * * The returned set contains the packages in string format (i.e. java.io) * * @param className * @param resource * @return */ private Set determineImportsForClass(String className, Resource resource) { Assert.notNull(resource, "a not-null class is required"); DependencyVisitor visitor = new DependencyVisitor(); boolean trace = logger.isTraceEnabled(); ClassReader reader; try { if (trace) logger.trace("Visiting class " + className); reader = new ClassReader(resource.getInputStream()); } catch (Exception ex) { throw (RuntimeException) new IllegalArgumentException("Cannot read class " + className).initCause(ex); } reader.accept(visitor, false); // convert from / to . format Set originalPackages = visitor.getPackages(); Set pkgs = new LinkedHashSet(originalPackages.size()); for (Iterator iterator = originalPackages.iterator(); iterator.hasNext();) { String pkg = (String) iterator.next(); pkgs.add(pkg.replace('/', '.')); } return pkgs; } protected void postProcessBundleContext(BundleContext context) throws Exception { logger.debug("Post processing: creating test bundle"); Resource jar; Manifest mf = getManifest(); // if the jar content hasn't been discovered yet (while creating the manifest) // do so now if (jarEntries == null) { // set root path jarCreator.setRootPath(getRootPath()); // add the content pattern jarCreator.setContentPattern(getBundleContentPattern()); // use jar creator for pattern discovery jar = jarCreator.createJar(mf); } // otherwise use the cached resources else { jar = jarCreator.createJar(mf, jarEntries); } try { installAndStartBundle(context, jar); } catch (Exception e) { IllegalStateException ise = new IllegalStateException( "Unable to dynamically start generated unit test bundle"); ise.initCause(e); throw ise; } // now do the delegation super.postProcessBundleContext(context); } private void installAndStartBundle(BundleContext context, Resource resource) throws Exception { // install & start Bundle bundle = context.installBundle( "[onTheFly-test-bundle]" + ClassUtils.getShortName(getClass()) + "[" + hashCode() + "]", resource.getInputStream()); String bundleString = OsgiStringUtils.nullSafeNameAndSymName(bundle); boolean debug = logger.isDebugEnabled(); if (debug) logger.debug("Test bundle [" + bundleString + "] successfully installed"); bundle.start(); if (debug) logger.debug("Test bundle [" + bundleString + "] successfully started"); } }