/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2004 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.openide.modules;

import java.io.File;
import java.util.Collection;
import java.util.Iterator;
import org.openide.util.Lookup;
import org.openide.util.LookupEvent;
import org.openide.util.LookupListener;

/**
 * Service providing the ability to locate a module-installed file in
 * the NetBeans application's installation.
 * Zero or more instances may be registered to lookup.
 * @author Jesse Glick
 * @since 3.21
 * @see Issue #28683
 */
public abstract class InstalledFileLocator {
    
    /**
     * No-op constructor for use by subclasses.
     */
    protected InstalledFileLocator() {}
    
    /**
     * Try to locate a file.
     * 

     * 

     * When using the normal NetBeans installation structure and NBM file format,
     * this path will be relative to the installation directory (or user directory,
     * for a locally installed module). Other possible installation mechanisms, such
     * as JNLP (Java WebStart), might arrange the physical files differently, but
     * generally the path indicated by a module's normal NBM file (beneath netbeans/
     * in the NBM) should be interpreted by the locator implementation to point to the actual
     * location of the file, so the module need not be aware of such details. Some
     * locator implementations may perform the search more accurately or quickly
     * when given a code name base for the module that supplies the file.
     * 
     * 

     * The file may refer to a directory (no trailing slash!), in which case the locator
     * should attempt to find that directory in the installation. Note that only one
     * file may be located from a given path, so generally this method will not be
     * useful where a directory can contain many items that may be merged between e.g.
     * the installation and user directories. For example, the docs folder
     * (used e.g. for Javadoc) might contain several ZIP files in both the installation and
     * user areas. There is currently no supported way to enumerate all such files. Therefore
     * searching for a directory should be attempted only when there is just one module which
     * is expected to provide that directory and all of its contents. The module may assume
     * that all contained files are in the same relative structure in the directory as in
     * the normal NBM-based installation; unusual locator implementations may need to create
     * temporary directories with matching structures to return from this method, in case the
     * physical file locations are not in such a directory structure.
     * See issue #36701 for details.
     * 
     * 
     * 

     * Localized and branded lookups should follow the normal naming conventions,
     * e.g. docs/OpenAPIs_ja.zip would be used for Japanese Javadoc
     * and locate("docs/OpenAPIs.zip", …, true)
     * would find it when running in Japanese locale.
     * 
     * 

     * 

     * For cases where the search is for a module JAR or one of its extensions, client
     * code may prefer to use the code source given by a class loader. This will permit
     * a client to find the base URL (may or may not refer to a file) responsible for loading
     * the contents of the protection domain, typically a JAR file, containing a class
     * which is accessible to the module class loader. For example:
     * 
     * 
Class c = ClassMyModuleDefines.class;
URL u = c.getProtectionDomain().getCodeSource().getLocation();
     * 
     * 

     * When running from a JAR file, this will typically give e.g.
     * file:/path/to/archive.jar. This information may be useful,
     * but it is not conclusive, since there is no guarantee what the URL protocol
     * will be, nor that the returned URL uniquely identifies a JAR shipped with
     * the module in its canonical NBM format. InstalledFileLocator
     * provides stronger guarantees than this technique, since you can explicitly
     * name a JAR file to be located on disk.
     * 
     * 
     * 

     * 

     * This class should not be used just to find resources on the system
     * filesystem, which in the normal NetBeans installation structure means the
     * result of merging ${netbeans.home}/system/ with ${netbeans.user}/system/
     * as well as module layers and perhaps project-specific storage. To find data in
     * the system filesystem, use the Filesystems API, e.g. in your layer you can predefine:
     * 
<filesystem>
    <folder name="MyModule">
        <file name="data.xml" url="contents-in-module-jar.xml"/>
    </folder>
</filesystem>

     * 

     * Then in your code use:
     * 
String path = "MyModule/data.xml";
FileSystem sfs = Repository.getDefault().getDefaultFileSystem();
FileObject fo = sfs.findResource(path);
if (fo != null) {
    // use fo.getInputStream() etc.
    // FileUtil.toFile(fo) will often be null, do not rely on it!
}

     * 
     * @param relativePath path from install root, e.g. docs/OpenAPIs.zip
     *                     or modules/autoload/ext/somelib.jar               
     *                     (always using / as a separator, regardless of platform)
     * @param codeNameBase name of the supplying module, e.g. org.netbeans.modules.foo;
     *                     may be null if unknown
     * @param localized true to perform a localized and branded lookup (useful for documentation etc.)
     * @return the requested File, if it can be found, else null
     */
    public abstract File locate(String relativePath, String codeNameBase, boolean localized);
    
    /**
     * Get a master locator.
     * Lookup is searched for all registered locators.
     * They are merged together and called in sequence
     * until one of them is able to service a request.
     * If you use this call, require the token org.openide.modules.InstalledFileLocator
     * to require any autoload modules which can provide locators.
     * @return a master merging locator (never null)
     */
    public static InstalledFileLocator getDefault() {
        return DEFAULT;
    }
    
    private static final InstalledFileLocator DEFAULT = new InstalledFileLocator() {
        public File locate(String rp, String cnb, boolean l) {
            InstalledFileLocator[] ifls = getInstances();
            for (int i = 0; i < ifls.length; i++) {
                File f = ifls[i].locate(rp, cnb, l);
                if (f != null) {
                    return f;
                }
            }
            return null;
        }
    };
    
    private static synchronized InstalledFileLocator[] getInstances() {
        if (instances == null) {
            if (result == null) {
                result = Lookup.getDefault().lookup(new Lookup.Template(InstalledFileLocator.class));
                result.addLookupListener(new LookupListener() {
                    public void resultChanged(LookupEvent e) {
                        synchronized (InstalledFileLocator.class) {
                            instances = null;
                        }
                    }
                });
            }
            Collection/**/ c = result.allInstances();
            instances = (InstalledFileLocator[])c.toArray(new InstalledFileLocator[c.size()]);
        }
        return instances;
    }
    
    private static InstalledFileLocator[] instances = null;
    private static Lookup.Result/**/ result = null;
    
}