001    /* 
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *   http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.felix.moduleloader;
020    
021    import java.net.URL;
022    import java.util.Enumeration;
023    
024    /**
025     * This interface represents a directed class/resource loading dependency
026     * between two modules, which result when the framework resolves
027     * <tt>Import-Package</tt> or <tt>Require-Bundle</tt> declarations. A wire is
028     * the means by which a dependent module makes a class/resource request on
029     * the providing module.
030    **/
031    public interface IWire
032    {
033        /**
034         * Returns the importing module.
035         * @return The importing module.
036        **/
037        public IModule getImporter();
038        /**
039         * Returns the associated requirement from the importing module that
040         * resulted in the creation of this wire.
041         * @return
042        **/
043        public IRequirement getRequirement();
044        /**
045         * Returns the exporting module.
046         * @return The exporting module.
047        **/
048        public IModule getExporter();
049        /**
050         * Returns the associated capability from the exporting module that
051         * satisfies the requirement of the importing module.
052         * @return
053        **/
054        public ICapability getCapability();
055        /**
056         * Returns whether or not the wire has a given package name. For some
057         * wires, such as ones for Require-Bundle, there may be many packages.
058         * This method is necessary since the set of packages attained by wires
059         * restrict which packages can be dynamically imported (i.e., you cannot
060         * dynamically import a package that is already attainable from an
061         * existing wire).
062         * @return <tt>true</tt> if the package name is attainable from this wire,
063         *         <tt>false</tt> otherwise.
064        **/
065        public boolean hasPackage(String pkgName);
066        /**
067         * Requests a class from the exporting module. If the class is found, then
068         * it is returned. If the class is not found, then this method may or may
069         * not throw an exception depending on the wire type (e.g., for an
070         * imported package or a required bundle). Throwing an exception indicates
071         * that the search should be aborted, while returning a <tt>null</tt>
072         * indicates that the search should continue.
073         * @return The class if found or <tt>null</tt> if not found and the search
074         *         should continue.
075         * @throws java.lang.ClassNotFoundException If the class was not found and
076         *         the search should be aborted.
077        **/
078        public Class getClass(String name) throws ClassNotFoundException;
079        /**
080         * Requests a resource from the exporting module. If the resource is found,
081         * then an URL is returned. If the resource is not found, then this method may
082         * or may not throw an exception depending on the wire type (e.g., for an
083         * imported package or a required bundle). Throwing an exception indicates
084         * that the search should be aborted, while returning a <tt>null</tt>
085         * indicates that the search should continue.
086         * @return An URL to the resource if found or <tt>null</tt> if not found
087         *         and the search should continue.
088         * @throws ResourceNotFoundException If the resource was not found and
089         *         the search should be aborted.
090        **/
091        public URL getResource(String name) throws ResourceNotFoundException;
092        /**
093         * Requests resources from the exporting module. If the resources are found,
094         * then an enumeration of URLs is returned. If the resources are not found,
095         * then this method may or may not throw an exception depending on the wire
096         * type (e.g., for an imported package or a required bundle). Throwing an
097         * exception indicates that the search should be aborted, while returning a
098         * <tt>null</tt> indicates that the search should continue.
099         * @return An enumeration of URLs for the resource if found or <tt>null</tt>
100         *         if not found and the search should continue.
101         * @throws ResourceNotFoundException If the resource was not found and
102         *         the search should be aborted.
103        **/
104        public Enumeration getResources(String name) throws ResourceNotFoundException;
105    }