<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/task.dtd">
<task id="howto-custom-protocol-plugin">
  <title>How to Write A Custom Protocol Plugin</title>
  <prolog>
    <metadata>
      <keywords>
        <indexterm>Oxygen SDK<indexterm>Custom Protocol</indexterm></indexterm>
        <indexterm>Plugins<indexterm>Custom Protocol</indexterm></indexterm>
      </keywords>
    </metadata>
  </prolog>
  <taskbody>
    <context>
      <p>To create a custom protocol <xref keyref="glossentry_plugin"><term>plugin</term></xref>,
        follow these steps:</p>
    </context>
    <steps id="procedure-custom-protocol">
      <step>
        <cmd>Write the handler class for your protocol that implements the
            <i>java.net.URLStreamHandler</i> interface.</cmd>
        <info>Be careful to provide ways to encode and decode the URLs of your files.</info>
      </step>
      <step>
        <cmd>Write the <term>plugin</term> class by extending <xref
            href="https://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/exml/plugin/Plugin.html"
            format="html" scope="external"
          ><i>ro.sync.exml.plugin.Plugin</i></xref>.</cmd>
      </step>
      <step>
        <cmd>Write the <term>plugin</term> extension class that implements the <xref
            href="https://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/exml/plugin/urlstreamhandler/URLStreamHandlerPluginExtension.html"
            format="html" scope="external"
              ><i>ro.sync.exml.plugin.urlstreamhandler.URLStreamHandlerPluginExtension</i></xref>
          interface.</cmd>
        <info>
          <p>It is necessary that the <term>plugin</term> extension for the custom protocol
            implements the <i>URLStreamHandlerPluginExtension</i> interface. Without it,
            you cannot use your <term>plugin</term>, because <ph keyref="product"/> is not able to
            find the protocol handler.</p>
          <p>You can choose also to implement the <xref
              href="https://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/exml/plugin/urlstreamhandler/URLChooserPluginExtension.html"
              format="html" scope="external"><i>URLChooserPluginExtension</i></xref>
            interface. It allows you to write and display your own customized dialog box for
            selecting resources that are loaded with the custom protocol.</p>
          <p>An implementation of the extension <xref
              href="https://www.oxygenxml.com/InstData/Editor/SDK/javadoc/ro/sync/exml/plugin/urlstreamhandler/URLHandlerReadOnlyCheckerExtension.html"
              format="html" scope="external"
              ><i>URLHandlerReadOnlyCheckerExtension</i></xref> allows you to:</p>
          <ul>
            <li>Mark a resource as read-only when it is opened.</li>
            <li>Switch between marking the resource as read-only and read-write while it is
              edited.</li>
          </ul>
          <p>It is useful when opening and editing CMS resources.</p>
        </info>
      </step>
      <step>
        <cmd>Write the <filepath>plugin.xml</filepath> descriptor file.</cmd>
        <info>Remember to set the name of the <term>plugin</term> class to the one from the second
          step and the <term>plugin</term> extension class name with the one you have chosen at step
          3.</info>
      </step>
      <step>
        <cmd>Create a <xref keyref="glossentry_jar"><term>JAR</term></xref> archive with all these
          files.</cmd>
      </step>
      <step>
        <cmd>Create a custom plugin folder inside the <b>plugins</b> folder (for example,
              <filepath><term conkeyref="reusables-user-guide/oxy-install-dir"
            />/plugins/myPlugin</filepath>) that contains your new <term>plugin</term>.</cmd>
      </step>
    </steps>
  </taskbody>
</task>