Package org.eclipse.equinox.plurl

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_REGISTER_IMPLEMENTATION

      static final String PLURL_REGISTER_IMPLEMENTATION
      An optional plurl protocol operation to register a Plurl instance with the current plurl protocol implementation. This is an optional operation that a Plurl implementation may implement to allow another plurl instance to be registered as a delegate. A delegate may be used to install the delegate plurl instance when the current plurl gets uninstalled.
      See Also:

    • PLURL_UNREGISTER_IMPLEMENTATION

      static final String PLURL_UNREGISTER_IMPLEMENTATION
      An optional plurl protocol operation to unregister a Plurl instance with the current plurl instance set with the JVM. This is an optional operation that a Plurl implementation may implement to allow another plurl instance to be unregistered as a delegate.
      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 the plurl factories into the JVM singletons. If plurl factories are already installed then this plurl instance is registered with the existing plurl instance set with the JVM by using something like the following: 
       ((Consumer<Object>) ("plurl://op/plurlRegisterImplementation").getContent()).accept(this);
      If the plurl factories cannot be installed then an IllegalStateException is thrown.

      If the JVM singletons are already set with other factories that are not plurl then an attempt is made to override the JVM singletons with this plurl instance. This may only be possible if the implementation is allowed to do deep reflection on the java.net package. If the JVM singletons are overriden then the original singleton factory instances must be used as parent factories of the plurl instance until the plurl instance is uninstalled. if overriding the JVM singletons is not possible then an IllegalStateException is thrown.

      If the JVM singletons were not overriden then this plurl instance is considered the primordial singleton factory for the JVM. Such a plurl instance cannot be uninstalled and will live the lifetime of the JVM.

      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.
      4. If plurl factories are already installed then this plurl implementation is registered as a delegate with the already installed plurl instance.
      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

    • uninstall

      void uninstall()
      If this plurl instance is the primordial factory for the JVM then uninstall is a no-op and the plurl instance will remain set with the JVM for the lifetime of the JVM instance.

      If this plurl is not the primordial factory and is the current plurl set with the JVM singletons then this plurl instance must do the following:

      1. Reset the original parent factories as the singleton factories of the JVM
      2. If there are any other plurl instances that got registered with this plurl instance then one of the registered plurl instances must be selected to be the next delegate plurl instance to install.
      3. If a delegate plurl instance gets installed then any existing factories that were added to this plurl instance must be added to the new delegate plurl instance and any registered plurl instances must be registered with the new delegate plurl instance.
      4. This plurl instance must release all references to other factories or plurl instances.
      If this plurl instance is not the current plurl set with JVM then this plurl registered with the existing plurl instance set with the JVM by using something like the following: 
       ((Consumer<Object>) ("plurl://op/plurlRegisterImplementation").getContent()).accept(this);

    • 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