Interface Plurl
- All Known Implementing Classes:
PlurlImpl
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 Summary
FieldsModifier and TypeFieldDescriptionstatic final StringThe plurl protocol operation to add a ContentStreamHandlerFactorystatic final StringThe plurl protocol operation to add a URLStreamHandlerFactorystatic final StringThe value to use for theinstall(String...)method to indicate that no protocols are forbidden. for overriding by plurl handlers.static final StringThe host to use for the "plurl" protocol to indicate an operation for adding or removing factories.static final StringThe "plurl" protocol to add and remove plurl factories.static final StringThe plurl protocol operation to remove a ContentStreamHandlerFactorystatic final StringThe plurl protocol operation to remove a URLStreamHandlerFactory -
Method Summary
Modifier and TypeMethodDescriptionstatic voidadd(PlurlContentHandlerFactory factory) Adds aPlurlContentHandlerFactoryfrom aninstalledplurl implementation.static voidadd(PlurlStreamHandlerFactory factory) Adds aPlurlStreamHandlerFactoryto aninstalledplurl implementation.voidInstalls plurl factories into the JVM singletons.static voidremove(PlurlContentHandlerFactory factory) Removes aPlurlContentHandlerFactoryfrom aninstalledplurl implementation.static voidremove(PlurlStreamHandlerFactory factory) Removes aPlurlStreamHandlerFactoryto aninstalledplurl implementation.
-
Field Details
-
PLURL_PROTOCOL
The "plurl" protocol to add and remove plurl factories.- See Also:
-
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
The plurl protocol operation to add a URLStreamHandlerFactory- See Also:
-
PLURL_REMOVE_URL_STREAM_HANDLER_FACTORY
The plurl protocol operation to remove a URLStreamHandlerFactory- See Also:
-
PLURL_ADD_CONTENT_HANDLER_FACTORY
The plurl protocol operation to add a ContentStreamHandlerFactory- See Also:
-
PLURL_REMOVE_CONTENT_HANDLER_FACTORY
The plurl protocol operation to remove a ContentStreamHandlerFactory- See Also:
-
PLURL_FORBID_NOTHING
The value to use for theinstall(String...)method to indicate that no protocols are forbidden. for overriding by plurl handlers.- See Also:
-
-
Method Details
-
install
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 anIllegalStateExceptionis thrown.When this method returns without throwing an exception then the following will be true:
- The singleton
URL.setURLStreamHandlerFactory(URLStreamHandlerFactory)is set with a plurl implementation which delegates to thePlurlStreamHandlerFactoryobjects that have beenadded. - The singleton
URLConnection.setContentHandlerFactory(ContentHandlerFactory)is set with a plurl implementation which delegates to thePlurlContentHandlerFactoryobjects that have beenadded. - The plurl protocol is available for creating
URLobjects.
- 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 valuePLURL_FORBID_NOTHING- Throws:
IllegalStateException- if the Plurl factories cannot be installed
- The singleton
-
add
Adds aPlurlStreamHandlerFactoryto aninstalledplurl implementation. If there is no plurl implementation installed then anIOExceptionis 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 gotremoved.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
Removes aPlurlStreamHandlerFactoryto aninstalledplurl implementation. If there is no plurl implementation installed then anIOExceptionis 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
Adds aPlurlContentHandlerFactoryfrom aninstalledplurl implementation. If there is no plurl implementation installed then anIOExceptionis 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 gotremoved.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
Removes aPlurlContentHandlerFactoryfrom aninstalledplurl implementation. If there is no plurl implementation installed then anIOExceptionis 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
-