# URL Stream Handler Service

###### Identifier:

org.eclipse.ecf.filetransfer.urlStreamHandlerService

###### Since:

1.0.0.M5

###### Description:

This extension point allows plugins to define an URLStreamHandlerService associated with an URL protocol. So, for example, if a plugin wants to setup a new URL protocol 'foobar', it can declare the following:

       <extension
             point="org.eclipse.ecf.filetransfer.urlStreamHandlerService">
          <urlStreamHandlerService
                protocol="foobar"
                serviceClass="org.eclipse.ecf.tests.filetransfer.TestURLStreamHandlerService">
          </urlStreamHandlerService>
       </extension>

When an URL with protocol 'foobar' is created:

    // Create URL with 'foobar' protocol
    URL url = new URL("foobar://myurlcontents/can/be?whatever=we&want=.");
    // Open connection to resource defined by URL
    URLConnection connection = url.openConnection();

When the URL is created the serviceClass `TestURLStreamHandlerService` will be called to parse the URL, and when the URL.openConnection() method is called on this URL, the serviceClass `TestURLStreamHandlerService.openConnection(URL u)` method will be called, allowing the registered serviceClass to create, connect, and return an URLConnection instance using any appropriate protocol. Here's an example implementation for `TestURLStreamHandlerService`:

    public class TestURLStreamHandlerService extends
      AbstractURLStreamHandlerService {

     }
     /* (non-Javadoc)
      * @see org.osgi.service.url.AbstractURLStreamHandlerService#openConnection(java.net.URL)
      */
     public URLConnection openConnection(URL u) throws IOException {
      return new TestHttpURLConnection(u);
     }

    }

Note that the class `org.eclipse.ecf.tests.filetransfer.TestURLStreamHandlerService` must extend the `org.osgi.service.url.AbstractURLStreamHandlerService` abstract service class.

###### Configuration Markup:

<!ELEMENT extension (urlStreamHandlerService)+>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

<!ELEMENT urlStreamHandlerService EMPTY>

<!ATTLIST urlStreamHandlerService

protocol CDATA #REQUIRED

serviceClass CDATA #REQUIRED>

- protocol - protocol name for use in URL instance creation.
- serviceClass - Implementation class. Must extend `org.osgi.service.url.AbstractURLStreamHandlerService`.

###### Examples:

Here is an example declaration of a serviceClass associated with an URL protocol:

       <extension
             point="org.eclipse.ecf.filetransfer.urlStreamHandlerService">
          <urlStreamHandlerService
                protocol="foobar"
                serviceClass="org.eclipse.ecf.tests.filetransfer.TestURLStreamHandlerService">
          </urlStreamHandlerService>
       </extension>

###### API Information:

Here is the API for the serviceClass:

    /**
     * Abstract implementation of the <code>URLStreamHandlerService</code> interface.
     * All the methods simply invoke the corresponding methods on
     * <code>java.net.URLStreamHandler</code> except for <code>parseURL</code> and
     * <code>setURL</code>, which use the <code>URLStreamHandlerSetter</code>
     * parameter. Subclasses of this abstract class should not need to override the
     * <code>setURL</code> and <code>parseURL(URLStreamHandlerSetter,...)</code>
     * methods.
     *
     * @version $Revision: 1.2 $
     */
    public abstract class AbstractURLStreamHandlerService extends URLStreamHandler
      implements URLStreamHandlerService {
     /**
      * @see "java.net.URLStreamHandler.openConnection"
      */
     public abstract URLConnection openConnection(URL u)
       throws java.io.IOException;

     /**
      * The <code>URLStreamHandlerSetter</code> object passed to the parseURL
      * method.
      */
     protected URLStreamHandlerSetter realHandler;

     /**
      * Parse a URL using the <code>URLStreamHandlerSetter</code> object. This
      * method sets the <code>realHandler</code> field with the specified
      * <code>URLStreamHandlerSetter</code> object and then calls
      * <code>parseURL(URL,String,int,int)</code>.
      *
      * @param realHandler The object on which the <code>setURL</code> method must
      *        be invoked for the specified URL.
      * @see "java.net.URLStreamHandler.parseURL"
      */
     public void parseURL(URLStreamHandlerSetter realHandler, URL u,
       String spec, int start, int limit) {
      this.realHandler = realHandler;
      parseURL(u, spec, start, limit);
     }

     /**
      * This method calls <code>super.toExternalForm</code>.
      *
      * @see "java.net.URLStreamHandler.toExternalForm"
      */
     public String toExternalForm(URL u) {
      return super.toExternalForm(u);
     }

     /**
      * This method calls <code>super.equals(URL,URL)</code>.
      *
      * @see "java.net.URLStreamHandler.equals(URL,URL)"
      */
     public boolean equals(URL u1, URL u2) {
      return super.equals(u1, u2);
     }

     /**
      * This method calls <code>super.getDefaultPort</code>.
      *
      * @see "java.net.URLStreamHandler.getDefaultPort"
      */
     public int getDefaultPort() {
      return super.getDefaultPort();
     }

     /**
      * This method calls <code>super.getHostAddress</code>.
      *
      * @see "java.net.URLStreamHandler.getHostAddress"
      */
     public InetAddress getHostAddress(URL u) {
      return super.getHostAddress(u);
     }

     /**
      * This method calls <code>super.hashCode(URL)</code>.
      *
      * @see "java.net.URLStreamHandler.hashCode(URL)"
      */
     public int hashCode(URL u) {
      return super.hashCode(u);
     }

     /**
      * This method calls <code>super.hostsEqual</code>.
      *
      * @see "java.net.URLStreamHandler.hostsEqual"
      */
     public boolean hostsEqual(URL u1, URL u2) {
      return super.hostsEqual(u1, u2);
     }

     /**
      * This method calls <code>super.sameFile</code>.
      *
      * @see "java.net.URLStreamHandler.sameFile"
      */
     public boolean sameFile(URL u1, URL u2) {
      return super.sameFile(u1, u2);
     }

     /**
      * This method calls
      * <code>realHandler.setURL(URL,String,String,int,String,String)</code>.
      *
      * @see "java.net.URLStreamHandler.setURL(URL,String,String,int,String,String)"
      * @deprecated This method is only for compatibility with handlers written
      *             for JDK 1.1.
      */
     protected void setURL(URL u, String proto, String host, int port,
       String file, String ref) {
      realHandler.setURL(u, proto, host, port, file, ref);
     }

     /**
      * This method calls
      * <code>realHandler.setURL(URL,String,String,int,String,String,String,String)</code>.
      *
      * @see "java.net.URLStreamHandler.setURL(URL,String,String,int,String,String,String,String)"
      */
     protected void setURL(URL u, String proto, String host, int port,
       String auth, String user, String path, String query, String ref) {
      realHandler.setURL(u, proto, host, port, auth, user, path, query, ref);
     }
    }

###### Supplied Implementation:

No supplied implementation.

Copyright (c) 2004 Composent, Inc. and others. This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at https://www.eclipse.org/legal/epl-2.0/ SPDX-License-Identifier: EPL-2.0