/*******************************************************************************
* Copyright (c) 2004, 2010 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.security.ProtectionDomain;
import java.util.*;
import org.osgi.framework.BundleReference;
import org.osgi.framework.wiring.BundleWiring;
/**
* The BundleClassLoader interface is used by the Framework to load local
* classes and resources from a Bundle. Classes that implement this
* interface must extend java.lang.ClassLoader, either directly or by extending
* a subclass of java.lang.ClassLoader.<p>
*
* ClassLoaders that implement the <code>BundleClassLoader</code> interface
* must use a <code>ClassLoaderDelegate</code> to delegate all class, resource
* and native library lookups.
* <p>
* Clients may implement this interface.
* </p>
* @since 3.1
* @see org.eclipse.osgi.framework.adaptor.BundleData#createClassLoader(ClassLoaderDelegate, BundleProtectionDomain, String[])
*/
public interface BundleClassLoader /*extends ClassLoader*/extends BundleReference {
/**
* Initializes the ClassLoader. This is called after all currently resolved fragment
* bundles have been attached to the BundleClassLoader by the Framework.
*/
public void initialize();
/**
* Finds a local resource in the BundleClassLoader without
* consulting the delegate.
* @param resource the resource path to find.
* @return a URL to the resource or null if the resource does not exist.
*/
public URL findLocalResource(String resource);
/**
* Finds all local resources in the BundleClassLoader with the specified
* path without consulting the delegate.
* @param resource the resource path to find.
* @return An Enumeration of all resources found or null if the resource.
* does not exist.
*/
public Enumeration<URL> findLocalResources(String resource);
/**
* Finds a local class in the BundleClassLoader without
* consulting the delegate.
* @param classname the classname to find.
* @return The class object found.
* @throws ClassNotFoundException if the classname does not exist locally.
*/
public Class<?> findLocalClass(String classname) throws ClassNotFoundException;
/**
* This method will first search the parent class loader for the resource;
* That failing, this method will invoke
* {@link ClassLoaderDelegate#findResource(String)} to find the resource.
* @param name the resource path to get.
* @return a URL for the resource or <code>null</code> if the resource is not found.
*/
public URL getResource(String name);
/**
* This method will first search the parent class loader for the resource;
* That failing, this method will invoke
* {@link ClassLoaderDelegate#findResource(String)} to find the resource.
* @param name the resource path to get.
* @return an Enumeration of URL objects for the resource or <code>null</code> if the resource is not found.
*/
public Enumeration<URL> getResources(String name) throws IOException;
/**
* This method will first search the parent class loader for the class;
* That failing, this method will invoke
* {@link ClassLoaderDelegate#findClass(String)} to find the resource.
* @param name the class name to load.
* @return the Class.
* @throws ClassNotFoundException
*/
public Class<?> loadClass(String name) throws ClassNotFoundException;
/**
* Closes this class loader. After this method is called
* loadClass will always throw ClassNotFoundException,
* getResource, getResourceAsStream, getResources and will
* return null.
*
*/
public void close();
/**
* Attaches the BundleData for a fragment to this BundleClassLoader.
* The Fragment BundleData resources must be appended to the end of
* this BundleClassLoader's classpath. Fragment BundleData resources
* must be searched ordered by Bundle ID's.
* @param bundledata The BundleData of the fragment.
* @param domain The ProtectionDomain of the resources of the fragment.
* Any classes loaded from the fragment's BundleData must belong to this
* ProtectionDomain.
* @param classpath An array of Bundle-ClassPath entries to
* use for loading classes and resources. This is specified by the
* Bundle-ClassPath manifest entry of the fragment.
*/
public void attachFragment(BundleData bundledata, ProtectionDomain domain, String[] classpath);
/**
* Returns the ClassLoaderDelegate used by this BundleClassLoader
* @return the ClassLoaderDelegate used by this BundleClassLoader
*/
public ClassLoaderDelegate getDelegate();
/**
* Returns the parent classloader used by this BundleClassLoader
* @return the parent classloader used by this BundleClassLoader
*/
public ClassLoader getParent();
/**
* Returns resource entries for the bundle associated with this class loader.
* This is used to answer a call to the
* {@link BundleWiring#findEntries(String, String, int)} method.
* @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 list of resource URLs. If no resources are found then
* the empty list is returned.
* @see {@link BundleWiring#findEntries(String, String, int)}
*/
List<URL> findEntries(String path, String filePattern, int options);
/**
* Returns the names of resources visible to this bundle class loader.
* This is used to answer a call to the
* {@link BundleWiring#listResources(String, String, int)} method.
* This method should simply return the result of calling
* {@link ClassLoaderDelegate#listResources(String, String, int)}
* @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 {@link BundleWiring#listResources(String, String, int)}
* @see {@link ClassLoaderDelegate#listResources(String, String, int)}
*/
Collection<String> listResources(String path, String filePattern, int options);
/**
* Returns the names of local resources visible to this bundle class loader.
* Only the resources available on the local class path of this bundle
* class loader are searched.
* @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 {@link ClassLoaderDelegate#listResources(String, String, int)}
*/
Collection<String> listLocalResources(String path, String filePattern, int options);
}