/*******************************************************************************
* Copyright (c) 2004, 2011 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.osgi.framework.adaptor;
import java.io.IOException;
import java.net.URL;
import java.util.Collection;
import java.util.Enumeration;
import org.osgi.framework.BundleException;
import org.osgi.framework.wiring.BundleWiring;
/**
* A ClassLoaderDelegate is used by the BundleClassLoader in a similar
* fashion that a parent ClassLoader is used. A ClassLoaderDelegate must
* be queried for any resource or class before it is loaded by the
* BundleClassLoader. The Framework implements the ClassLoaderDelegate
* and supplies it to the BundleClassLoader. FrameworkAdaptor implementations
* are not responsible for suppling an implementation for ClassLoaderDelegate.
* <p>
* This interface is not intended to be implemented by clients.
* </p>
* @noimplement This interface is not intended to be implemented by clients.
* @since 3.1
*/
public interface ClassLoaderDelegate {
/**
* Finds a class for a bundle that may be outside of the actual bundle
* (i.e. a class from an imported package or required bundle).<p>
*
* If the class does not belong to an imported package or is not
* found in a required bundle then the ClassloaderDelegate will call
* BundleClassLoader.findLocalClass(). <p>
*
* If no class is found then a ClassNotFoundException is thrown.
* @param classname the class to find.
* @return the Class.
* @throws ClassNotFoundException if the class is not found.
*/
public Class<?> findClass(String classname) throws ClassNotFoundException;
/**
* Finds a resource for a bundle that may be outside of the actual bundle
* (i.e. a resource from an imported package or required bundle).<p>
*
* If the resource does not belong to an imported package or is not
* found in a required bundle then the ClassloaderDelegate will call
* BundleClassLoader.findLocalResource(). <p>
*
* If no resource is found then return null.
* @param resource the resource to load.
* @return the resource or null if resource is not found.
*/
public URL findResource(String resource);
/**
* Finds an enumeration of resources for a bundle that may be outside of
* the actual bundle (i.e. a resource from an imported package or required
* bundle).<p>
*
* If the resource does not belong to an imported package or is not
* found in a required bundle then the ClassloaderDelegate will call
* BundleClassLoader.findLocalResource(). <p>
* If no resource is found then return null.
* @param resource the resource to find.
* @return the enumeration of resources found or null if the resource
* does not exist.
*/
public Enumeration<URL> findResources(String resource) throws IOException;
/**
* Returns the absolute path name of a native library. The following is
* a list of steps that a ClassLoaderDelegate must take when trying to
* find a library:
* <ul>
* <li>If the bundle is a fragment then try to find the library in the
* host bundle.
* <li>if the bundle is a host then try to find the library in the
* host bundle and then try to find the library in the fragment
* bundles.
* </ul>
* If no library is found return null.
* @param libraryname the library to find the path to.
* @return the path to the library or null if not found.
*/
public String findLibrary(String libraryname);
/**
* Returns true if the lazy trigger has been set for this
* delegate. The lazy trigger is set when a bundle has been
* marked for lazy activation due to a successful class load.
* @return true if the lazy trigger has been set
* @since 3.6
*/
public boolean isLazyTriggerSet();
/**
* Sets the lazy trigger for this delegate. This will activate
* the bundle if the bundle has been started with the activation
* policy and the bundle's start level is met.
* @throws BundleException if an error occurred while activating the bundle
* @see ClassLoaderDelegate#isLazyTriggerSet()
* @since 3.6
*/
public void setLazyTrigger() throws BundleException;
/**
* Returns the names of resources visible to this delegate.
* This is used to answer a call to the
* {@link BundleWiring#listResources(String, String, int)} method.
* First a search is done on the packages imported by the bundle associated
* with this delegate. Next a search is done on the the bundles required by
* the bundle associated with this delegate. Finally a local search of
* the bundle associated with this delegate is done by calling
* {@link BundleClassLoader#listLocalResources(String, String, int)}. Note
* that for imported packages the search stops at the source for the import.
* @param path The path name in which to look.
* @param filePattern The file name pattern for selecting resource names in
* the specified path.
* @param options The options for listing resource names.
* @return a collection of resource names. If no resources are found then
* the empty collection is returned.
* @see BundleWiring#listResources(String, String, int)
*/
public Collection<String> listResources(String path, String filePattern, int options);
}