Interface Plurl

All Known Implementing Classes:
PlurlImpl

public interface Plurl
Plurl is used to multiplex the URL factory singletons for URL.setURLStreamHandlerFactory(URLStreamHandlerFactory) and URLConnection.setContentHandlerFactory(ContentHandlerFactory). Plurl factories may be added and removed using the add and remove methods or using the plurl protocol.

The plurl protocol allows factories to be added even if the installed plurl implementation is not using the same org.eclipse.equinox.plurl package as the factories being registered. A plurl implementation must handle this case by reflecting on the plurl factories that are added. A plurl factory can be added and removed with the plurl protocol like this:

 PlurlStreamHandlerFactory myStreamFactory = getStreamFactory();
 PlurlContentHandlerFactory myContentFactory = getContentFactory();
 
 ((Consumer<URLStreamHandlerFactory>) ("plurl://op/addURLStreamHandlerFactory").getContent()).accept(myStreamFactory);
 ((Consumer<ContentHandlerFactory>) ("plurl://op/addContentHandlerFactory").getContent()).accept(myContentFactory);

 ((Consumer<URLStreamHandlerFactory>) ("plurl://op/removeURLStreamHandlerFactory").getContent())
                .accept(myStreamFactory);
 ((Consumer<ContentHandlerFactory>) ("plurl://op/removeContentHandlerFactory").getContent()).accept(myContentFactory);
 
The content provided by the plurl protocol is of type Consumer which can take either an URLStreamHandlerFactory or a ContentHandlerFactory depending on the operation.

A plurl implementation delegates to the added PlurlFactory objects. To select which PlurlFactory to delegate the PlurlFactory.shouldHandle(Class) method is used.

If only one factory has been added to plurl then that PlurlFactory is used to create the handler. Otherwise each PlurlFactory.shouldHandle(Class) is called for a class in the call stack until a factory returns true. If no factory returns true then the next class in the call stack is used. If no factory is found after using all classes in the call stack then the first factory added is selected. Once a factory is selected, it is used to create the requested handler. If the selected factory returns a null handler then no other factory is asked to create the handler.

See Also:
  • Field Details

    • PLURL_PROTOCOL

      static final String PLURL_PROTOCOL
      The "plurl" protocol to add and remove plurl factories.
      See Also:
    • PLURL_OP

      static final String PLURL_OP
      The host to use for the "plurl" protocol to indicate an operation for adding or removing factories.
      See Also:
    • PLURL_ADD_URL_STREAM_HANDLER_FACTORY

      static final String PLURL_ADD_URL_STREAM_HANDLER_FACTORY
      The plurl protocol operation to add a URLStreamHandlerFactory
      See Also:
    • PLURL_REMOVE_URL_STREAM_HANDLER_FACTORY

      static final String PLURL_REMOVE_URL_STREAM_HANDLER_FACTORY
      The plurl protocol operation to remove a URLStreamHandlerFactory
      See Also:
    • PLURL_ADD_CONTENT_HANDLER_FACTORY

      static final String PLURL_ADD_CONTENT_HANDLER_FACTORY
      The plurl protocol operation to add a ContentStreamHandlerFactory
      See Also:
    • PLURL_REMOVE_CONTENT_HANDLER_FACTORY

      static final String PLURL_REMOVE_CONTENT_HANDLER_FACTORY
      The plurl protocol operation to remove a ContentStreamHandlerFactory
      See Also:
    • PLURL_FORBID_NOTHING

      static final String PLURL_FORBID_NOTHING
      The value to use for the install(String...) method to indicate that no protocols are forbidden. for overriding by plurl handlers.
      See Also:
  • Method Details

    • install

      void install(String... forbidden)
      Installs plurl factories into the JVM singletons. If plurl factories are already installed then this is a no-op. If the plurl factories cannot be installed then an IllegalStateException is thrown.

      When this method returns without throwing an exception then the following will be true:

      1. The singleton URL.setURLStreamHandlerFactory(URLStreamHandlerFactory) is set with a plurl implementation which delegates to the PlurlStreamHandlerFactory objects that have been added.
      2. The singleton URLConnection.setContentHandlerFactory(ContentHandlerFactory) is set with a plurl implementation which delegates to the PlurlContentHandlerFactory objects that have been added.
      3. The plurl protocol is available for creating URL objects.
      Parameters:
      forbidden - builtin JVM protocols that cannot be overridden by plurl. If no forbidden protocols are specified then the default forbidden protocols are 'jar', 'jmod', 'file', and 'jrt'. To forbid no protocols then use the value PLURL_FORBID_NOTHING
      Throws:
      IllegalStateException - if the Plurl factories cannot be installed
    • add

      static void add(PlurlStreamHandlerFactory factory) throws IOException
      Adds a PlurlStreamHandlerFactory to an installed plurl implementation. If there is no plurl implementation installed then an IOException is thrown. The plurl implementation must not hold any strong references to the factory. If the factory is garbage collected then the plurl implementation must behave as if the factory got removed.

      This is a convenience method for using the plurl protocol like this:

       ((Consumer<URLStreamHandlerFactory>) ("plurl://op/addURLStreamHandlerFactory").getContent()).accept(factory);
       
      Parameters:
      factory - the PlurlStreamHandlerFactory to add
      Throws:
      IOException - if there is no plurl implementation installed or there was an error adding the factory
    • remove

      static void remove(PlurlStreamHandlerFactory factory) throws IOException
      Removes a PlurlStreamHandlerFactory to an installed plurl implementation. If there is no plurl implementation installed then an IOException is thrown.

      This is a convenience method for using the plurl protocol like this:

       ((Consumer<URLStreamHandlerFactory>) ("plurl://op/removeURLStreamHandlerFactory").getContent()).accept(factory);
       
      Parameters:
      factory - the PlurlStreamHandlerFactory to remove
      Throws:
      IOException - if there is no plurl implementation installed or there was an error removing the factory
    • add

      static void add(PlurlContentHandlerFactory factory) throws IOException
      Adds a PlurlContentHandlerFactory from an installed plurl implementation. If there is no plurl implementation installed then an IOException is thrown. The plurl implementation must not hold any strong references to the factory. If the factory is garbage collected then the plurl implementation must behave as if the factory got removed.

      This is a convenience method for using the plurl protocol like this:

       ((Consumer<ContentHandlerFactory>) ("plurl://op/addContentHandlerFactory").getContent()).accept(factory);
       
      Parameters:
      factory - the PlurlContentHandlerFactory to add
      Throws:
      IOException - if there is no plurl implementation installed or there was an error adding the factory
    • remove

      static void remove(PlurlContentHandlerFactory factory) throws IOException
      Removes a PlurlContentHandlerFactory from an installed plurl implementation. If there is no plurl implementation installed then an IOException is thrown.

      This is a convenience method for using the plurl protocol like this:

       ((Consumer<ContentHandlerFactory>) ("plurl://op/removeContentHandlerFactory").getContent()).accept(factory);
       
      Parameters:
      factory - the PlurlContentHandlerFactory to remove
      Throws:
      IOException - if there is no plurl implementation installed or there was an error removing the factory