import java.net.URI;

import org.netbeans.modules.xml.api.model.DescriptionSource;

                        @Override

                        public URL getContentURL() {

                            return manpage;

                        }

        @Override

        public DescriptionSource resolveLink(String link) {

            return null;

        }

        @Override

        public boolean isExternal() {

            return false;

        }

        @Override

        public URL getContentURL() {

            return null;

        }

                    <code-name-base>org.netbeans.api.annotations.common</code-name-base>

                    <build-prerequisite/>

                    <compile-dependency/>

                    <run-dependency>

                        <release-version>1</release-version>

                        <specification-version>1.11</specification-version>

                    </run-dependency>

                </dependency>

                <dependency>

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2011 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2011 Sun Microsystems, Inc.

 */

package org.netbeans.modules.xml.api.model;

import java.net.URI;

import java.net.URL;

import org.netbeans.api.annotations.common.CheckForNull;

/**

 * Optional mixin interface, which can be implemented together with the

 * {@link GrammarResult} interface on the returned completion item. 

 * It allows to resolve links and provide description contents.

 * <p/>

 * Implementation may return {@code null} from {@link #getDescription} to 

 * indicate that the system should load contents from the URL supplied by {@link #getContentURL()}.

 * <p/>

 * The implementation may choose to provide the content URL to open within the IDE

 * or in an external browser. Any links will be resolved relatively to that URL.

 * For special cases, the implementation may resolve a link to another instance

 * of DescriptionSource by implementing {@link #resolveLink}.

 * <p/>

 * If both {@link #getDescription} and {@link #getContentURL} return null, there's

 * no description at all for the {@link GrammarResult}.

 * 

 * @author sdedic

 * @since 1.28

 */

public interface DescriptionSource {

    /**

     * Provides text of the description. If the method returns null, the 

     * IDE will try to load contents of the {@link #getContentURL()} and use that

     * as a description.

     * 

     * @return Description contents or {@code null}, if contents should be loaded

     * from {@link #getContentURL}.

     */

    @CheckForNull

    public String  getDescription();

    /**

     * True, if the description can be opened by an external browser, following the

     * {@link #getContentURL}.

     * 

     * @return true, if the content URL can be used outside of the IDE

     */

    public boolean isExternal();

    /**

     * Returns URL for the content, so it can be retrieved. If this URL is provided,

     * any link not resolved by {@link #resolveLink(java.net.URI)} will be treated

     * as relative to this content URL.

     * 

     * @return URL of the description content

     */

    @CheckForNull

    public URL  getContentURL();

    /**

     * Resolves a link in the documentation to another DescriptionSource. Can

     * return null, if the link cannot be resolved.

     * 

     * @param link link found in the text

     * @return resolved description, or {@code null}

     */

    @CheckForNull

    public DescriptionSource  resolveLink(String link);

}

import org.netbeans.api.annotations.common.CheckForNull;

    @CheckForNull

                    <code-name-base>org.netbeans.modules.queries</code-name-base>

                    <build-prerequisite/>

                    <compile-dependency/>

                    <run-dependency>

                        <release-version>1</release-version>

                        <specification-version>1.25</specification-version>

                    </run-dependency>

                </dependency>

                <dependency>

import java.io.IOException;

import java.net.MalformedURLException;

import java.util.logging.Level;

import java.util.logging.Logger;

import org.netbeans.api.queries.FileEncodingQuery;

import org.netbeans.modules.xml.api.model.DescriptionSource;

import org.openide.filesystems.FileObject;

import org.openide.filesystems.URLMapper;

import org.openide.util.Exceptions;

    private static final Logger LOG = Logger.getLogger(XMLResultItem.class.getName());

            private CompletionDocumentation create() {

                String doc;

                doc = res.getDescription();

                if (!(res instanceof DescriptionSource)) {

                    if (doc == null) {

                        return null;

                    }

                    return new Docum(doc);

                } else {

                    DescriptionSource ds = (DescriptionSource)res;

                    if (doc == null && ds.getContentURL() == null) {

                        return null;

                    }

                    return new ExtDocum(ds,  doc);

                }

            }

    /**

     * Extended documentation, based on the {@link DescriptionSource} SPI.

     */

    private static class ExtDocum extends URLDocum implements CompletionDocumentation {

        private DescriptionSource src;

        private String doc;

        ExtDocum(DescriptionSource src, String doc) {

            super(src.getContentURL(), src.isExternal());

            this.src = src;

            this.doc = doc;

        }

        @Override

        public String getText() {

            if (doc == null) {

                doc = src.getDescription();

                if (doc == null) {

                    doc = super.getText();

                }

            }

            return doc;

        }

        @Override

        public CompletionDocumentation resolveLink(String link) {

            try {

                DescriptionSource target = src.resolveLink(link);

                if (target != null) {

                    return new ExtDocum(target, null);

                }

                URL base = src.getContentURL();

                if (base == null) {

                    // sorry, cannot resolve.

                    return null;

                }

                URL targetURL = new URL(base, link);

                return new URLDocum(targetURL, src.isExternal());

            } catch (MalformedURLException ex) {

                Exceptions.printStackTrace(ex);

                return null;

            }

        }

        @Override

        public Action getGotoSourceAction() {

            return null;

        }

    }

    /**

     * Pure URL documentation item. Resolves links, if original URL was able

     * to open externally, the derived URLs do it as well.

     */

    private static class URLDocum implements CompletionDocumentation {

        URL content;

        boolean external;

        URLDocum(URL content, boolean external) {

            this.content = content;

            this.external = external;

        }

        URLDocum(boolean external) {

            this.external = external;

        }

        @Override

        public Action getGotoSourceAction() {

            return null;

        }

        @Override

        public String getText() {

            FileObject f = URLMapper.findFileObject(content);

            if (f != null) {

                try {

                    return new String(f.asBytes(), FileEncodingQuery.getEncoding(f));

                } catch (IOException x) {

                    LOG.log(Level.INFO, "Could not load " + content, x);

                }

            }

            return null;

        }

        @Override

        public URL getURL() {

            return external ? content : null;

        }

        @Override

        public CompletionDocumentation resolveLink(String link) {

            if (content == null) {

                return null;

            }

            try {

                return new URLDocum(new URL(content, link), external);

            } catch (MalformedURLException ex) {

                Exceptions.printStackTrace(ex);

                return null;

            }

        }

    }