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} 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;

     * Returns contents of a description, text suitable for displaying as a tooltip

     * that simplifies decision. {@code null} may be returned if no description is available.

     * The decription is interpreted as HTML markup. If the markup contains relative

     * links or special URIs, implement also {@link DescriptionSource} to resolve 

     * those links.

     * <p/>

     * If {@link DescriptionSource} is implemented on the same object, this method

     * may return null to indicate the content should be <b>loaded by the infrastructure</b>

     * from the URL returned by {@link DescriptionSource#getContentURL()}. If both

     * {@code getDescription()} and {@code DescriptionSource.getContentURL()} return

     * null, no description is displayed in the tooltip.

     * <p/>

     * Implementors may prefer implementing the {@code DescriptionSource} and

     * loading from the {@link DescriptionSource#getContentURL()} if the

     * description resides in a separate file included in the JAR or in the XML layer.

     * 

    @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);

                // leave the VM as soon as possible. This hack uses URLMappers

                // to find out whether URL (converted to FO and back) can be

                // represented outside the VM

                boolean external = true;

                FileObject f = URLMapper.findFileObject(targetURL);

                if (f != null) {

                    external = URLMapper.findURL(f, URLMapper.EXTERNAL) != null;

                }

                return new URLDocum(targetURL, external);

            } 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() {

            if (content == null) {

                return null;

            }

            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;

            }

        }

    }

/*

 * 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.text.completion;

import java.lang.reflect.Constructor;

import java.net.URL;

import javax.swing.Icon;

import org.netbeans.junit.NbTestCase;

import org.netbeans.junit.NbTestSuite;

import org.netbeans.modules.editor.completion.CompletionImpl;

import org.netbeans.modules.editor.completion.CompletionResultSetImpl;

import org.netbeans.modules.xml.api.EncodingUtil;

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

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

import org.netbeans.modules.xml.spi.dom.AbstractNode;

import org.netbeans.spi.editor.completion.CompletionDocumentation;

import org.netbeans.spi.editor.completion.CompletionProvider;

import org.netbeans.spi.editor.completion.CompletionResultSet;

import org.netbeans.spi.editor.completion.CompletionTask;

/**

 * Checks behaviour of {@link GrammarResult} support in the ElementResultItem.

 * plain CompletionDocumentation must work unchanged. If mixin interface is implemented,

 * explicit values (content, resolved links) must take precedence.

 * <p/>

 * If contentURL is provided, links must be resolved and content loaded by the 

 * ElementResultItem support even though the supplied CompletionDocumentation itself does not 

 * provide content/links.

 * 

 * @author sdedic

 */

public class ElementResultItemDocumentationTest extends NbTestCase {

    public static NbTestSuite suite() {

        NbTestSuite suite = new NbTestSuite();

        suite.addTestSuite(ElementResultItemDocumentationTest.class);

        return suite;

    }

    public ElementResultItemDocumentationTest(String name) {

        super(name);

    }

    @Override

    protected void setUp() throws Exception {

        super.setUp();

    }

    @Override

    protected void tearDown() throws Exception {

        super.tearDown();

    }

    private CompletionResultSetImpl rsImpl;

    private CompletionResultSet resultSetFor(CompletionTask task, int type) throws Exception {

        rsImpl = createCompletionResultImpl(task, type);

        return rsImpl.getResultSet();

    }

    private CompletionResultSetImpl createCompletionResultImpl(CompletionTask task, int type) throws Exception {

        Class clazz = CompletionResultSetImpl.class;

        Constructor ctor = clazz.getDeclaredConstructor(CompletionImpl.class, Object.class, CompletionTask.class, Integer.TYPE);

        ctor.setAccessible(true);

        return (CompletionResultSetImpl)ctor.newInstance(CompletionImpl.get(), "", task, type);

    }

    /**

     * Check the previou state, result items without the mixin interface. 

     * Should return the description 'as is'

     * 

     * @throws Exception 

     */

    private static final String PLAIN_DESCRIPTION_TEXT = "Plain description";

    public void testPlainContent() throws Exception {

        MockGrammarResult r = new MockGrammarResult();

        r.setDescription(PLAIN_DESCRIPTION_TEXT);

        ElementResultItem item = new ElementResultItem(0, r);

        CompletionTask task = item.doCreateDocumentationTask(r);

        CompletionResultSet rs = resultSetFor(task, CompletionProvider.DOCUMENTATION_QUERY_TYPE);

        task.query(rs);

        assertTrue(rs.isFinished());

        assertEquals(PLAIN_DESCRIPTION_TEXT, rsImpl.getDocumentation().getText());

        // should return null from the url.

        assertNull(rsImpl.getDocumentation().getURL());

        // should not be able to resolve links

        assertNull(rsImpl.getDocumentation().resolveLink("link"));

    }

    private URL  createResourceName(String n) {

        return ElementResultItemDocumentationTest.class.getResource(n);

    }

    private CompletionDocumentation createDocResourceResultSet(MockUrlGrammarResult r) throws Exception {

        if (r == null) {

            r = new MockUrlGrammarResult();

            r.setContentURL(createResourceName("res/docResource.html"));

            r.setExternal(true);

        }

        ElementResultItem item = new ElementResultItem(0, r);

        CompletionTask task = item.doCreateDocumentationTask(r);

        CompletionResultSet rs = resultSetFor(task, CompletionProvider.DOCUMENTATION_QUERY_TYPE);

        task.query(rs);

        assertTrue(rs.isFinished());

        return rsImpl.getDocumentation();

    }

    /**

     * Checks that custom contents overrides the one supplied by XMLResultItem

     * 

     * @throws Exception 

     */

    public void testCustomContent() throws Exception {

        URL res = EncodingUtil.class.getResource("/org/netbeans/modules/xml/core/resources/Bundle.properties");

        MockUrlGrammarResult test = new MockUrlGrammarResult();

        test.setContentURL(res);

        test.setExternal(false);

        test.setDescription(PLAIN_DESCRIPTION_TEXT);

        CompletionDocumentation doc = createDocResourceResultSet(test);

        assertNull(doc.getURL());

        assertEquals("Invalid content", PLAIN_DESCRIPTION_TEXT, doc.getText());

    }

    /**

     * Checks documentation bundled in a JAR - not openable by external browser.

     * Need a resource within a JAR

     * 

     * @throws Exception 

     */

    public void testInternalUrlDocumentation() throws Exception {

        URL res = EncodingUtil.class.getResource("/org/netbeans/modules/xml/core/resources/Bundle.properties");

        MockUrlGrammarResult test = new MockUrlGrammarResult();

        test.setContentURL(res);

        test.setExternal(false);

        CompletionDocumentation doc = createDocResourceResultSet(test);

        assertNull(doc.getURL());

        assertTrue(doc.getText().contains("OpenIDE-Module-Name=XML Core"));

        // check that relative links still resolve to internal doc

        CompletionDocumentation  internal = doc.resolveLink("mf-layer.xml");

        assertNotNull("Relative links must be resolvable", internal);

        assertNull("Relative links cannot be opened in extbrowser", doc.getURL());

        assertTrue("Content must be accessible", 

                internal.getText().contains("org-netbeans-modules-xml-dtd-grammar-DTDGrammarQueryProvider.instance"));

        // check that absolute links resolve to external doc

        CompletionDocumentation  external = doc.resolveLink("http://www.netbeans.org");

        assertNotNull("Absolute links must be resolvable", external);

        assertEquals("Absolute links must have URL", external.getURL(), new URL("http://www.netbeans.org"));

    }

    /**

     * Checks that file-based documentation reverts to external as soon as possible

     * @throws Exception 

     */

    public void testFileDocumentation() throws Exception {

        URL res = EncodingUtil.class.getResource("/org/netbeans/modules/xml/core/resources/Bundle.properties");

        MockUrlGrammarResult test = new MockUrlGrammarResult();

        test.setContentURL(res);

        test.setExternal(false);

        CompletionDocumentation doc = createDocResourceResultSet(test);

        assertNull(doc.getURL());

        assertTrue("Invalid content", doc.getText().contains("OpenIDE-Module-Name=XML Core"));

        // check that resolve of file-based URL turns the doc to external:

        URL url = createResourceName("res/docResource.html");

        CompletionDocumentation  file = doc.resolveLink(url.toString());

        assertNotNull(file);

        assertEquals("URL must be openable in browser", url, file.getURL());

        assertTrue("Invalid content of the linked doc", file.getText().startsWith("This is an URL resource with <a href="));

    }

    /**

     * Checks that relative and .. link resolution works OK.

     * 

     * @throws Exception 

     */

    public void testResolveRelativeLinks() throws Exception {

        CompletionDocumentation doc = createDocResourceResultSet(null);

        assertEquals(createResourceName("res/docResource.html"), doc.getURL());

        CompletionDocumentation linked = doc.resolveLink("relativeLink1.html");

        assertNotNull(linked);

        assertEquals("Relative link must be resolved", createResourceName("res/relativeLink1.html"), linked.getURL());

        linked = doc.resolveLink("../parentDoc.html");

        assertNotNull(linked);

        assertEquals("Link to resource in parent folder must be resolved", createResourceName("parentDoc.html"), linked.getURL());

    }

    /**

     * Checks that DS returning 'external' provides URL and resolves links, although

     * no custom resolver is given

     * 

     * @throws Exception 

     */

    public void testNetworkUrlDocumentation() throws Exception {

        MockUrlGrammarResult test = new MockUrlGrammarResult();

        test.setExternal(true);

        test.setContentURL(new URL("http://www.netbeans.org"));

        CompletionDocumentation doc = createDocResourceResultSet(test);

        assertEquals("External documentation must have URL", new URL("http://www.netbeans.org"), doc.getURL());

        CompletionDocumentation resolved = doc.resolveLink("index.html");

        assertEquals("Resolved external link must have URL", new URL("http://www.netbeans.org/index.html"), resolved.getURL());

    }

    /**

     * Checks that without content URL, no item is produced

     * @throws Exception 

     */

    public void testNoContentUrl() throws Exception {

        MockUrlGrammarResult res = new MockUrlGrammarResult();

        CompletionDocumentation doc = createDocResourceResultSet(res);

        assertNull(doc);

    }

    public void testCustomResolveLink() throws Exception {

        MockUrlGrammarResult res = new MockUrlGrammarResult() {

            // resolves relative links in different directory

            @Override

            public DescriptionSource resolveLink(String link) {

                MockUrlGrammarResult res = new MockUrlGrammarResult();

                URL base = createResourceName("res/" + link);

                res.setContentURL(base);

                res.setExternal(link.contains("Exist.html"));

                if (link.contains("customContent")) {

                    res.setDescription(PLAIN_DESCRIPTION_TEXT);

                }

                return res;

            }

        };

        res.setContentURL(createResourceName("res/docResource.html"));

        CompletionDocumentation doc = createDocResourceResultSet(res);

        // doc does not exist, but documentation item is there

        CompletionDocumentation notExisting = doc.resolveLink("doesNotExist.html");

        assertNotNull(notExisting);

        //  it is external, as defined by custom resolver

        assertEquals(createResourceName("doesNotExist.html"), notExisting.getURL());

        // but contents cannot be fetched by the framework

        assertNull("Supplied description must take precedence", notExisting.getText());

        // existing item

        CompletionDocumentation resolved = doc.resolveLink("relativeLink1.html");

        // custom resolver says this is an internal link!

        assertNull("Must not be openable in browser", resolved.getURL());

        // fwk is able to fetch contents

        assertTrue("Framework must fetch contents of linked URL", 

                resolved.getText().startsWith("Resource referenced by relative link"));

        CompletionDocumentation parent = doc.resolveLink("customContent");

        assertEquals(PLAIN_DESCRIPTION_TEXT, parent.getText());

    }

    private static class MockUrlGrammarResult extends MockGrammarResult implements DescriptionSource {

        private URL contentURL;

        private boolean external;

        public void setContentURL(URL contentURL) {

            this.contentURL = contentURL;

        }

        public void setExternal(boolean external) {

            this.external = external;

        }

        @Override

        public URL getContentURL() {

            return contentURL;

        }

        @Override

        public boolean isExternal() {

            return external;

        }

        @Override

        public DescriptionSource resolveLink(String link) {

            return null;

        }

    }

    private static class MockGrammarResult extends AbstractNode implements GrammarResult {

        private String description;

        private String displayName;

        public void setDescription(String description) {

            this.description = description;

        }

        public void setDisplayName(String displayName) {

            this.displayName = displayName;

        }

        @Override

        public String getDescription() {

            return description;

        }

        @Override

        public String getDisplayName() {

            return displayName;

        }

        @Override

        public Icon getIcon(int kind) {

            return null;

        }

        @Override

        public boolean isEmptyElement() {

            return false;

        }

        @Override

        public short getNodeType() {

            return ELEMENT_NODE;

        }

    }

}

Document in parent directory

This is an URL resource with <a href="relativeLink1.html">relative link</a> and

<a href="http://www.seznam.cz">absolute link</a>

Resource referenced by relative link