FileDocCategorySizeDatePackage
Extern.javaAPI DocExample8371Wed Apr 19 11:17:10 BST 2000com.sun.tools.doclets.standard

Extern

public class Extern extends Object
Process and manage "-link" and "-linkoffline" to external packages. The options "-link" and "-linkoffline" both depend on the fact that Javadoc now generates "package-list"(lists all the packages which are getting documented) file in the current or the destination directory, while generating the documentation.
author
Atul M Dambalkar
author
Robert Field

Fields Summary
private static Map
packageMap
Map package names on to this object.
final String
packageName
Package name, found in the "package-list" file in the {@link path}.
final String
path
The URL or the directory path at which the package documentation will be avaliable.
final boolean
relative
If given path is directory path then true else if it is a URL then false.
Constructors Summary
Extern(String packageName, String path, boolean relative)
Constructor to build a Extern object and map it with the package name. If the same package name is found in the map, then the first mapped Extern object or offline location will be retained.

param
packagename Package name found in the "package-list" file.
param
path URL or Directory path from where the "package-list" file is picked.
param
relative True if path is URL, false if directory path.

        this.packageName = packageName;
        this.path = path;
        this.relative = relative;
        if (packageMap == null) {
            packageMap = new HashMap();
        }
        if (!packageMap.containsKey(packageName)) { // save the previous 
	  packageMap.put(packageName, this);        // mapped location
        }
Methods Summary
static java.lang.StringadjustEndFileSeparator(java.lang.String url)
If the URL or Directory path is missing end file separator, add that.

        String filesep = isRelativePath(url)? File.separator: "/";
        if (!url.endsWith(filesep)) {
            url += filesep; 
        }
        return url;
static java.lang.StringcomposeExternPackageList(java.lang.String url, java.lang.String pkglisturl)
Adjusts the end file separator if it is missing from the URL or the directory path and depending upon the URL or file path, it fetches or reads the "package-list" file.

param
url URL or the directory path.
param
pkglisturl URL for the "package-list" file or the "package-list" file itself.

        url = adjustEndFileSeparator(url);
        pkglisturl = adjustEndFileSeparator(pkglisturl);
        if (pkglisturl.startsWith("http://") ||   
            pkglisturl.startsWith("file:")) {
            return fetchURLComposeExternPackageList(url, pkglisturl);
        } else {
            return readFileComposeExternPackageList(url, pkglisturl);
        }
static java.lang.StringfetchURLComposeExternPackageList(java.lang.String urlpath, java.lang.String pkglisturlpath)
Fetch the URL and read the "package-list" file.

param
urlpath Path to the packages.
param
pkglisturlpath URL or the path to the "package-list" file.

        String link = pkglisturlpath + "package-list"; 
        try {
            boolean relative = isRelativePath(urlpath);
            readPackageList((new URL(link)).openStream(), urlpath, relative);
        } catch (MalformedURLException exc) {
            return getText("doclet.MalformedURL", link);
        } catch (IOException exc) {
            return getText("doclet.URL_error", link);
        } 
        return null;
public static com.sun.tools.doclets.standard.ExternfindPackage(java.lang.String pkgName)
Get the "Extern" object associated with this package name.

param
pkgname Package name.

        if (packageMap == null) {
            return null;
        }
        return (Extern)packageMap.get(pkgName);
private static java.lang.StringgetText(java.lang.String prop, java.lang.String link)
Retrieve the text from the resource bundle.

param
prop Message key.
param
link Message argument.

        return Standard.configuration().standardmessage.getText(prop, link);
private static java.lang.StringgetText(java.lang.String msg)
Retrieve the text from the resource bundle.

param
msg Message key.

        return Standard.configuration().standardmessage.getText(msg);
static booleanisRelativePath(java.lang.String url)
Return true if it's a relative file path and does not start with "http://" or "file:" string.

        return !(url.startsWith("http://") || url.startsWith("file:"));
static java.lang.StringreadFileComposeExternPackageList(java.lang.String urlpath, java.lang.String relpath)
Read the "package-list" file which is available locally.

param
urlpath URL or Directory path to hte packages.
param
relpath Path to the local "package-list" file.

        String link = relpath + "package-list";
        try {
            File file = new File(link);    
            if (file.exists() && file.canRead()) {
                boolean relative = isRelativePath(urlpath);
                readPackageList(new FileInputStream(file), urlpath, relative);
            } else {
                return getText("doclet.File_error", link);
            }
        } catch (FileNotFoundException exc) {
            return getText("doclet.File_error", link);
        } catch (IOException exc) {
            return getText("doclet.File_error", link);
        }
        return null;
static voidreadPackageList(java.io.InputStream input, java.lang.String path, boolean relative)
Read the file "package-list" and for each package name found, create Extern object and associate it with the package name in the map.

param
input InputStream from the "package-list" file.
param
path URL or the directory path to the packages.
param
relative Is path relative?

        InputStreamReader in = new InputStreamReader(input);
        StringBuffer strbuf = new StringBuffer();
        try {
            int c;
            while ((c = in.read()) >= 0) {
                char ch = (char)c;
                if (ch == '\n" || ch == '\r") {
                    if (strbuf.length() > 0) {
                        String packname = strbuf.toString();
                        String packpath = path + 
                                      packname.replace('.", '/") + '/";
                        new Extern(packname, packpath, relative); 
                        strbuf.setLength(0);
                    }
                } else {
                    strbuf.append(ch);
                }
            }
        } finally {
            input.close();
        }
public java.lang.StringtoString()
String representation of "this" with packagename and the path.

        return packageName + (relative? " -> " : " => ") + path;
public static booleanurl(java.lang.String url, java.lang.String pkglisturl, com.sun.javadoc.DocErrorReporter reporter)
Build the extern package list from given URL or the directory path. Flag error if the "-link" or "-linkoffline" option is already used.

param
url URL or Directory path.
param
pkglisturl This can be another URL for "pacakge-list" or ordinary file.

        String errMsg = composeExternPackageList(url, pkglisturl);
        if (errMsg != null) {
            reporter.printError(errMsg);
            return false;
        } else {
            return true;
        }